What is a Pipeline Body?

The body of a pipeline usually contains the data to be prepared during a pipeline execution. The body will be passed to one command after another in a pipeline flow. So the body output of a previous command is the input body of the next command. Any command can then read and change the body. At the very end of a pipeline execution, the data in the body will finally be send to the caller.

Change the default output of a command

In case a command produces a result, by default the output location of such a command to write the result to is the body. So any subsequent command can read the data from this location without additional setup required.

But sometimes the result of a command should not be passed to the next command via body. In this case you can change the location where a command should write its result to. To do so, you have two optional parameters output or var on any command available, producing an output to configure this accordingly.

output

Using this parameter you can define a Pipeline Expression (PEL) which specifies, where to write the result of the command to. The target can be at any location or sub-location of the current message. It can be in the vars scope but also can be used to add the result into the current body at some child-location for example. Here are some examples how to use this parameter:

Example 1: Add to vars scope

pipeline:
  - http.get:
      url: https://some.domain.tld/rest/customers
      output: ${vars.customers}

This example writes the result of the HTTP GET request into a new variable with name customers in the vars scope.

Example 2: Add to existing object in vars scope

vars:
  customer: {"id": 123}
pipeline:
  - http.get:
      url: "https://some.domain.tld/rest/orders/${vars.customer.id}"
      output: ${vars.customer.orders}

This example attaches the result of the HTTP GET request to the already existing variable object customer as new field with name orders.

Example 3: Add to existing object in body scope

body: {"id": 123}
pipeline:
  - http.get:
      url: "https://some.domain.tld/rest/orders/${body.id}"
      output: ${body.orders}

This example attaches the result of the HTTP GET request to the already existing body object as new field with name orders. It is similar to Example 2 except that the result is attached as child to an existing object in the body.

Example 4: Skip any output

pipeline:
  - http.get:
      url: "https://some.domain.tld/rest/orders/${body.id}"
      output: false

This example will not write any result since the output parameter was set to false which means to skip any output of the command. This is handy in case you do not need the output of the command at all.

var

Another option to write the result of a command to a variable instead of the body is by using the var parameter. This parameter expects a string and sets the result of the command in the vars scope using this given variable name. It is a more easy readable way to save into the vars scope compared to the output param but has the same affect as the parameter output: ${vars.myVarName}.

Example:

pipeline:
  - http.get:
      url: https://some.domain.tld/rest/customers
      var: customers

This example stores the result from the HTTP GET call in a variable of name customers in the vars scope. In case such a variable already exists, it will be overwritten.

Stacking the Body

SINCE VERSION 9.0

In some cases the current data in the body needs to be temporarly saved for later use. So any next command can overwrite the existing body data. For this, one option is to store the current body value to a variable and later reset this value into the body.

Another approach is to use the body stack with the commands body.push, body.peek and body.pop. This way you can simply "hide" the current body value using body.push and unhide it using the command body.peek or body.pop. This is especially useful in case you need to keep the order who the body data was added:

• body.push = Adds the current data in the body to the stack.

• body.peek = Moves the current data from the stack back to the body, without removing it from the stack.

• body.pop = Moves the current data from the stack back to the body and removes it from the stack.

Example:

pipeline:
  
  # Create data in the body
  - body.set: "ORIGIN VALUE"
  
  # Save the body data temporarly "away" for later use
  - body.push
  
  # Do something else with current body
  - body.set: "NEW VALUE"
  
  # "Reset" the body value from stack
  - body.pop

When executing this pipeline, the final output will be:

"ORIGIN VALUE"

The origin value was reset to the body at the very end. So there is no need to extra create and manage variables for that.

You can also call body.push several times. With every call the current data in the body will be stored to the stack (it will be added to the top). Any call of body.pop will return and remove the data at the stack from top to down in the same reverse order they got added. back.

Naming your stack

In case you would like to handle multiple stacks, you can also define the stack name using the same name parameter on body.push, body.peek and body.pop accordingly.