Creating and using a subworkflow

You can use subworkflows to define a piece of logic or a set of steps you want to call multiple times, simplifying the workflow definition. Subworkflows are similar to a function or routine in a programming language. They can accept parameters and return values, allowing you to create more complex workflows with a broader range of applications.

This page covers defining a subworkflow and calling it from within a workflow. For information on basic workflow tasks, see Creating and updating an existing workflow and Executing a workflow.

Creating a workflow that uses a subworkflow

To create a subworkflow:

  1. Add a main block to the top of the workflow definition:

    main:
       steps:
           - step_name:
               ...
           ...
    

    If a workflow has a subworkflow, the main workflow must be placed in a main block.

  2. Define the subworkflow below the main steps of the workflow:

    main:
       steps:
           - step_name:
               ...
           ...
    [SUBWORKFLOW_NAME]:
        params: [PARAMETER_1[: DEFAULT_VALUE1], PARAMETER_2[: DEFAULT_VALUE2]...]
        steps:
            - step_name:
            ...
    

    Replace the following:

    • SUBWORKFLOW_NAME: Required. Name of the subworkflow.
    • [PARAMETER_1, PARAMETER_2]: Optional. Parameters used by the subworkflow.
    • DEFAULT_VALUE1, DEFAULT_VALUE2: Optional. Default values for the respective parameters.

    If you don't need to pass parameters to the subworkflow, delete the params block. Note that any parameters must be enclosed in square brackets; for example: params: [first_name, last_name, country: "England"].

  3. Within the subworkflow, define the steps just as you would in the main workflow.

  4. To call the subworkflow from the main workflow, add a call section within a step in the main workflow, optionally supplying arguments to pass to the subworkflow:

    main:
       - [STEP_NAME]:
           call: [SUBWORKFLOW_NAME]
           [args:
               ARG_1: VALUE
               ARG_2: VALUE
               ...]
           [result: OUTPUT_VARIABLE]
    [SUBWORKFLOW_NAME]:
        params: [PARAMETER_1,PARAMETER_2...]
        steps:
            - step_1:
            ...
    

    Replace the following:

    • SUBWORKFLOW_NAME: Required. Name of the subworkflow.
    • ARG_1, ARG_2: Optional. The arguments passed to the subworkflow, if the subworkflow accepts parameters.
    • VALUE: Optional. The values the arguments are set to.
    • OUTPUT_VARIABLE: Optional. The variable where the workflow stores the data the subworkflow returns, if the subworkflow returns anything.

Example

This example demonstrates defining a subworkflow named name_message and calling it from the main workflow:

main:
    steps:
        - call_subworkflow:
            call: name_message
            args:
                first_name: "Sherlock"
                last_name: "Holmes"
            result: output
        - call_subworkflow2:
            call: name_message
            args:
                first_name: "Ada"
                last_name: "Lovelace"
            result: output2
        - return_message:
            return: ${output + output2}

name_message:
    params: [first_name, last_name, country: "England"]
    steps:
        - prepareMessage:
            return: ${"Hello " + first_name + " " + last_name + " from " + country + "."}

This workflow definition does the following:

  • The main workflow calls the name_message subworkflow twice, from the steps call_subworkflow and call_subworkflow2.
  • The two steps supply different inputs for the arguments first_name and last_name, which are then passed to the subworkflow.
  • The subworkflow name_message takes the arguments passed to it and constructs a simple message, supplying the default value of England for the country variable.
  • The subworkflow returns the message it constructs to the main workflow.
  • The steps in the main workflow store the results as output and output2, respectively.
  • The main workflow combines output and output2 into a single message and returns the result: Hello Sherlock Holmes from England. Hello Ada Lovelace from England.

What's next