conductor-oss--conductor/docs/devguide/how-tos/Tasks/task-inputs.md

description

description
Wire task inputs in Conductor workflows — reference workflow inputs, task outputs, and variables using dynamic expressions in this open source workflow orchestration engine.

Wiring Task Inputs

In Conductor, task inputs can be provided in the workflow definition in multiple ways:

• As a hard-coded value –

"taskInputA": true

• As a dynamic reference to the workflow inputs, workflow variables, or the inputs/outputs of prior tasks –

"taskInputA": "${workflow.input.someValue}

Syntax for dynamic references

All dynamic references are formatted as the following expression:

"${type.jsonpath}"

These dynamic references are formatted as dot-notation expressions, taking after JSONPath syntax.

Component	Description
${...}	The root notation indicating that the variable will be dynamically replaced at runtime.
type	The type of reference. Supported values: workflow—Refers to the current workflow instance. workflow.input—Refers to the workflow’s input parameters. workflow.output—Refers to the workflow’s output parameters. workflow.variables—Refers to the workflow variables set in the workflow using the Set Variable task. taskReferenceName—Refers to a task in the current workflow instance by its reference name. (For example, “http_ref”). taskReferenceName.input—Refers to the task’s input parameters. taskReferenceName.output—Refers to the task’s output parameters.
jsonpath	The JSONPath expression in dot-notation.

Sample expressions

Here is a non-exhaustive list of dynamic references you can use:

• To reference a task’s input payload –

${<taskReferenceName>.input}

• To reference a task’s output payload –

${<taskReferenceName>.output}

• To reference a task’s input parameter –

${<taskReferenceName>.input.<someKey>}

• To reference a task’s output parameter –

${<taskReferenceName>.output.<someKey>}

• To reference the workflow's input payload –

${workflow.input}

• To reference the workflow's output payload –

${workflow.output}

• To reference the workflow's input parameter –

${workflow.input.<someKey>}

• To reference the workflow's output parameter –

${workflow.output.<someKey>}

• To reference the workflow's current status (RUNNING, PAUSED, TIMED_OUT, TERMINATED, FAILED, or COMPLETED) –

${workflow.status}

• To reference the workflow's (execution) ID –

${workflow.workflowId}

• (Used in sub-workflows) To reference the parent workflow (execution) ID –

${workflow.parentWorkflowId}

• (Used in sub-workflows) To reference the task execution ID for the Sub Workflow task in the parent workflow –

${workflow.parentWorkflowTaskId}

• To reference the workflow's name –

${workflow.workflowType} 

• To reference the workflow's version –

${workflow.version} 

• To reference the start time of the workflow execution –

${workflow.createTime} 

• To reference the workflow's correlation ID –

${workflow.correlationId} 

• To reference the workflow’s domain name that was invoked during its execution –

${workflow.taskToDomain.<domainName>} 

• To reference the workflow's variable created using the Set Variable task –

${workflow.variables.<someKey>} 

Examples

Here are some examples for using dynamic references in workflows.

Referencing workflow inputs​​

For the given workflow input:

{
  "userID": 1,
  "userName": "SAMPLE",
  "userDetails": {
    "country": "nestedValue",
    "age": 50
  }
}

You can reference these workflow inputs elsewhere using the following expressions:

{
  "user": "${workflow.input.userName}",
  "userAge": "${workflow.input.userDetails.age}"
}

At runtime, the parameters will be:

{
  "user": "SAMPLE",
  "userAge": 50
}

Referencing other task outputs​​

If a task previousTaskReference produced the following output:

{
  "taxZone": "A",
  "productDetails": {
    "nestedKey1": "outputValue-1",
    "nestedKey2": "outputValue-2"
  }
}

You can reference these task outputs elsewhere using the following expressions:

{
  "nextTaskInput1": "${previousTaskReference.output.taxZone}",
  "nextTaskInput2": "${previousTaskReference.output.productDetails.nestedKey1}"
}

At runtime, the parameters will be:

{
  "nextTaskInput1": "A",
  "nextTaskInput2": "outputValue-1"
}

Referencing workflow variables

If a workflow variable is set using the Set Variable task:

{
  "name": "Ipsum"
}

The variable can be referenced in the same workflow using the following expression:

{
  "user": "${workflow.variables.name}"
}

Note: Workflow variables cannot be re-referenced across workflows, even between a parent workflow and a sub-workflow.

Referencing data between parent workflow and sub-workflow​

To pass parameters from a parent workflow into its sub-workflow, you must declare them as input parameters for the Sub Workflow task. If needed, these inputs can then be set as workflow variables within the sub-workflow definition itself using a Set Variable task.

// parent workflow definition with task configuration

{
 "createTime": 1733980872607,
 "updateTime": 0,
 "name": "testParent",
 "description": "workflow with subworkflow",
 "version": 1,
 "tasks": [
   {
     "name": "get_item",
     "taskReferenceName": "get_item_ref",
     "inputParameters": {
       "uri": "https://example.com/api",
       "method": "GET",
       "accept": "application/json",
       "contentType": "application/json",
       "encode": true
     },
     "type": "HTTP",
   },
   {
     "name": "sub_workflow",
     "taskReferenceName": "sub_workflow_ref",
     "inputParameters": {
       "user": "${workflow.variables.name}",
       "item": "${previous_task_ref.output.item[0]}"
     },
     "type": "SUB_WORKFLOW",
     "subWorkflowParam": {
       "name": "testSub",
       "version": 1
     }
   }
 ],
 "inputParameters": [],
 "outputParameters": {}
}

To pass parameters from a sub-workflow back to its parent workflow, you must pass them as the sub-workflow’s output parameters in the sub-workflow definition.

// sub-workflow definition

{
 "createTime": 1726651838873,
 "updateTime": 1733983507294,
 "name": "testSub",
 "description": "subworkflow for parent workflow",
 "version": 1,
 "tasks": [
   {
     "name": "get-user",
     "taskReferenceName": "get-user_ref",
     "inputParameters": {
       "uri": "https://example.com/api",
       "method": "GET",
       "accept": "application/json",
       "contentType": "application/json",
       "encode": true
     },
     "type": "HTTP",
   },
   {
     "name": "send-notification",
     "taskReferenceName": "send-notification_ref",
     "inputParameters": {
       "uri": "https://example.com/api",
       "method": "GET",
       "accept": "application/json",
       "contentType": "application/json",
       "encode": true
     },
     "type": "HTTP",
   }
 ],
 "inputParameters": [],
 "outputParameters": {
   "location": "${get-user_ref.output.response.body.results[0].location.country}",
   "isNotif": "${send-notification_ref.output}"
 }
}

In the parent workflow, these sub-workflow outputs can be referenced using the expression format ${<sub_workflow_ref>.output.<someKey>}.

Troubleshooting

You can verify if the data was passed correctly by checking the input/output values of the task execution in the UI. Common errors:

• If the reference expression is incorrectly formatted, the referencing parameter value may end up with the wrong data or a null value.
• If the referenced value (such as a task output) has not resolved at the point when it is referenced, the referencing parameter value will be null.