Syntax overview

To create a workflow, you use the Workflows syntax to define the steps you want and their order of execution. For more information about creating workflows, see Create and manage workflows.

For other functions available in addition to the core syntax, refer to the Standard library and Connectors references.

File structure

Workflow source files have the following characteristics:

  • They contain only one main workflow.
  • They might contain subworkflows.

  • They are either a valid YAML or JSON file.

    Code samples are provided in both YAML and the equivalent JSON.

You can search the Workflows syntax for its reserved words and other details. To see examples of the syntax in action, see the cheat sheet.

Reserved word Description Use with See also Examples

args

 Pass arguments and their values when calling a function that accepts parameters. call steps call
result

assign

 Set the value of a variable. — —

branches

 Execute parallel branches concurrently and the steps in each branch sequentially. steps parallel

break

 Terminate iteration of a for loop. next in for loops continue

call

 Run a function and return a result. — args
result

condition

 Provide an expression to control if a step is executed (the first condition to evaluate as true). switch —

continue

 Terminate the current iteration of a for loop and continue with the next iteration. next in for loops break

end

 Stop a workflow's execution without returning a value. next —

except

 Catch and handle errors thrown during a workflow execution. try retry
for Iterate over a sequence of numbers or through a collection of data, such as a list or map. steps —

main

 Define your main workflow. If a workflow has a subworkflow, or to receive runtime arguments, there must be a main block. Subworkflows —

next

 Define what step Workflows should execute next. — break
continue

parallel

 Execute two or more steps concurrently. branches
for loops
steps 		—

params

 Accept workflow execution arguments, or arguments passed to a subworkflow. Subworkflows main

raise

 Raise custom errors. — except
retry
try

result

 Assign the result from a call to this variable. call steps args

retry

 Define the retry behavior and the number of retry attempts. try —

return

 Stop a workflow's execution and return a value or expression. — —

steps

 Nest a series of steps. branches
for loops
Subworkflows
try 		main

switch

 Allow the value of an expression to control the flow of a workflow's execution. — condition

try

 Define a list of steps to retry if an error is raised, or catch and handle the error. — except
retry

Example: args

YAML

  - STEP_NAME:
      call: ...
      args:
      ...
      result: VARIABLE

JSON

  [
    {
      "STEP_NAME": {
        "call": ...,
        "args": {
          ...
        },
        "result": "VARIABLE"
      }
    }
  ]

Example: assign

YAML

  - STEP_NAME:
      assign:
          - VARIABLE_NAME: VALUE

JSON

  [
    {
      "STEP_NAME": {
        "assign": [
          {
            "VARIABLE_NAME": "VALUE"
          }
        ]
      }
    }
  ]

Example: branches

YAML

  - PARALLEL_STEP_NAME:
      parallel:
          ...
          branches:
            - BRANCH_NAME_A:
                steps:
                    ...
            - BRANCH_NAME_B:
                steps:
                    ...

JSON

   [
    {
      "PARALLEL_STEP_NAME": {
        "parallel": {
          ...
          "branches": [
            {
              "BRANCH_NAME_A": {
                "steps":
                     ...
              }
            },
            {
              "BRANCH_NAME_B": {
                "steps":
                     ...
              }
            }
          ]
        }
      }
    }
  ]

Example: break

YAML

  - FOR_LOOP_STEP_NAME_A:
      for:
          value: LOOP_VARIABLE_NAME_A
          in: ${LIST_EXPRESSION_A}    # or simply in: LIST_DEFINITION
          steps:
              - STEP_NAME_A:
                  next: continue
  - FOR_LOOP_STEP_NAME_B:
      for:
          value: LOOP_VARIABLE_NAME_B
          range: [${BEGIN_EXPRESSION}, ${END_EXPRESSION}]
          steps:
              - STEP_NAME_B:
                  next: break

JSON

  [
    {
      "FOR_LOOP_STEP_NAME_A": {
        "for": {
          "value": "LOOP_VARIABLE_NAME_A",
          "in": "${LIST_EXPRESSION_A}",
          "steps": [
            {
              "STEP_NAME_A": {
                "next": "continue"
              }
            }
          ]
        }
      }
    },
    {
      "FOR_LOOP_STEP_NAME_B": {
        "for": {
          "value": "LOOP_VARIABLE_NAME_B",
          "range": [
            "${BEGIN_EXPRESSION}",
            "${END_EXPRESSION}"
          ],
          "steps": [
            {
              "STEP_NAME_B": {
                "next": "break"
              }
            }
          ]
        }
      }
    }
  ]

Example: call

YAML

  - STEP_NAME:
      call: ...
      args:
      ...
      result: VARIABLE

