- 31 Jan 2024
- 4 Minutes to read
- DarkLight
Nested workflows
- Updated on 31 Jan 2024
- 4 Minutes to read
- DarkLight
Use the nested workflow operator to improve the readability, efficiency, and maintainability of complex workflows by breaking them up into reusable modules (subroutines) in the form of nested workflows.
The nested workflow operator can also be used for a variety of other use cases, such as:
- Automated workflow testing (detailed documentation is coming soon).
- Handling workflow execution failures: implement logic to handle failures in a nested workflow subroutine within the main workflow.
Additionally, the nested workflow operator enables seamless information exchange with the parent workflow through input and output parameters, and each run generates an activity log entry with the parent workflow as the event source.
Important to know
Nested workflows used as subroutines in parent workflows are triggered by the parent workflow and require the On-demand trigger that has the Triggered from toggle with two options:
- Anywhere: The workflow can be triggered from the designer, external sources such as Slack or web forms, and is also available as a nested workflow. With this setting, the workflow counts toward the workspace workflow quota.
- Nested only: The workflow can only be used as a nested workflow in parent workflows. With this setting, the workflow counts toward the workspace nested workflow quota.
When the parent workflow is published and running, it will only run published nested workflows (unless an ID of a different revision was specified).
When the parent workflow is in draft mode, it will run the latest version of the nested workflow (published or latest draft).
In this article
More information on nested workflows
Create a nested workflow
There are two ways to create a nested workflow:
- Create a workflow with an on-demand trigger and incorporate it as a nested workflow by using the nested workflow operator (see example).
- Select several steps and click the Create workflow icon to turn them into a nested workflow.
Edit a nested workflow
To test a nested workflow that's draft, the parent workflow also needs to be in draft mode. If the state of the parent workflow is Published, the published version of the nested workflow will be run.
- Move the parent workflow to draft mode.
- Edit the nested workflow.
- To test, trigger either the parent or nested workflow manually.
View the list of dependent workflows
When editing a workflow, avoid breaking changes by checking the list of dependent workflows and updating the ones that will be affected by the changes you're making. Get a list of the published workflows that are using the workflow you're viewing (parent workflows) by clicking the View Affected Workflows icon. Click any workflow on the list to open it in a new tab.
The affected workflows list includes only the direct parent workflows. Repeat the process in case there are multiple levels of nesting.
- Edit the nested workflow.
- View the list of dependent workflows (parents).
- Make changes to the dependent workflows as required.
- Test run the modified workflows. Make sure any parent workflow you run is in draft mode for it to run the draft version of the nested workflow.
- Publish the workflows you modified.
Execution options
These are the optional properties that you can enable for a nested workflow:
- Ignore failure: By default, if a nested workflow fails, the parent workflow execution stops, and its status is set to fail. Select Yes for the parent workflow execution to continue even if the nested workflow fails.
- Wait for output: By default, the parent workflow execution is paused until the nested workflow execution completes. Select No to run both workflows simultaneously. Note that with this configuration, the parent workflow might not have access to the nested workflow output.
Example: create a nested workflow
The example below demonstrates how a workflow can serve as a nested workflow within a parent workflow.
1. Create the nested workflow
A nested workflow is a regular workflow with an on-demand trigger. In this example, the nested workflow will enrich an IP address.
On the Workflows page, click Create Workflow.
- Give the workflow a meaningful name, such as IP Enrichment.
- Select the On Demand trigger and click Create Workflow.
Select the trigger to add input parameters for passing the required data from the parent workflow to the nested workflow. This example uses a short-text field titled IP Address as the workflow aims to enrich an IP address.
Implement the logic to enrich the IP address. Access the IP address by using:
{{ $.event.ip_address }}
Add the Exit operator and define the workflow output. This output will be accessible in the parent workflow upon the completion of the nested workflow execution.
2. Use the nested workflow in a parent workflow
The parent workflow executes the nested workflow as part of its logic, providing the necessary information and using the output in subsequent steps.
For example, you can create a workflow to investigate suspicious user activity, incorporating the workflow created in the previous section to enrich the user's IP address as part of the investigation.
- Create the parent workflow and implement the required logic.
- Add the Workflow operator.
- Select a workflow to call as a nested workflow.
- Provide the values for the nested workflow input parameters.
- Access the nested workflow output in subsequent steps by using:
{{ $.<nested_workflow_name>.<output_structure> }}