Merge Tasks | User Docs

Last Updated: October 26, 2026

Merge tasks collect desired playbook data and combine them into a single array. This array—the merge result—is found in the Raw Data tab of the Playbook Task Details popover.

Merge is useful when consolidating data from upstream task nodes that arrive either as:

Distinct parallel playbook nodes

Example - Merging Parallel Nodes *

objective – Merge the return data of three parallel task nodes into a string array.

Tip: you can also generate this playbook with AI. See Generating with AI.

Build the following playbook:
Configure task A to return the string "A", task B to return "B", and task C to return "C".

Provide the following configuration as input for the Merge task:

JSON

{
  "groupBy": "Playbook Instance",
  "dataJsonPath": "$.*.returnData"
}

Test run the playbook.
Observe the execution results for each task.
- Data Formatter tasks:
- Merge task:

Multiple instances of the same task

Example - Merging Data from Instances of the Same Task *

objective – Use an Unwind task to split a list of objects into individual objects, update each one using a Data Formatter task, and then recombine the modified objects with a Merge task.

Build the following playbook:

Provide the following JSON data as input for the JSON Data parameter of the Unwind task:

JSON

[
  { "key1": "value1", "key2": "value2" },
  { "key3": "value3", "key4": "value4" },
  { "key5": "value5", "key6": "value6" }
]

Provide the following Jinja logic as input for the Process Object (Data Formatter) task:

JSON

{
  {% set k1 = PlaybookData | jsonpath('$.Unwind.contextData.data.key1') %}
  {% set k2 = PlaybookData | jsonpath('$.Unwind.contextData.data.key2') %}
  {% set k3 = PlaybookData | jsonpath('$.Unwind.contextData.data.key3') %}
  {% set k4 = PlaybookData | jsonpath('$.Unwind.contextData.data.key4') %}
  {% set k5 = PlaybookData | jsonpath('$.Unwind.contextData.data.key5') %}
  {% set k6 = PlaybookData | jsonpath('$.Unwind.contextData.data.key6') %}

  {% if k1 %}
  "key1": "UPDATED VALUE 1"{% if k2 %},{% endif %}
  {% endif %}
  {% if k2 %}
  "key2": "UPDATED VALUE 2"{% if k3 %},{% endif %}
  {% endif %}
  {% if k3 %}
  "key3": "UPDATED VALUE 3"{% if k4 %},{% endif %}
  {% endif %}
  {% if k4 %}
  "key4": "UPDATED VALUE 4"{% if k5 %},{% endif %}
  {% endif %}
  {% if k5 %}
  "key5": "UPDATED VALUE 5"{% if k6 %},{% endif %}
  {% endif %}
  {% if k6 %}
  "key6": "UPDATED VALUE 6"
  {% endif %}
}

Provide the following configuration as input for the Merge task:

JSON

{
  "groupBy": "Task",
  "taskName": "Unwind",
  "dataJsonPath": "$['Process Object'].returnData"
}

Test run the playbook.
Observe the execution results for each task.
- Unwind task:
- Process Object (Data Formatter) task:
- Merge task:

Merge Condition

The merge condition is a JSON object that tells the system how to group data based on a shared lineage—such as by Playbook Instance, Task, Task Instance, or Path—(lineage grouping), which data to filter, and the required match count for producing the merge result.

Merge Condition Schema

JSON

{
  "groupBy": "<Playbook Instance | Task | Task Instance | Path>",
  "taskName": "<Display name of the task>",
  "paths": [
    "<JSON path 1>",
    "<JSON path 2>",
    "<JSON path 3>",
    ...
    "<JSON path N>"
  ],
  "dataJsonPath": "<JSON path>",
  "count": <Number>
}

The following tables list the (case-sensitive) keys for the merge condition.

Grouping Fields

These key-value pairs define the criteria for grouping data that share a common lineage. This defines the lineage grouping behavior.

Key	Data Type	Description
groupBy	`string`	Defines the mode used to group execution-lineage objects that share certain runtime characteristics. Supported modes include: Path Playbook Instance default Task Task Instance Execution-lineage objects matched by the active grouping mode will consolidate into an array.
taskName	`string`	The task display name used to select execution paths to merge. The taskName key is used in conjunction with the `groupBy: "Task"` and `groupBy: "Task Instance"` configurations.
paths	`array<string>`	The array of node-anchored JSON path expressions that the Merge task evaluates within task outputs. Any execution lineage containing at least one listed path is included in the merge result. The paths key is used in conjunction with the `groupBy: "Path"` configuration.

