Task catalogue / Workflow
Workflow
Verified against Flow 5.0.0-beta.39
On this page
The Workflow category has 12 tasks. Each entry shows the task's latest revision, the one the palette adds. See Reading an entry.
Note
The palette lists For each first in this category. It isn't a catalogue task: it repeats a task once per item of a list. See For each.
Acquire Lock
This task attempts to obtain a lock with the specified name. If no other workflow in the team is using a lock with that name, a lock with that name and is created. If another workflow in the team is using a lock with the specified name, the current workflow waits until the lock is available.
- Slug:
acquire-lock - Type:
acquirelock - Revision: 2
- Image: None. Flow runs this task itself.
Note
Revision 1 says Timeout is in seconds and defaults it to 300, but Flow reads it in milliseconds, so the lock expires after 300 milliseconds. Revision 2 says milliseconds and defaults to 300000, which is 5 minutes. Upgrade a node pinned to revision 1 in the editor.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Lock Name | key |
Text | Yes | A value to identify the lock. | |
| Timeout | timeout |
Number | Yes | 300000 |
Duration before the lock expires, in milliseconds |
No results.
Example
Let only one run in the workspace deploy to an environment at a time. A run that reaches the lock while another holds it waits its turn.
| Field | Value |
|---|---|
| Task name | lock-env |
| Lock Name | deploy-$(params.environment) |
| Timeout | 900000: 15 minutes in milliseconds, longer than the deploy takes |
For a run with environment set to production, the lock is named deploy-production. A run that finds it held shows Waiting and tries again every 5 seconds, without using up its timeout. Link the deploy tasks after lock-env, then a Release Lock task with the same Lock Name. The lock is shared by every workflow in the workspace, and is freed when Release Lock runs, when the run ends, or when Timeout passes, whichever comes first. The task returns no results.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| A second run gets the lock while the first is still working | Timeout passed. It's in milliseconds, although revision 1 says seconds, so 300 there lasts 300 milliseconds. |
Set Timeout in milliseconds, longer than the locked tasks take. Upgrade a node that's still on revision 1. |
| The task stays Waiting | Another run in the workspace holds a lock of that name, from this workflow or any other. | Find the run holding it. The lock is freed when that run releases it or ends, or when its Timeout passes. |
The task fails with acquirelock requires a key and a timeout. |
Timeout has no value, or isn't a number once references resolve, such as a parameter that holds 15m. |
Give Timeout in milliseconds, in digits only. |
Manual Approval
Pauses workflow until approval is actioned. If no approver group is specified then this task can be approved by anyone in the team, and only requires 1 approval.
- Slug:
manual-approval - Type:
approval - Revision: 2
- Image: None. Flow runs this task itself.
Note
The hint for Number of Approvals (optional) says "Only respected if Approver Group is specified", but Flow applies the number whether or not you choose an approver group. Leave it blank when one approval is enough. See Number of Approvals applies without an approver group.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Approver Group (optional) | approverGroupId |
Select | No | Limit the approvers to the members in this group | |
| Number of Approvals (optional) | numberOfApprovals |
Number | No | Only respected if Approver Group is specified |
Results
| Name | Description |
|---|---|
approvalStatus |
The status of the approval task, can be approved or rejected. |
approvalDate |
Date and time of the action |
approvalUserName |
Username of the approver |
approvalUserEmail |
Email address of the approver |
approvalComments |
Additional comments added by the approver |
Example
Pause a release for one person's sign-off, then let a later task report who decided. This is the approve task in Pass results between tasks with an approval.
| Field | Value |
|---|---|
| Task name | approve |
| Approver Group (optional) | Blank, so any workspace owner or editor can decide |
| Number of Approvals (optional) | Blank, so one decision completes the task |
The task returns:
| Result | Value |
|---|---|
approvalStatus |
approved or rejected |
approvalDate |
When the approver acted, in ISO 8601 UTC, such as 2026-11-04T05:12:44.120Z |
approvalUserName |
The approver's name |
approvalUserEmail |
The approver's email address |
approvalComments |
The approver's comment, or empty |
The run waits at approve, without using up its timeout, until someone selects Approve or Reject on Actions, on Home or on the run page. Approve ends the task Succeeded and Reject ends it Failed; both set all five results. A later task reads them as $(tasks.approve.results.approvalStatus). See Actions.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| After Reject, the next task shows Skipped and the run ends Failed | A rejection fails the task, and a success link runs the next task only when the task succeeds. | To carry on either way, use an always link and read approvalStatus in the next task. To act only on a rejection, use a failure link. |
| With no approver group, the approval waits for more decisions, such as 0/2 approvals | Flow applies Number of Approvals (optional) with or without a group, although its hint says otherwise. | Leave it blank when one decision is enough. See Number of Approvals applies without an approver group. |
| Someone sees the approval but can't decide it | Readers can't decide. When the task names an approver group, only its members can, and never a machine token. | Give them the editor role, or add them to the group under Manage workspace › Approver Groups. |
| Approver Group (optional) is disabled and reads "No approver groups configured for this workspace." | The workspace has no approver groups. | Create one under Manage workspace › Approver Groups, then choose it. |
Manual Task
Pauses workflow until manual task is actioned.
- Slug:
manual-task - Type:
manual - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Instructions | instructions |
Text Area | Yes | Steps for end user to follow to perform manual task. |
No results.
Example
Ask someone to take a database snapshot by hand before a migration runs.
| Field | Value |
|---|---|
| Task name | snapshot |
| Instructions | The steps below, in Markdown |
Instructions
Take a snapshot of the `orders` database before the migration.
1. Name it `pre-migration-$(params.version)`.
2. Wait until it shows **Available**.
3. Select **Complete Successfully**. If the snapshot fails, select **Complete Unsuccessfully**.The run waits at snapshot, without using up its timeout, until an owner or editor opens it under Actions › Manual Tasks and selects Complete Successfully, which ends the task Succeeded, or Complete Unsuccessfully, which ends it Failed. Flow fills in $(params.version) before the instructions are shown. The task returns no results.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| The run stays Waiting at the task | Nobody has completed it, and a manual task waits indefinitely. | An owner or editor completes it under Actions › Manual Tasks, or with Action on the run page. |
| After Complete Unsuccessfully, the next task shows Skipped and the run ends Failed | That choice fails the task, and a success link runs the next task only when the task succeeds. | Add a failure link to a task that handles it, such as a notification. |
| Someone sees the task but can't complete it | Readers can't complete manual tasks. | Give them the editor role in the workspace. |
Release Lock
This task releases a lock with the specified name.
- Slug:
release-lock - Type:
releaselock - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Lock Name | key |
Text | Yes | A value to identify as the lock. |
No results.
Example
Free the lock that the Acquire Lock task lock-env took, as soon as the deploy is done, so the next run can deploy.
| Field | Value |
|---|---|
| Task name | unlock-env |
| Lock Name | deploy-$(params.environment), the same as on lock-env |
Link unlock-env after the last task that needs the lock. It frees the lock only when this run holds it, whichever of the run's tasks took it, and succeeds whether or not it freed anything. If a task before it fails and Release Lock is skipped, the lock is still freed when the run ends. The task returns no results.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| Release Lock succeeds, but the next run still waits for the lock | Lock Name doesn't match the Acquire Lock's exactly once references resolve, and Release Lock succeeds when it frees nothing. | Give both tasks the same value. Lock names are case-sensitive. |
| The lock stays held while the run waits at a later task, such as an approval | A lock is freed when Release Lock runs or the run ends, not when the locked tasks finish. | Link Release Lock straight after the last task that needs the lock. |
Run Custom Task
Run a trusted custom container as a task
- Slug:
run-custom-task - Type:
custom - Revision: 1
- Image: The image you set on the node.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Image | image |
Text | No | Enter a valid container image reference | |
| Command | command |
Text Area | No | New line delimited container command. You can access environment variables using $(variable) notation. | |
| Arguments | arguments |
Text Area | No | New line delimited container arguments. You can access environment variables using $(variable) notation. | |
| Script | shellScript |
Text Editor - Shell | No |
No results.
Run Scheduled Workflow
This task runs the selected workflow one time in the future. It only schedules the workflow, it does not wait for it to execute. Additionally you can pass in workflow parameters if they have been defined.
- Slug:
run-scheduled-workflow - Type:
runscheduledworkflow - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Workflow Reference | workflowRef |
Text | Yes | The reference (or slug) of the Workflow to schedule. | |
| Future In | futureIn |
Number | Yes | How many futurePeriod units from now the Workflow should run. | |
| Future Period | futurePeriod |
Text | Yes | The unit futureIn is measured in: minutes, hours, days, weeks, or months. | |
| Timezone | timezone |
Text | Yes | The timezone time is set in (e.g. America/New_York). Only applied for days, weeks, and months. | |
| Time | time |
Text | Yes | The 24-hour clock time (e.g. 14:30) to run at. Only applied for days, weeks, and months. |
No results.
Run Workflow
This task runs the selected workflow separately. It only triggers the workflow, it does not wait for completion. Additionally you can pass in parameters to the workflow if they have been defined.
- Slug:
run-workflow - Type:
runworkflow - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Workflow Reference | workflowRef |
Text | Yes | The reference (or slug) of the Workflow to run. | |
| Wait for the child run to finish | wait |
Boolean | No | false |
When enabled, this task waits for the child run and takes its terminal status: the task succeeds only if the child run succeeds. |
No results.
Example
From a release workflow, start the workflow deploy-service for one environment, wait for it, and use the URL it returns.
| Field | Value |
|---|---|
| Task name | deploy |
| Workflow | Deploy service, chosen from the list. Flow stores its name, deploy-service. |
| Wait for the child run to finish | On |
| The child's parameters, such as Environment | $(params.environment) |
The task returns:
| Result | Value |
|---|---|
workflowRunRef |
The child run's ID |
url |
The url result the child set with a Set Result Parameter task, once the child succeeds |
Once you choose a workflow, its parameters appear in the form. deploy shows Waiting until the child run ends, then takes its status, and a later task reads $(tasks.deploy.results.url). With Wait for the child run to finish off, the task succeeds as soon as the child starts, with only workflowRunRef. See Child workflows.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| The task succeeds at once, and a later task gets nothing from the child | Wait for the child run to finish is off, the default, so the task returns only workflowRunRef. |
Turn it on. |
The task fails with ChildRunFailed, and a message such as Child run <id> ended failed |
With waiting on, the task takes the child's status, and the child didn't succeed. | Select View Activity on the task to open the child run and see why. |
| The child fails, or a task in it gets an empty value | The child gets only the values its node passes. The parent run's parameters aren't handed down. | Fill in the child's fields on the node, with references such as $(params.environment). Pass a secret the same way. |
The task fails with NestingDepthExceeded and starts nothing |
Runs nest at most 5 deep by default. | Flatten the chain of workflows, or ask an admin to raise Admin › Settings › Run limits › Maximum Child Workflow Nesting Depth. |
Set Result Parameter
Set a Result Parameter on the Workflow. These are then available in the workflows activity.
- Slug:
set-result-parameter - Type:
setwfproperty - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Name | output |
Text | No | Only alphanumeric, underscore, dash, and period characters allowed | |
| Value | value |
Text | No |
No results.
Set Workflow Result Status
Override Workflow Execution Status
- Slug:
set-workflow-result-status - Type:
setwfstatus - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Status | status |
Select | No |
No results.
Sleep
Sleep for specified duration in milliseconds
- Slug:
sleep - Type:
sleep - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Duration | duration |
Text | No |
No results.
Example
Wait 2 minutes after a deploy, so the service is up before a smoke test runs.
| Field | Value |
|---|---|
| Task name | wait-for-start |
| Duration | 120000, which is 2 minutes in milliseconds |
The task shows Waiting, then Succeeded within about a second of its due time. The wait doesn't count towards the run's timeout. Duration can be a reference, such as $(params.delay-ms). The task returns no results.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| The sleep ends almost at once | Duration is in milliseconds, so 120 waits 120 milliseconds. |
Multiply seconds by 1,000: 120000 is 2 minutes. |
| The task stays Running instead of Waiting, and never ends | Duration isn't a whole number: it's blank, has a unit such as 2m, or is a reference that resolved to text. |
Cancel the run. Enter digits only, then save a new version. |
Switch
Create a Switch Component
- Slug:
switch - Type:
decision - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Value | value |
Text | No |
No results.
Wait For Event
Wait for an event from an external system to resume workflow execution. The event can be a webhook or a Cloud Event.
- Slug:
wait-for-event - Type:
eventwait - Revision: 1
- Image: None. Flow runs this task itself.
Parameters
| Label | Name | Type | Required | Default | Helper text |
|---|---|---|---|---|---|
| Topic | topic |
Text | No |
No results.