Triggering Workflows
Triggering workflows in Paragon
All Paragon workflows start with a trigger, which determines when the workflow will run and how data is passed into the workflow. Available workflow trigger types include:
In this section, we'll walk through common use cases for each trigger type and how you should use them.
App Events are custom events that are sent programmatically from your application via the Paragon SDK or API to trigger Workflows. In general, App Events are useful for triggering workflows that map data from your application to your users' apps.
For example, you might send a "Contact Created" App Event from your application to trigger a Workflow that creates a matching contact in your users' Salesforce CRM.
Once defined, an App Event can be used to trigger multiple workflows. This is useful in cases where you may want the same event to trigger similar workflows across different integrations.
For example, the same "Contact Created" event in the above example could trigger one workflow that creates a contact in Salesforce, and another workflow that creates a contact in HubSpot. This allows you to easily provide the same integration functionality across different providers without any additional engineering.
To create an App event, select the App Event trigger type in the Workflow editor and choose "Create new app event" in the menu under Choose an App Event.
Next, enter the name and event schema of your App Event. The event schema that you enter here should be an example payload sent from your application to Paragon. The event schema defined here will be used as test data for any workflows triggered by this App Event.
The event schema must be a valid JSON object, and can contain any arbitrary JSON.
App Events can be sent from your application using the Paragon SDK or REST API. In both cases, you must pass two parameters:
- name - the event name defined in your App Event
- payload - the event payload that should match the event schema defined in your App Event
See the code examples below for how to send App Events using the Paragon SDK or API.
JavaScript SDK
REST API
var eventName = "Contact Created";
var eventPayload = { "name": "Brandon", "email": "[email protected]" };
// Called once during your user's session
paragon.authenticate("project-id", <Paragon User Token>)
// Trigger the "Contact Created" App Event
paragon.event(eventName, eventPayload)
// Trigger the "Contact Created" App Event
POST https://api.useparagon.com/projects/<Paragon Project ID>/sdk/events/trigger
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
{
"name": "Contact Created",
"payload": {
"name": "Brandon",
"email": "[email protected]"
}
}
When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.
If you need to edit your App Events' name or event schema, you can visit the App Events tab in your Paragon dashboard to view and manage your app events.
The Request trigger can be used to run workflows by sending it an HTTP request or webhook. This option also allows passing data from the incoming request into the workflow. For example, when a lead is created in your app, you could trigger a workflow that sends the lead data to your customer's CRM and provides a custom response if it goes through.
Request-triggered workflows can be triggered by sending an HTTP
POST request to their unique URL. You can manually enter the expected query parameters (Params), headers (Headers), and body parameters (Body) to use as variables by other steps in the workflow.JavaScript SDK
REST API
// Called once during your user's session
paragon.authenticate("project-id", <Paragon User Token>)
// Trigger the "Lead Created" workflow
await paragon.workflow("<workflow_id>", {
"body": {
"email": "[email protected]",
"first_name": "Bowie",
"last_name": "Foo"
}
});
// Trigger the "Lead Created" Workflow
POST https://zeus.useparagon.com/projects/<Paragon Project ID>/sdk/triggers/<Workflow ID>
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Bowie",
"last_name": "Foo
}
There are two ways to define what data you expect to be sent by incoming requests to the workflow:
- Manually entering the expected request data
- Automatically detecting data by sending a test request
Manually entering request data is usually the best option if you know what data will be sent by the incoming request (e.g. you're sending it from your own app). This option allows you to manually enter the expected query parameters (Params), headers (Headers), and body parameters (Body). Any data entered here can be used as variables by other steps in the workflow.
You can also choose to validate the incoming request data. For example, you can enforce that query parameters should be required, that headers should match an expected value, or that body parameters should match an expected type. If the incoming request doesn't meet your workflow's validation rules, the workflow will automatically return an error response.
Automatically detecting data from a test request is usually the best option if you have a large amount of data to pass through. When you choose this option, the test shelf will appear and display a test URL at the bottom of the step sidebar. By sending a request to the test URL, Paragon will automatically detect data from the request and display it in the test shelf. Here, it'll be saved as test data that can be used as variables by other steps in the workflow.
Once you're ready to start using a Request workflow in production, click the "Deploy" button in the top-right of the screen to deploy the workflow. This will set the workflow's endpoint URL live and make it available for requests to be sent to.
Webhook triggers can be used to run workflows based on events in your users' apps. For example, you might want to trigger a workflow whenever new contacts are created in your users' Salesforce account to sync your users' Salesforce contacts to your application in real-time.
You can find the full list of supported Webhook Triggers below. If you don't see the integration you're looking for, let us know and we'll be happy to add it to our roadmap if we're not already working on it.
Integration Enabled triggers can be used to run workflows when a user initially activates your integration. For example, you might want to trigger a workflow that syncs all leads from your customer's CRM to your application once they've enabled the integration.
The Scheduler trigger is used for workflows that should run automatically at a scheduled time or interval.
The Scheduler trigger provides the following scheduling options:
- Seconds (e.g. every 5 seconds)
- Minutes (e.g. every 30 minutes)
- Hourly (e.g. every hour at 15 minutes past the hour)
- Daily (e.g. every 2 days at 9:00 am)
- Weekly (e.g. every Monday at 12:00 pm)
Once deployed, the workflow will run automatically at the designated time for all users who have activated the workflow in their Connect Portal.
Last modified 13d ago