All process flows must begin with a trigger - it’s this that determines when and how frequently the process flow will run. For this reason, all new process flows are created with a trigger shape already in place. You should edit this shape to apply your required settings:
Having accessed settings for a trigger shape, you can select the required trigger type - this determines any subsequent options that are displayed:
Currently, schedule, webhook, and event listener trigger types are available.
The trigger webhook option can be used if you want to trigger a process flow whenever a given event occurs in your third-party application.
When you choose to add a webhook to a process flow trigger shape, a Patchworks webhook URL with built-in authentication is auto-generated. This URL must be added to your third-party application, so it knows where to send event data.
How you use webhooks is driven by your business requirements, and the capabilities of your third-party application. For example, your third-party application might send a webhook which includes a batch of orders to be processed in the body, or the webhook body might simply contain a notification message indicating that orders are ready for you to pull.
Patchworks webhook URLs are generated in the form:
For example:
The {{webhook_id}} is a Patchworks signature which is generated as a random hash (that doesn't expire). This provides built-in authentication for our URLs however, they should still be kept private.
The default response for a successful webhook trigger is a status code of 200, with the following body:
If required, you can customise this response.
Follow the steps below to add a new webhook trigger.
Step 1 Click the settings icon associated with the trigger shape in your process flow:
Step 2 Click the add new webhook button:
...a unique Patchworks webhook URL is generated:
Step 3 Copy this URL and paste it into your third-party application.
The documentation for your third-party application should guide you through any required setup for webhooks.
Step 4 If you want to customise the response for your webhook, click the edit icon associated with the URL and make required changes. For more information please see Customising your webhook response.
Step 5 Build the rest of your process flow as needed to handle incoming data from your defined webhook(s).
Step 6 Make sure that your process flow is deployed and enabled - webhooks will not be received if this isn't done.
If required, you can change the default response for your webhook by selecting the 'edit' icon associated with the URL - for example:
Here, you'll find options to select an alternative status code and specify new body text:
Here you can:
Use the status code dropdown field to select the required response code.
Enter the required text in the body field.
Select the required format for your body content (choose from JSON, XML or Plain text).
Trigger schedule options are used to schedule the associated process flow to run at a specified frequency and/or time. Here, you can use intuitive selection options to define your requirements or - if you are familiar with regular expressions - use advanced options to build your own expression.
Trigger schedules are based on Coordinated Universal Time (UTC).
Schedules can be defined based on the following occurrences:
Define a schedule to run every x minutes - for example:
Define a schedule to run every x hours - for example:
Define a schedule to run on selected days of the week at a given start time - for example:
Use the every dropdown list for quick daily presets, or define custom settings:
Define a schedule to run on selected days of the month or weeks, for selected months, at a given start time - for example:
Use the every dropdown list for quick monthly presets, or define custom settings:
If you are familiar with cron expressions, you can select this option to activate the cron expression field beneath and enter your required expression directly:
Patchworks supports the 'standard' cron expression format, consisting of five fields: minute, hour, day of the month, month, and day of the week.
Each field is represented by a number or an asterisk (*) to indicate any value. For example:
0 5 * * * would run at 5 am, every day of the week.
Extended cron expressions (where six characters can be used to include seconds or seven characters to include seconds and year) are not supported.
Follow the steps below to add a new trigger schedule.
Step 1 To add a new schedule, click the add new schedule button:
Step 2 Select an occurrence.
Step 3 Define your required settings for the occurrence.
Step 4 Click save to save this schedule. The schedule is added to the shape - for example:
You can add a single schedule, or multiple schedules. When you add multiple schedules, ALL of them will be active.
Event connectors can trigger process flows by listening for events that are published to message queues/topics by a message broker (e.g. RabbitMQ).
Once an event connector is configured, it becomes available for use as a process flow trigger.
New event connectors are available for selection in process flow trigger shapes as soon as they are saved successfully.
ALL messages published to selected queues/topics are passed through to the process flow.
Follow the steps below to add an event connector as a process flow trigger.
Step 1 Click the settings icon associated with the trigger shape in your process flow:
Step 2 Click the add new event listener button:
...event options are displayed:
Step 3 Select a broker from the list (all configured event connectors are available for selection):
Step 4 Select a queue from the list - all configured message queues/topics for the selected broker (i.e. event connector) are available for selection:
Step 5 Save the shape settings.