Key

Data Type

Description

groupBy

string

Defines the mode used to group execution-lineage objects that share certain runtime characteristics.
Supported modes include:
- Path
- Playbook Instance default
- Task
- Task Instance
Execution-lineage objects matched by the active grouping mode will consolidate into an array.

taskName

string

The task display name used to select execution paths to merge.
The taskName key is used in conjunction with the groupBy: "Task" and groupBy: "Task Instance" configurations.

paths

array<string>

The array of node-anchored JSON path expressions that the Merge task evaluates within task outputs.
- Any execution lineage containing at least one listed path is included in the merge result.
The paths key is used in conjunction with the groupBy: "Path" configuration.

Post-Grouping Fields

These key-value pairs control how grouped data is handled after lineage grouping has been applied.

Key	Data Type	Description
dataJsonPath	`string`	The JSON path expression that returns the data of one task node per matched lineage. Original merge array elements (full lineage objects) become the value at the specified path.
count	`integer`	The number of matched execution-lineage objects required to trigger the merge and generate the array for downstream workflows. By default, all matched execution-lineage objects are returned in the merge output.

RELATED ARTICLES

FAQ

What are execution-lineage objects?

Execution-lineage object = A JSON object containing the full sequence of task metadata and outputs that lead to an active execution point.

example

Given the following playbook build configuration:

Provided that the Merge task serves as the reference active execution point, the following are the execution lineages and their corresponding object representations:

lineage 1

JSON

{
  "DataSource": { ... },
  "A1": { ... }
}

lineage 2

JSON

{
  "DataSource": { ... },
  "B1": { ... },
  "B2.1": { ... }
}

lineage 3

JSON

{
  "DataSource": { ... },
  "B1": { ... },
  "B2.2": { ... }
}

Assuming the default merge condition is applied, the resulting merged output will be as follows:

JSON

[
  {
    "DataSource": { ... },
    "A1": { ... }
  },
  {
    "DataSource": { ... },
    "B1": { ... },
    "B2.1": { ... }
  },
  {
    "DataSource": { ... },
    "B1": { ... },
    "B2.2": { ... }
  }
]

TAKEAWAYS

An execution-lineage object describes a complete ancestral chain of task executions.
The default merge condition—unlike other grouping modes—will not, on its own, cause the merge result to exclude execution-lineage objects of any:
- Divergent lineages (e.g., as with lineage 1 and lineage 2/3)
- Sibling lineages (e.g., as with lineage 2 and lineage 3)

How can one use the dataJsonPath key to extract deeply nested values?

example 1

Build the following playbook.

Configure task A1 to return the following output:

JSON

[
  { "key1": "value1", "key2": "value2" },
  { "key3": "value3", "key4": "value4" },
  { "key5": "value5", "key6": "value6" }
]

Configure Merge with the following condition:

JSON

{
  "groupBy": "Path",
  "paths": ["$.['A1'].returnData"],
  "dataJsonPath": "$['A1'].returnData[?(@.key2=='value2')]"
}

Test run the playbook.

Check the merge results.
Merge result

JSON

[
  {
    "key1": "value1",
    "key2": "value2"
  }
]

example 2

Configure task A1 to return the following output:

JSON

[
  {
    "A": {
      "B": {
        "C": {
          "D": {
            "TARGET": {
              "id": 1,
              "value": "match"
            }
          }
        }
      }
    }
  },
  {
    "A": {
      "B": {
        "C": {
          "D": {
            "TARGET": {
              "id": 2,
              "value": "no-match"
            }
          }
        }
      }
    }
  }
]

Configure Merge with the following condition:

JSON

{
  "groupBy": "Path",
  "paths": ["$['A1'].returnData"],
  "dataJsonPath": "$['A1'].returnData[?(@.A.B.C.D.TARGET.value=='match')].A.B.C.D.TARGET"
}

Test run the playbook.

Check the merge result.
merge result

JSON

[
  {
    "id": 1,
    "value": "match"
  }
]