JSON

  [
    {
      "STEP_NAME": {
        "call": ...,
        "args": {
          ...
        },
        "result": "VARIABLE"
      }
    }
  ]

Example: condition

YAML

  - STEP_NAME_A:
      switch:
          - condition: ${EXPRESSION_A}
            next: STEP_NAME_B
          - condition: ${EXPRESSION_B}
            next: STEP_NAME_C
          - condition: true
            next: STEP_NAME_C
      next: STEP_NAME_D

JSON

  [
    {
      "STEP_NAME_A": {
        "switch": [
          {
            "condition": "${EXPRESSION_A}",
            "next": "STEP_NAME_B"
          },
          {
            "condition": "${EXPRESSION_B}",
            "next": "STEP_NAME_C"
          }
          {
            "condition": true,
            "next": "STEP_NAME_C"
          }
        ],
        "next": "STEP_NAME_D"
      }
    }
  ]

Example: continue

YAML

  - FOR_LOOP_STEP_NAME_A:
      for:
          value: LOOP_VARIABLE_NAME_A
          in: ${LIST_EXPRESSION_A}    # or simply in: LIST_DEFINITION
          steps:
              - STEP_NAME_A:
                  next: continue
  - FOR_LOOP_STEP_NAME_B:
      for:
          value: LOOP_VARIABLE_NAME_B
          range: [${BEGIN_EXPRESSION}, ${END_EXPRESSION}]
          steps:
              - STEP_NAME_B:
                  next: break

JSON

  [
    {
      "FOR_LOOP_STEP_NAME_A": {
        "for": {
          "value": "LOOP_VARIABLE_NAME_A",
          "in": "${LIST_EXPRESSION_A}",
          "steps": [
            {
              "STEP_NAME_A": {
                "next": "continue"
              }
            }
          ]
        }
      }
    },
    {
      "FOR_LOOP_STEP_NAME_B": {
        "for": {
          "value": "LOOP_VARIABLE_NAME_B",
          "range": [
            "${BEGIN_EXPRESSION}",
            "${END_EXPRESSION}"
          ],
          "steps": [
            {
              "STEP_NAME_B": {
                "next": "break"
              }
            }
          ]
        }
      }
    }
  ]

Example: end

YAML

  - STEP_NAME:
      ...
      next: end

JSON

  [
    {
      "STEP_NAME": {
        ...
        "next": "end"
      }
    }
  ]

Example: except

YAML

  - STEP_NAME:
     try:
         call: http.get
         ...
     except:
         as: ERROR_MAP
         steps:
             ...

JSON

  [
    {
      "STEP_NAME": {
        "try": {
          "call": "http.get"
          ...
        },
        "except": {
          "as": "ERROR_MAP",
          "steps":
              ...
        }
      }
    }
  ]

Example: for

YAML

  - FOR_LOOP_STEP_NAME:
      for:
          value: LOOP_VARIABLE_NAME
          index: INDEX_VARIABLE_NAME
          in: ${LIST_EXPRESSION}
          steps:
              - STEP_NAME_A:
                ...

JSON

  [
    {
      "FOR_LOOP_STEP_NAME": {
        "for": {
          "value": "LOOP_VARIABLE_NAME",
          "index": "INDEX_VARIABLE_NAME",
          "in": "${LIST_EXPRESSION}",
          "steps": [
            {
              "STEP_NAME_A":
                ...
            }
          ]
        }
      }
    }
  ]

Example: main

YAML

  main:
      params: [MAP_NAME]
      steps:
          - STEP_NAME:
              ...
          ...

JSON

    {
      "main": {
        "params": [
          "MAP_NAME"
        ],
        "steps": [
          {
            "STEP_NAME": {
              ...
            }
          },
          ...
        ]
      }
    }

Example: next

YAML

  - STEP_NAME:
      ...
      next: STEP_NAME_TO_JUMP_TO

JSON

  [
    {
      "STEP_NAME": {
        ...
        "next": "STEP_NAME_TO_JUMP_TO"
      }
    }
  ]

Example: params

YAML

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

JSON

  {
    "main": {
      "steps": [
        {
          "STEP_NAME": {
            "call": "SUBWORKFLOW_NAME",
            "args": {
              "ARG_1": "VALUE_1",
              "ARG_2": "VALUE_2"
            },
            "result": "OUTPUT_VARIABLE"
          }
        }
      ]
    },
    "SUBWORKFLOW_NAME": {
      "params": ["PARAMETER_1,PARAMETER_2"...],
      "steps": [
        {
          "step_1":
          ...
        }
      ]
    }
  }

Example: parallel

