Map task
Use a Map task when the same nested item processor must run for every item in a collection.
Set the Map items JSONPath expression that selects an array, configure the nested item processor, and set either fixed maximum concurrency or a concurrency expression when needed. When it runs, SimWorkflow invokes the nested processor for each selected item, subject to that concurrency. Confirm the selected value is an array, item fields are available, nested tasks and routes are valid, and concurrency fits downstream capacity.
For example, use Map to validate each line item in an order. Do not use it for one object or when items need unrelated processes.
|
Field |
Required |
Default Value |
Description |
|---|---|---|---|
|
|
Yes |
N/A |
Enter one complete supported JSONPath or JSONata expression returning the array to process. See expression languages. The selected value must be an array. |
|
|
No |
N/A |
Sets a fixed limit on concurrently processed items. Use it when a constant limit protects a downstream system. |
|
|
No |
N/A |
Sets an expression-based concurrency limit. Use it instead of a fixed limit when capacity depends on available workflow data. |
Example: check each requested item
Use Map for two items needing the same checks, not two unrelated branches. Start with:
{
"items": [
{
"sku": "KEYBOARD",
"quantity": 2
},
{
"sku": "MOUSE",
"quantity": 3
}
]
}
Name the Map Check items, map {"items":"${workflow.input.items}"} into its Input Parameters, and use ${items} as the items expression. Inside its item processor, a JQ task named Prepare item can map {"item":"${swf:item}"} into its own Input Parameters and use .item | {sku, quantity} as its filter. End that nested path.
For this filter, Map's output is ordered by the original item position, not completion time:
{
"items": [
{
"result": {
"sku": "KEYBOARD",
"quantity": 2
},
"resultList": [
{
"sku": "KEYBOARD",
"quantity": 2
}
]
},
{
"result": {
"sku": "MOUSE",
"quantity": 3
},
"resultList": [
{
"sku": "MOUSE",
"quantity": 3
}
]
}
]
}
A following task can map ${['Check items'].output.items}. Each entry is the final nested task's complete output, so the JQ wrapper remains. A Map item cannot use a sibling item's task result to satisfy its own path or join. Give fixed concurrency a small positive value when downstream calls need protection. Blank or 0 adds no Map-specific concurrency cap; organization and downstream limits still apply. Use either fixed concurrency or its expression, not both. Its expression must return a whole number at least 0. If the selected items are not an array, correct the mapping before running.
Example
Required itemsExpression is one complete expression returning an array; required itemProcessor has startTask and nested tasks. Optional maxConcurrency is a whole number at least 0, or use maxConcurrencyExpression returning one, not both. Blank/null/0 adds no Map-specific concurrency cap. Each item has ${swf:item} and zero-based ${swf:itemIndex}; nested scopes never select a sibling item's task output.
Configure the example using its visible controls:
Select Map Task and open Configuration. Enter ${items} in Map items JSONPath expression. Click the down-arrow circle at the Map box's lower-left edge to enter its nested canvas. Add the Prepare item JQ task, map item to ${swf:item} on its Input Parameters, and set its Expression to .item. Connect the nested Start to that task and leave its outgoing path empty to finish the item. Use the return control to leave the Map and return to the outer canvas.
Input
Captured task data after Input Parameters mapping:
{
"items": [
{
"sku": "KEYBOARD"
},
{
"sku": "MOUSE"
}
]
}
Output
For nonempty input, items is an array of final item-processor outputs in original item order, not completion order and not the original input items. One item gives one output element. An empty Map currently returns {} without items; account for missing items when selecting it.
Raw task output:
{
"items": [
{
"result": {
"sku": "KEYBOARD"
},
"resultList": [
{
"sku": "KEYBOARD"
}
]
},
{
"result": {
"sku": "MOUSE"
},
"resultList": [
{
"sku": "MOUSE"
}
]
}
]
}
When something goes wrong: An expression returning null/object/text instead of an array fails; fix the mapped input and confirm the nested processor validates. Use a positive concurrency cap when the downstream service needs protection. A failed iteration is not a successful empty result.
A following task can map this value: ${['Check items'].output.items}.