What is a Pipeline Macro?

A Pipeline Macro or just Macro in short is a single Pipeline Expression which can be declared inside an automation pipeline using the command macro and then reused at multiple places of the pipeline using the command macro.run. It is similar to a function / method definition and its call, but it is limited to the execution of a Pipeline Expression.

If you need to implement and reuse more sophisticated logic, consider to call a sub-pipeline by using the command pipeline.run instead.

Declaring a Macro​

Here is a simple example to declare a macro in a pipeline:

pipeline:
  - macro:
      args:
        firstName: "Some"
        lastName:  "Name"
      do: |
        firstName + ' ' + lastName

The parameter args defines the (optional) parameters to the macro as name-value pairs.

These arguments can be directly accessed by their names inside to the macro expression.

The macro expression is placed using the parameter do. This can be any supported Pipeline Expression. Since the parameter is an explicit expression parameter, you do not need to use the expression brackets like ${and }. They're optional.

This example will execute the macro with the pipeline flow and results in an output like this:

Some Name

Accessing scope variables​

You can also access all scopes variables like vars, headers and body, as you would do inside any Pipeline Expression:

vars:
  lastName: "Name"
pipeline:
  - macro:
      args:
        firstName: "Some"
      do: |
        firstName + ' ' + vars.lastName

Calling a macro​

In order to call a macro from another position in the pipeline, you have to first declare it using the command macro and to define a name for the macro unique inside the pipelie using the parameter name.

  • A callable macro must be declared first in the pipeline, before it can be called.

  • It's good practice to define callable macros always at the very top of the pipeline.

  • Callable macro names must be unique within a pipeline.

  • A callable macro (= has name parameter) will be ignored by the pipeline flow and must be explicitly called using the command macro.run.

Here is an example to declare such a callable macro:

pipeline:
  - macro:
      name: "concatNames"
      args:
        firstName: "Some"
        lastName:  "Name"
      do: |
        firstName + ' ' + lastName

As soon as such a macro has a name assigned, it will no longer be executed by the default pipeline flow, but ignored. Now, it can only be executed by calling the command macro.run.

In case you would like to execute this macro with the pipeline flow and via macro.run, you need to set the parameter flow to true.

Here is an example to call the macro concatNames declared before:

pipeline:

  - macro:
      name: "concatNames"
      args:
        firstName: "Some"
        lastName:  "Name"
      do: |
        firstName + ' ' + lastName

  - macro.run:
      name: "concatNames"

In case you do not define any args in macro.run, the default args will be used. So, the output here would be:

Some Name

You can overwrite the default args by re-declaring some or all of them:

pipeline:

  - macro:
      name: "concatNames"
      args:
        firstName: "Some"
        lastName:  "Name"
      do: |
        firstName + ' ' + lastName

  - macro.run:
      name: "concatNames"
      args:
        firstName: "HELLO"

Output would be:

HELLO Name

By default, the result of the macro will be stored to the body. You can change that, by using the parameter output to store it to any location like the vars scope for example:

pipeline:

  - macro:
      name: "concatNames"
      args:
        firstName: "Some"
        lastName:  "Name"
      do: |
        firstName + ' ' + lastName

  - macro.run:
      name: "concatNames"
      args:
        firstName: "HELLO"
      output: vars.macroResult

  - set.body:
      value: "Result in variable macroResult: ${vars.macroResult}"

This will create a body value like this after execution:

Result in variable macroResult: HELLO Name