Building Workflows
Workflows connect data between your users' apps and your application
Last updated
Workflows connect data between your users' apps and your application
Last updated
Once your users have connected their third-party app accounts in the Connect Portal, you can build workflows that connect data between your application and your users' apps. Paragon's visual workflow builder allows you to create custom integrations that your users can activate in their integrations.
Workflows are durable, retriable jobs that can be triggered by your application or by events in your user's connected accounts. Workflows can be used to build out logic for your integration in Paragon's scalable, high-availability runtime.
Here are some common step types that can get you started building workflows:
Integration Actions: Perform an action in your users' connected app account, like sending a Slack message or querying contacts from Salesforce
Requests: Make a request to any API, such as sending data to your application
Functions: Write custom JavaScript to transform data or perform custom business logic, using npm libraries as supported
Conditionals: Add conditional branching logic
Fan Out: Iterate in parallel over a list of data and reduce results in downstream steps
Along with the Connect API, Workflows are one of two primary ways to build integrations with Paragon.
In general, Workflows are the way that most integrations are built with Paragon. When deciding when to use Workflows or the Connect API, Workflows are often best suited for common use cases including:
Pushing data from your application to your users' apps
Receiving new or updated data from your users' apps (Webhooks)
Allowing your users to configure integration options with custom fields
Enabling non-engineering teams (e.g. Product or Client Services teams) to configure integrations without writing code
Here are examples of Workflows for a few common integrations:
Slack: Send notifications from your application to Slack
Salesforce: Sync contacts from your application to Salesforce
HubSpot: Sync contacts HubSpot to your application
Google Calendar: Create Google Calendar events from events in your application
You can create a Workflow by selecting an integration and clicking Create Workflow.
Naming your workflow
The Workflow Editor will appear and allow you to name your new workflow (click in the workflow title "New Workflow" and type to rename).
Selecting a trigger
Every workflow begins with a trigger. Select a trigger that matches how this workflow should begin its execution.
Workflows can only have one type of trigger. If you need to create a two-way sync between an integration and your application, you would create two workflows: one workflow to push updates from Integration -> Your App and another workflow to push updates from Your App -> Integration.
See the page below for full information on defining and using triggers:
Adding steps
Beneath a trigger, you can build out your workflow logic as a series of steps. Steps can represent Integration Actions, API requests, custom functions, or other control flow elements in your workflow.
Requests, Integration Actions, and Function Steps can be configured to "Continue workflow if step fails" or to use Auto-Retries.
You can insert data from any upstream step in the Workflow Editor with the Dynamic Variable Menu. To access the Dynamic Variable Menu, click into any text input box, type two left curly braces {{, then select the desired step and specific reference to pull data from.
Note: When testing steps or workflows from the Workflow Editor, the data output returned is partial.
Here are some limitations to the test data displayed in the Workflow Editor:
Arrays are truncated to 20 items maximum
Paginated requests will only send 3 requests maximum
The above limitations improve the performance of the Workflow Editor as you build your workflow and reference variables between steps.
To test the workflow without these limitations, use a live Connected User to connect an integration in the Connect Portal and enable the workflow. Once you trigger the workflow for this user, the execution will appear in Task History, where you can monitor the results and view the full input and output data.
You can push workflows live to your customers by pressing the purple Deploy button in the top-right corner of the Workflow Editor.
You can edit deployed workflows by making changes directly to the Workflow Editor. The changes will not affect the live workflow changes until you redeploy the workflow.
To pull deployed workflows from your customers, click the purple “Deploy” button in the top-right corner of the Workflow Editor, then select “Undeploy”.
Workflows that you've deployed for an integration will appear in that integration's Connect Portal under the Configuration tab.
There, your users can choose which workflows they want to activate for that integration. You can also provide options for your users to configure their workflow settings. For example, if you have a Slack workflow that sends notifications to your users' workspaces, you may want to provide them the option of which Slack channel they want to send notifications to.
See Workflow User Settings for an overview of how to provide user-facing options for your users to configure their workflow settings.
Throughout the articles in this section, we'll provide a detailed overview of how to start building your own Workflows in Paragon.
Click the "+" button underneath any step to add a new step. You can also right-click any step to add a step immediately downstream of the step, duplicate the step, or remove the step from the workflow.
Individual steps in a workflow can be tested as you build them. Each step has a Test Step button () in the sidebar that executes the step as the Preview User (the user connected in the Preview page of your integration).
You can use the Test Workflow button () when you want to test a workflow with all steps to completion.
