Skip to end of metadata
Go to start of metadata

Beta notice

The information below is currently in Beta-Status for early adopters and testers. It will change over the next weeks and month until a stable version is available.


This page describes how you, as a developer, can develop your own Add-Ons including your own steps and templates. 

Workspaces

The Developer-Accounts use Workspaces as a basis to build Add-Ons and Steps. An Add-On is represented by a Workspace basically. 
A workspace is the top-level container which contains:

  • your developed steps
  • Accounts
  • Projects
  • Flows
  • Datastores
  • Schemas
  • Mappingsets


A workspace per Add-On

If you want to develop a new functionality, you need to create a new Workspace. This workspace can than be published as an Add-On which has the same name as the workspace.  

Create a new Development Workspace

  • Create a new Workspace



Create a new Step 

The first thing is to create a new Step which performs some task and has Inputs and Outputs. 

Steps are Flows

The most important thing to know is, that the step you are creating is a Flow under the hood.

You don't need a programming language to create new Steps. We have made it possible that you can just use your existing knowledge of building Flows, to build steps.



Give your Step a globally unique name e.g. [NameOfMyAddOn]-[NameOfStep]



You have created your first step.

Two things were created for your automatically:

  1. The FlowStep itself
    The new FlowStep is linked to a Flow in the background. This Flow will contain the business logic which your FlowStep will execute. 
  2. Test-Flow
    In order to use your FlowStep you will always need a flow which uses it. We just created such a Test-Flow for your automatically. This test-Flow already has your FlowStep added, but of course initially it does nothing. 


Start with the TestFlow

We suggest the following approach:

  • Always start opening your Test-Flow first.
  • From there you can already start building a process which uses your new step as if it already existed.
  • You can go into your FlowStep (using the Edit Flow-Step button) from your Test-Flow and back to add life into your step and always test the functionality from your Test-Flow.

This approach has the following advantage:

  • You are building your step exactly how it will be used in the future by the user.
  • You are already using your own step from the beginning and build it step by step and fill it inputs and outputs.



Your Test-Flow

When you go into the Test-Flow for the first time it looks like this and does nothing. 


Planning your FlowStep and Test-Flow

Let's assume our FlowStep should do the following:

  1. Fetch Product information from some REST-API
  2. The step should have an Input with a simple filter to decide which products to fetch
  3. The output should be a SPREADSHEET with the product data.

Then, our Test-Flow should do the following: 

  1. Call our FlowStep to fetch the products
  2. the Spreadsheet with the products should be written to a CSV-File and sent to us via Email


That means the we can already build our Test-Flow and pretend our FlowStep is already working (which it is not yet). 
We add a SpreadsheetCSVWriter and EmailSend Step.


Start building the FlowStep

Now we start filling our FlowStep. Click on the Edit Sub-Flow Button.
This brings you directly into your new FlowStep. It is empty of course. 

Let's start adding a few Steps to do something.

Remember we want to fetch product data from a REST-API and return the products as SPREADSHEET. Let's use the following steps for this:

  • APICall (to make the REST-API call)


Create Output-Variable

As we want our step output to be a SPREADSHEET we need to give the Flow also an Output-Variable. This will become the output of the step later. 

Give the output-Variable a name (we just used output here. We could have used also e.g. products.) and choose an output of a Step which should be the output of this Flow. As we want a SPREADSHEET output, we are using the output of the JSON2Spreadsheet step. 


Input Variable

Remember we wanted our step to have a filter where you can control which products to fetch. 
Let's add a Flow-Variable with a simple dummy filter option. We can fine tune this later. It is just to see something now. 


Save the variables.

After saving the filter dropdown should have 2 new values.


Optional / required and public / private variables

It is possible to control more aspects of Flow Variables:

  • optionality (controls wether the variable is required or optional)
  • visibility (controls wether the variable can be see from calling flows e.g. PUBLIC vs. PRIVATE)


Optionality

OptionalityDescription
optional field (default)
  • the variable does not need to be filled by the caller.
  • if a default value is specified it will be used if the caller does not specify a value
required field
  • the variable needs to be filled by the caller
  • if the caller does not specify the variable the flow will throw an error indicating the this required field is not populated

Visibility

VisibilityDescription
PUBLIC (default)
  • the flow variable can be seen from calling flows
PRIVATE
  • this variable is only visible for the Flow/Step itself
  • the caller does not see this variable
  • you can use it like private variables in a programming language
    • e.g. if you need a variable which you use in many steps of your flow, but you don't want
      others to override it


Sync Flow and Step and check what we just did

One important concept to understand is how the Flow and the FlowStep are linked. 
If you are working on your Flow the FlowStep in the background is not automatically updated with the changes.
You need to manually sync it using the button below: 

When the button is red, then a Sync is required. If it is not red, then no sync is required.
Sync and go back to our Test-Flow to see how it looks from there. 

Hint: On the top you see the breadcrumb with a link to your Test-Flow. 


Check how the Step looks in the Test-Flow

Back in our Test-Flow we go into the Step-configuration.

As expected our Step now has a filter-Dropdown menu we have just created. 
 


You can also check if the Step has the SPREADSHEET output. Click on the small arrow below the step to see the outputs. 


