Building Workflows

Workflows connect data between your users' apps and your application

Introduction

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.

When to use Workflows

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

Creating Workflows

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:

pageTriggering Workflows

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.

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.

Requests, Integration Actions, and Function Steps can be configured to "Continue workflow if step fails" or to use Auto-Retries.

Testing Workflows

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.

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.

Deploying Workflows

You can push workflows live to your customers by pressing the purple Deploy button in the top-right corner of the Workflow Editor.

Editing Workflows

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.

Workflows and the Connect Portal

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.

What's Next

Throughout the articles in this section, we'll provide a detailed overview of how to start building your own Workflows in Paragon.