Sub Workflow
The Sub Workflow task executes another workflow within the current workflow. This allows you to reuse common workflows across multiple workflows. Unlike the Start Workflow task, the Sub Workflow task provides synchronous execution.
The Sub Workflow task can also be used to overcome the limitations of other tasks:
- Use it in a Do While task to achieve nested Do While loops.
- Use it in a Dynamic Fork task to execute more than one task in each fork.
Task parameters
Configure these parameters for the Sub Workflow task.
| Parameter | Description | Required/ Optional |
|---|---|---|
| subWorkflowParam | A map that includes the sub-workflow’s configuration, such as the name, version, task-to-domain mapping, idempotency key, and priority. | Required. |
| subWorkflowParam. name | The name of the workflow to be executed. This workflow should have a pre-existing definition in Conductor. | Required. |
| subWorkflowParam. version | The version of the workflow to be executed. If unspecified or set to 0, the latest version will be used. | Required. |
| subWorkflowParam. taskToDomain | A map of sub-workflow tasks to specific domains. The keys are the task reference names and the values are the domain names. If unspecified, the taskToDomain of the executing parent workflow will take over. | Optional. |
| subWorkflowParam. priority | The priority of the subworkflow. Supports values from 0-99 and can be passed as a dynamic input. If set, this priority overrides the parent workflow’s priority. If not, it inherits the parent workflow’s priority. | Optional. |
| subWorkflowParam. idempotencyKey | A unique, user-generated key to prevent duplicate workflow executions. Idempotency data is retained for the life of the workflow execution. | Optional. |
| subWorkflowParam. idempotencyStrategy | The idempotency strategy for handling duplicate requests. Supported values:
| Required if idempotencyKey is used. |
In addition, you can also configure the sub-workflow’s input in inputParameters, which will be passed down to the invoked sub-workflow. The sub-workflow’s input can be coupled to the parent workflow’s input parameters, or it can be invoked from the output of the preceding task.
- If you are taking the sub-workflow’s input parameters from the parent workflow, you need to add them as an input parameter in the parent workflow and then call the same input parameters inside the sub-workflow definition.
- If an idempotency strategy is configured in the sub-workflow task configuration and no idempotency key is provided, the sub-workflow task will automatically inherit the idempotency key from its parent workflow.
Other generic parameters
Here are other parameters for configuring the task behavior.
| Parameter | Description | Required/ Optional |
|---|---|---|
| optional | Whether the task is optional. The default is false. If set to true, the workflow continues to the next task even if this task is in progress or fails. | Optional. |
Task configuration
This is the task configuration for a Sub Workflow task.
{
"name": "sub_workflow",
"taskReferenceName": "sub_workflow_ref",
"inputParameters": {
// input parameters for the sub workflow},
"type": "SUB_WORKFLOW",
"subWorkflowParam": {
"name": "subworkflowName",
"version": 3,
"priority": 5,
"idempotencyKey": "someKey",
"idempotencyStrategy": "RETURN_EXISTING",
"taskToDomain": {
"someTask": "someDomain"
}
}
}
}
Task output
The Sub Workflow task will return the following parameters.
| Parameter | Description |
|---|---|
| subWorkflowId | The sub-workflow (execution) ID that is generated when running the sub-workflow. |
In addition to the execution ID, the sub-workflow’s workflow output will also be supplied as the Sub Workflow task output.
Adding a Sub Workflow task in UI
To add a Sub Workflow task:
- In your workflow, select the (+) icon and add a Sub Workflow task.
- Enter the Workflow name and Version. Once selected, the sub-workflow’s input parameters will automatically appear if there are any pre-defined ones.
- (Optional) Enter the Idempotency key and select the Idempotency strategy.
- (Optional) Add any additional input parameters for the sub-workflow.
- (Optional) Add task-to-domain mapping for the sub-workflow tasks.
To view the sub-workflow tasks inside the parent workflow, you can select Expand to display them in the visual diagram editor.
Examples
Here are some examples for using the Sub Workflow task.
Using the Sub Workflow task in a workflow
Let’s say you have a very long workflow, “payment_for_subscription”, which handles the payment for subscriptions as shown below:
To add this “payment_for_subscription” workflow to a larger subscription workflow, it would be possible to copy and paste the workflow JSON definition over. However, whenever the “payment_for_subscription” workflow is updated, it will not be reflected in the workflow where you have added it. A better way to handle this is to call the “payment_for_subscription” workflow as a sub-workflow in the wider subscription workflow so that any updates to this workflow get reflected in all its parent workflows.
You can add this as a sub-workflow in your required workflow whenever a payment flow is to be implemented:
This is a subscription workflow with multiple instances where the payment flow is to be implemented. Here, the previously-created payment workflow is added as sub-workflows.
FAQs
How do we retry a sub-workflow from a specific task?
You can use the following API to retry a sub-workflow from a specific task. From the Conductor UI, check the task level start time to verify that the preceding tasks are not re-run. Additionally, you can insert a WAIT task before the desired re-run starting point and confirm that it does not transition to the state of that WAIT task.
curl -X POST 'https://<conductor_server_dns>/api/workflow/<subworkflow-execution_id>/rerun' \
-H 'Content-Type: application/json' \
-d '{
"reRunFromTaskId": "<task_execution_id>"
}' \
-H 'x-authorization: <auth_token>'