The API is a powerful tool to programmatically set up and manage flows to a very detailed extent. From a manager perspective, as everything is done programmatically, it can be difficult to get updates to a flow from an external system without waiting for a timed auto update function or similar.
Requesting an update from the flow management page, by triggering a webhook, enables an integration to perform custom actions, such as calling a GET- or a POST endpoint or triggering a series of predefined events such as an update routine.
An external source can be added to a flow either in-app on the flow management page or via the API. An external source is set up using a reference, the reference could be a unique identifier used at the external system to identify the exam or the source data.
When a manager requests an update on the flow, a webhook is triggered with a requestId, a flowId and the flow code in the payload. Subscribing to the webhook, the external integration can listen for requests on the attributes delivered in the payload. Triggering the webhook, changes the flow update state in-app to Sync Requested. The API can be used to end the update cycle, by setting the state to “completed”. This updates the flow update state in-app to Complete.
Valid Inputs for the Reference Field
| Characters | Regex |
|---|---|
| 09azAZ,.;;:| |
^[0-9a-zA-Z\-_,.;:|]+$ |
Cases
After the initial flow set up, a reference is added either manually by the manager or via the API using POST /flows/{flowId}/external-sources. A manager then triggers the External Source webhook, forcing, in this case, an update routine to update the flow with external data:
The update routine can start every time the webhook triggers, thus giving a manager the option for near real-time updates with external data.
After the update routine has completed, POST /flows/{flowId}/external-sources/{flowExternalSourceReference}/sync/done is used to set the in-app status to Complete.
A newly created flow does not contain any external data, and as such would need an external integration to feed data onto the flow. Feeding data onto the flow from an external integration would require a unique flow identifier, this could be the flowId or the flow code from the webhook payload.
On a manually created flow, a manager triggers the webhook and the integration picks up the payload, looking for known values. From there, the integration can trigger the flow set up routine, thus enriching the flow with external data.
After the flow set up has completed, POST /flows/{flowId}/external-sources/{flowExternalSourceReference}/sync/done is used to set the in-app status to Complete.
Some assessments may be identical but split up in the backend, such as Class A and Class B. A manager can merge them into a single flow by adding multiple external sources. This allows the manager to choose whether to synchronise all or only a single source. References are added using POST /flows/{flowId}/external-sources:
Participants can be allocated to a reference to manage Class A and B separately, while added to the same flow. This makes it simpler to separate the participants in the middleware, while still keeping the flow management to a minimum:
To allocate participants, the POST /flows/{flowId}/external-sources/{flowExternalSourceId}/allocations/participants endpoint is used. The request body is a list of participant IDs to be allocated to the reference.
It is also possible to remove an existing allocation using either DELETE /flows/{flowId}/external-sources/{flowExternalSourceId}/allocations/participants/{participantId}.
Or all allocated participants using DELETE /flows/{flowId}/external-sources/{flowExternalSourceId}/allocations.