Workflows - Multi-step API calls

Key Concepts

A workflow is a sequence of API calls that execute one after another. The calls can be completely independent or use variables extracted from an earlier call and passed to a later one in the sequence. Just like a plain API call, workflows are deployed to be run periodically from agents in the same way as individual API calls.

📘

Example Workflow

1. Make an API call to create a user in a particular system
2. Extract the user ID from the returned payload
3. Make an API call to create a record associated with the user account for the user ID
4. Extract the record ID from the returned payload
5. Make an API call to obtain the record associated with the user account for the user ID and the record ID
6. Validate the returned payload using API Conditions to demonstrate that the record was created successfully
7. Make an API call to delete the record associated with the user account for the user ID and the record ID
8. Make an API call to obtain the record associated with the user account for the user ID and the record ID
9. Validate the returned payload using API Conditions to demonstrate that the record was deleted successfully (trying to obtain a deleted record should lead to the returned payload containing an error message)
10. Make an API call to delete the user account associated with the user ID

❗️

Variables in workflows

A variable used in a workflow only persists for use in that workflow. We provide pre-set variables for services like DATE and TIME, and global variables that can be used to handle externally generated tokens and IDs.

Creating a Workflow

Clicking on the Workflows item on the left-hand menu invokes the Workflow page.

If you already have created some workflows, they will be listed on the page.

Clicking on the +Create New Workflow button invokes the Edit Workflow dialog.

You can enter a more memorable name for the workflow. You can choose an API call from the dropdown or click +New API Call to create the API call from scratch in the usual way.

Variables and Conditions

Variables can then be added to calls and conditions added to allow you to stop workflows in the event of a failure.

See the section on assertions and conditions for more details on how to handle these situations.

Editing a Workflow

You can edit a workflow by clicking on the Edit button for a workflow in the list. This shows API calls that make up the workflow and the variables, if any, that are set at each stage of the workflow.

The variables extracted from earlier stages can be used as inputs in the later stages. The last stage will not have any variables set as there are no further stages for any variable to be used in.

If you click on the Conditions button, you can edit the conditions for the component of the workflow.

The Property Path, such as ['items'].0.id, is a reference to a value in the returned JSON payload. In this example:

• ['items'] refers to the collection of items returned in the JSON payload
• 0 is the first entry in entries (items are counted from 0)
• id is the entry with the name id

A variable with the name ID is set to the value of ['items'].0.id.

Using a Variable

Once you have set your variable - in this case, ID - you can use that variable in later calls in the workflow either as part of the URI or as a parameter using the following notations:

%%ID%%
__ID__

For instance, if a URI or parameter contained a hardwired ID such as 113231459, this could be substituted for the variable extracted from an earlier call in the workflow by replacing 113231459 by %%ID%% or ID (two underscores before and after the name as escape characters). Similarly, if you had extracted a token with the name TOKEN from a call in the workflow, this would be substituted into the URI as %%TOKEN%% or TOKEN.

Scheduling Workflows

A workflow can be scheduled in exactly the same way as an individual API call.

Workflow Results

You can examine a list of workflow results.

Clicking on View brings up a summary of the results for each of the components for that particular invocation of the workflow. You can drill down further by clicking on View Results or View API Call to see details of the API call and the result of the call in that workflow invocation.