YAML

  - PARALLEL_STEP_NAME:
      parallel:
          exception_policy: POLICY
          shared: [VARIABLE_A, VARIABLE_B, ...]
          BRANCHES_OR_FOR:
             ...

JSON

  [
    {
      "PARALLEL_STEP_NAME": {
        "parallel": {
          "exception_policy": "POLICY",
          "shared": [
            "VARIABLE_A",
            "VARIABLE_B",
            ...
          ],
          "BRANCHES_OR_FOR":
          ...
        }
      }
    }
  ]

Example: raise

YAML

  - step_a:
      raise: "Something went wrong."

JSON

  [
    {
      "step_a": {
        "raise": "Something went wrong."
      }
    }
  ]

Example: result

YAML

  - STEP_NAME:
      call: ...
      args:
      ...
      result: VARIABLE

JSON

  [
    {
      "STEP_NAME": {
        "call": ...,
        "args":
        ...,
        "result": "VARIABLE"
      }
    }
  ]

Example: retry

YAML

  - step_name:
      try:
          steps:
              ...
      retry: RETRY_POLICY
          predicate: RETRY_PREDICATE
          max_retries: NUMBER_OF_RETRIES
          backoff:
              initial_delay: DELAY_SECONDS
              max_delay: MAX_DELAY_SECONDS
              multiplier: DELAY_MULTIPLIER

JSON

  [
    {
      "step_name": {
        "try": {
           "steps": [
               ...
    ]
        },
        "retry": "RETRY_POLICY"
          "predicate": "RETRY_PREDICATE",
          "max_retries": NUMBER_OF_RETRIES,
          "backoff": {
            "initial_delay": DELAY_SECONDS,
            "max_delay": MAX_DELAY_SECONDS,
            "multiplier": DELAY_MULTIPLIER
          }
        }
      }
  ]

Example: return

YAML

  - STEP_NAME:
      ...
      return: ${VARIABLE}

JSON

  [
    {
      "STEP_NAME": {
        ...
        "return": "${VARIABLE}"
      }
    }
  ]

Example: steps

YAML

  - STEP_NAME:
    steps:
      - STEP_NAME_1:
          steps:
              - STEP_NAME_A:
                  ...
              - STEP_NAME_B:
                  ...
      - STEP_NAME_2:
          steps:
              - STEP_NAME_C:
                  ...

JSON

    {
      STEP_NAME: {
      "steps": [
        {
          STEP_NAME_1: {
            "steps": [
              {
                STEP_NAME_A:
                  ...
              },
              {
                STEP_NAME_B:
                  ...
              }
            ]
          }
        },
        {
          STEP_NAME_2: {
            "steps": [
              {
                STEP_NAME_C:
                  ...
              }
            ]
          }
        }
      ]
    }
  }

Example: switch

YAML

  - STEP_NAME_A:
      switch:
          - condition: ${EXPRESSION_A}
            next: STEP_NAME_B
          - condition: ${EXPRESSION_B}
            next: STEP_NAME_C
          - condition: true
            next: STEP_NAME_C
      next: STEP_NAME_D

JSON

  [
    {
      "STEP_NAME_A": {
        "switch": [
          {
            "condition": "${EXPRESSION_A}",
            "next": "STEP_NAME_B"
          },
          {
            "condition": "${EXPRESSION_B}",
            "next": "STEP_NAME_C"
          }
          {
            "condition": true,
            "next": "STEP_NAME_C"
          }
        ],
        "next": "STEP_NAME_D"
      }
    }
  ]

Example: try

YAML

  - STEP_NAME:
     try:
         call: http.get
         ...
     except:
         as: ERROR_MAP
         steps:
             ...

JSON

  [
    {
      "STEP_NAME": {
        "try": {
          "call": "http.get"
          ...
        },
        "except": {
          "as": "ERROR_MAP",
          "steps":
              ...
        }
      }
    }
  ]

Example: stub

Using code samples

For all samples that communicate with other Google Cloud resources, your workflow must be associated with a service account that has sufficient privileges to access those resources. To learn more about granting roles to service accounts, see Manage access to projects, folders, and organizations. To learn how to change the service account associated with a workflow, see update a workflow. For more information about authentication, see Grant a workflow permission to access Google Cloud resources.

Some samples might require that you first enable a Google Cloud API. Learn more about listing services and enabling services.

See all Workflows code samples.

Notation key

Notation Description
[] Square brackets Optional; if the brackets themselves must be typed, this is indicated
{} Braces Required
| Vertical bar Separator for mutually exclusive items; choose one
... Ellipsis Items that can be repeated; or indicates an omission to improve clarity and shorten the length of the example