To complete our Test-Flow we just pass the output SPREADSHEET of our Step into the SpreadsheetCSVWriter, so that the data will be written to a CSV-file.

Conclusion

We have created the main building blocks of a new Step. 

  • Our step has an input (the filter dropdown)
  • Our step has some steps doing something (URLDownload and JSON2Spreadsheet)
  • Our step has an output (the SPREADSHEET from JSON2Spreadsheet)

Our Test-Flow

  • use the FlowStep
  • can see the input (the filter-dropdown)
  • can see the output (the SPREADSHEET)
  • consumes the output SPREADSHEET to write it into a CSV-File

What next?

Obviously our FlowStep is not doing anything useful yet. But it really does something useful, the Test-Flow can already work with it. 
Just go ahead and build your FlowStep, do a real REST-API call, parse the JSON-Response etc. 


 

Using Add-Ons in your own account

When development is finished and you want to use the steps in another Account (not in your DEVELOPMENT Account) you need to create a PRIVATE Add-On. 
This is in contrast to PUBLIC Add-Ons which can be sold in the App-Store and used by other customers too. (This will be possible in the future)

Give your customers access

Please create support ticket and contact synesty support, if you want to give your customers (or other users) access to your Add-On.
Synesty will check and do quality assurance of your Add-On and Steps. If everything is ok, then Synesty Support provides you with information, how your customers install that Add-On.



When you have created the PRIVATE Add-On you need to assign your steps to it in order to use it. 


After that the step is assigned and appears under Assigned Flow-Steps.


Bugfixing with STAGING and LIVE

Once you have assigned the Step to an Add-On, the Step is ready for release. 
After Synesty QA and Release of your Add-On, your customers can install the Add-On and use the assigned steps in their flows. 


Thus, you want to be more careful when changing your Step, because the change applies to all flows using your step. But you still want to make changes to your step (e.g. Bugfixes), test the changes, but without making the change available to other Flows or customers immediately. 

That's why we introduced the concept of STAGING and LIVE. 

If your Step is live (assigned to an Add-On) all future changes are first only done to the STAGING version. The Sync-Button in the flow will change into Update to STAGING for that purpose. 

Testing of Bugfixes in STAGING

In your Test-Flow you can then select on each Flow-Step if you want to use the LIVE (default) or STAGING version. This allows you to test the change without affecting isolated in your Test-Flow only.
Once you have finished testing you can push the changes from STAGING to LIVE. This can be done in the Add-On Settings of your Workspace.

You can toggle between LIVE and STAGING to test and compare the two version.

Who can use STAGING and LIVE?

Note that only you as the DEVELOPER or creator of the Flow-Step can switch to the STAGING Version. This only works in your account where you have created the Step.
All other Customers will ALWAYS use the LIVE-Version. 


Releasing from STAGING to LIVE

In the Add-On Properties section of your DEV-Workspace you can release the STAGING-Version of each Step to the LIVE version. This is simply done by copying the STAGING-Version over the LIVE-Version. After that LIVE and STAGING are the same. There is also an visual indicator for that.


Versioning

In the future we plan to extend the versioning further so that you can store multiple revisions, so that you could also rollback to a previous revision (e.g. in case of a bug). But at the moment STAGING and LIVE are the only two versions possible.


Public Add-Ons

PUBLIC Add-Ons

PUBLIC Add-Ons will be possible in the future. We will write about it here.


Creating a Service - if your step requires login credentials

If you are building a Step which e.g. interacts with a 3rd party API, then you typically want your step to have an ACCOUNT input field which the user of the step can store under My connections.

For this you need to create a Service


A Service stores the definition of an account-variables like username, password etc.


After you have created the Service and added account variables you can select the service in Flow-Variables of your Flow step.

Assigning a Service to an account

If you want that the Service of your account shows up under My connections, you need to assign the Service to your Add-On.


Creating an account

After you have created the Service and the definition of the account variables it shows up under My Connections and you can create an account.


Then go into your FlowStep and create an Account-variable.


Choose your new Service under Connection. 

Then select the actual account and save the Flow variables.


Using account data in your step

Now as a Step developer, you want to use the variables inside the account in your step. E.g. if your account has user and password fields which you want to use in a APICall step. 

Then the account-sub-variables can be selected.

In this case user is the field "user" of our account definition inside our service. @account is the name of the flow-variable which we called account. Both together are referenced by the freemarker variable ${user@account}

Make sure you always use the + Button on each field. That way you make sure you always get the correct variable name. There is a special case e.g. for the step SpreadsheetURLDownload where the variable is ${meta.user@account} instead of ${user@account}. This is special to SpreadsheetURLDownload step to avoid naming conflicts with the column names of the input-Spreadsheet.


Summary

Let's summarize what we have learned in the guide above:

We learned how to...

  • ... build an own Step called FlowStep.
  • ... test this FlowStep using a related Test-Flow.
  • ... create an Add-On by creating a DEVELOPMENT Workspace.
  • ... prepare the Add-On for release (publish) by adding the FlowStep to the Add-On.
  • ... make changes / bugfixes, test it in STAGING and publish it from STAGING to LIVE.
  • ... create Services and an account-definition in order to use Accounts where users can store login-credentials for your Add-On / FlowStep.

These are the most important building blocks when developing your own steps. 



  • No labels