Group by Task Instance | docs.d3security

last updateD: june 18, 2025

The Merge task's "groupBy": "Task Instance" configuration operates similarly to grouping by "Task" with one distinction: it creates a separate merge array for each instance of the specified task.

Merge Condition Format

To apply this configuration, the merge condition must include at least the following two keys:

JSON

{
  "groupBy": "Task Instance",
  "taskName": "<Display name of a task node>"
}

Core Concepts

Example 1 - Group By Task Instance Basics

OBJECTIVE – Understand the relationship between the number of executions of the specified task in the merge condition and the quantity of merge results produced.

Build the following playbook:

Use the following merge condition:

JSON

{
    "groupBy": "Task Instance",
    "taskName": "A"
}

Test run the playbook.
Click on the icon within the Merge task.
Note that two out of the three execution instances lack merge results.
Observe the execution result in the instance rendering the Raw Data tab.
merge result
JSON
```
[
  {
    "DataSource": { ... },
    "A": { ... },
    "D": { ... }
  }
]
```

Repeat steps 2-6 with "B" as the merge condition taskName:

JSON

{
    "groupBy": "Task Instance",
    "taskName": "B"
}

merge result

JSON

[
  {
    "DataSource": { ... },
    "B": { ... },
    "D": { ... }
  }
]

Repeat steps 2-6 with "C" as the merge condition taskName:

JSON

{
    "groupBy": "Task Instance",
    "taskName": "C"
}

merge result

JSON

[
  {
    "DataSource": { ... },
    "C": { ... },
    "D": { ... }
  }
]

Repeat steps 2-6 with "D" as the merge condition taskName:

JSON

{
    "groupBy": "Task Instance",
    "taskName": "D"
}

merge result 1

JSON

[
  {
    "DataSource": { ... },
    "A": { ... },
    "D": { ... }
  }
]

merge result 2

JSON

[
  {
    "DataSource": { ... },
    "B": { ... },
    "D": { ... }
  }
]

merge result 3

JSON

[
  {
    "DataSource": { ... },
    "C": { ... },
    "D": { ... }
  }
]

TAKEAWAYS

The Raw Data tab, containing the merge results, renders only for execution instances that match the task name specified in the merge condition.
There is a 1:1 correspondence between the number of executions of the specified task and the number of merge results.
- Tasks A, B, and C each execute only once. Consequently, selecting any of them in a groupBy Task Instance situation produces a single merge instance containing the merge result.
- Task D executes three times. Consequently, selecting it in a groupBy Task Instance situation results in three merge execution instances each containing an execution lineage object.

Had step 9 been executed using the merge condition grouping by Task rather than by Task Instance, the outcome would have been a single Merge instance containing the merge result.
group by task Merge result

JSON

[
  {
    "DataSource": { ... },
    "A": { ... },
    "D": { ... },
    "Merge": { ... }
  },
  {
    "DataSource": { ... },
    "C": { ... },
    "D": { ... },
    "Merge": { ... }
  },
  {
    "DataSource": { ... },
    "B": { ... },
    "D": { ... }
  }
]

Example 2 - Merging Using a Task with Upstream and Downstream Nodes

OBJECTIVE – Understand how the Merge task processes execution lineage permutations with a designated task, considering its upstream and downstream nodes.

Build the following playbook:

Configure the JSON Data parameter of the Unwind A node as follows:

JSON

[
  { "id": 1, "name": "Object 1" },
  { "id": 2, "name": "Object 2" }
]

Configure the JSON Data parameter of the Unwind B node as follows:

JSON

[
  { "id": 3, "name": "Object 3" },
  { "id": 4, "name": "Object 4" },
  { "id": 5, "name": "Object 5" }
]

Input the following merge condition:

JSON

{
    "groupBy": "Task Instance",
    "taskName": "ABC 1"
}

Click on the icon within the Merge task.

Locate execution instances with the Raw Data tab visible, then review the execution result.

MERGE RESULT 1

JSON

[
  {
    "DataSource": { ... },
    "Unwind A": { ... },
    "ABC 1": { ... },
    "ABC 1.1": { ... }
  },
  {
    "DataSource": { ... },
    "Unwind A": { ... },
    "ABC 1": { ... },
    "ABC 1.2": { ... }
  }
]

MERGE RESULT 2

JSON

[
  {
    "DataSource": { ... },
    "Unwind A": { ... },
    "ABC 1": { ... },
    "ABC 1.1": { ... }
  },
  {
    "DataSource": { ... },
    "Unwind A": { ... },
    "ABC 1": { ... },
    "ABC 1.2": { ... }
  }
]

MERGE RESULT 3

JSON

[
  {
    "DataSource": { ... },
    "Unwind B": { ... },
    "ABC 1": { ... },
    "ABC 1.1": { ... }
  },
  {
    "DataSource": { ... },
    "Unwind B": { ... },
    "ABC 1": { ... },
    "ABC 1.2": { ... }
  }
]

MERGE RESULT 4

JSON

[
  {
    "DataSource": { ... },
    "Unwind B": { ... },
    "ABC 1": { ... },
    "ABC 1.1": { ... }
  },
  {
    "DataSource": { ... },
    "Unwind B": { ... },
    "ABC 1": { ... },
    "ABC 1.2": { ... }
  }
]

MERGE RESULT 5

JSON

[
  {
    "DataSource": { ... },
    "Unwind B": { ... },
    "ABC 1": { ... },
    "ABC 1.1": { ... },
    "Merge": { ... }
  },
  {
    "DataSource": { ... },
    "Unwind B": { ... },
    "ABC 1": { ... },
    "ABC 1.2": { ... }
  }
]

MERGE RESULT 6

JSON

[
  {
    "DataSource": { ... },
    "C": { ... },
    "ABC 1": { ... },
    "ABC 1.1": { ... },
    "Merge": { ... }
  },
  {
    "DataSource": { ... },
    "C": { ... },
    "ABC 1": { ... },
    "ABC 1.2": { ... }
  }
]

Configuring the merge condition with groupBy Task instead of Task Instance will result in a single Merge execution containing one consolidated array of the same twelve objects.

TAKEAWAY

Merge results will be distributed across instances, instead of being chunked altogether in one Merge execution instance.

RELATED ARTICLES