diff --git a/docs/platform-services/automation-service/automation-service-playbooks.md b/docs/platform-services/automation-service/automation-service-playbooks.md index 73ecd9af97..57451ad5f3 100644 --- a/docs/platform-services/automation-service/automation-service-playbooks.md +++ b/docs/platform-services/automation-service/automation-service-playbooks.md @@ -200,7 +200,7 @@ A filter node filters results from the preceding action based on the condition y 1. [Add an action node](#add-an-action-node-to-a-playbook). 1. Hover your mouse over an action node and click the **+** button. The available nodes are displayed.
Add filter node 1. Click **Filter**. The filter node configuration dialog displays.
Add filter node conditions -1. (Optional) Use **Split by** to select an output if it is a list (array) and you want to evaluate each item separately. Each item in the list is checked against the filter condition. If the condition is true for an item, the item is passed to the next node. (If you do not use the **Split by** field on an output that is a list, then if the condition is true for any item in the list, the entire list moves forward to the next node.) +1. (Optional) Use **Split by** to select an output if it is a list (array) and you want to evaluate each item separately. See ["Split by" field in a filter node](#split-by-field-in-a-filter-node) for more information. 1. Configure the conditions you want to use for filtering. 1. Deselect the **Cartesian product** checkbox. :::warning @@ -699,6 +699,52 @@ Following are examples of payloads from different trigger types: } ``` +## Handling arrays in playbooks + +An array is a collection of related data values grouped together. When you are handling output from a playbook action, you may want to treat the entire array as a single item you want to pass to the next action, or you may want to treat each element in the array as a separate item. In playbooks, you can do either. + +### Arrays in text areas + +When you create an action, sometimes you are presented with a text area that includes an "Insert placeholder" icon Insert placeholder icon. When you click the icon, it allows you to add placeholders to the text area for input or output. + +Perform the following steps to add a placeholder to a text area to handle an array in output from a previous action. This allows you to process an array as a single element or multiple elements. +1. [Create a playbook](#create-a-new-playbook) and [add action nodes](#add-an-action-node-to-a-playbook). +1. Edit an action node that displays a text area. +1. In the following example, the **Send Email** action shows text areas for the email's subject, body, and HTML. Click an "Insert placeholder" icon Insert placeholder icon for one of the fields, for example, **HTML Content**.
Insert placeholder icon +1. Select a value from a previous action. In this example, we'll choose **Get Insight**.
Get value from previous action +1. Select **Outputs**. Only the arrays in the output show these icons: Icons on arrays in output
Get value from previous action outputs +1. Click the icon for how you want the array to be handled by the action: + * Loop through elements in the array **Loop**. Loops through the array so that the action is run for each item in the array. + * Combine all elements in the array **Combine**. Combines all items in the array into a single value run by the action. +1. The variable is inserted into the text area preceded by the icon for whether the contents of the array are looped or combined.
Example of looped array variable + +In this example, the action will be run for each item in the array ("looped"). + +:::note +The [**Cartesian Product**](#cartesian-product) checkbox is disabled if any variable is selected using the loop feature in the text area. +Cartesian Product checkbox disabled +::: + +### Cartesian product + +The **Cartesian product** checkbox appears on nodes you add to playbooks. Clicking this checkbox causes the node to use the [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product) method to loop through items in arrays processed by the node. + +Cartesian product checkbox + +For example, suppose one input field is for signal name, and another is for signal value. If you have 2 arrays like this, and each array has 3 items, the Cartesian product evaluation pairs each item from the first set with each item from the second set, which will produce 9 pairs (3x3). Without Cartesian product evaluation, only matching position items are paired, which will produce 3 pairs (equal to the number of items). + +:::warning +Use the **Cartesian product** checkbox with caution. For most cases, deselect the **Cartesian product** checkbox when creating playbooks. Large array fields in the input can result in the action being called many times, causing the action to exceed the [actions limit](/docs/platform-services/automation-service/about-automation-service/#actions-limit). Only select this checkbox if you want to evaluate data from array input fields using the Cartesian product method. +::: + +### "Split by" field in a filter node + +When you [add a filter node](#add-a-filter-node-to-a-playbook), use the **Split by** field to evaluate each item separately in arrays (lists). + +Split by field + +Each item in arrays is checked against the filter condition. If the condition is true for an item, the item is passed to the next node. If you do not use the **Split by** field on an output that is a list, then if the condition is true for any item in the list, the entire list moves forward to the next node. + ## Troubleshoot playbooks You can run playbooks in automations for [monitors](/docs/alerts/monitors/use-playbooks-with-monitors/), [Cloud SIEM](/docs/cse/automation/automations-in-cloud-siem/), or [Cloud SOAR](/docs/cloud-soar/automation/). If a playbook has a problem when it runs in an automation, an error message often displays in the playbook providing information about the problem. diff --git a/docs/reuse/cartesian-product.md b/docs/reuse/cartesian-product.md index 50b9bc6629..420dd34270 100644 --- a/docs/reuse/cartesian-product.md +++ b/docs/reuse/cartesian-product.md @@ -1 +1 @@ -Use the **Cartesian product** checkbox with caution. Large array fields in the input can result in the action being called many times, causing the action to exceed the [actions limit](/docs/platform-services/automation-service/about-automation-service/#actions-limit). Only select this checkbox if you want to evaluate data from array input fields using the [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product) method. For example, suppose one input field is for signal name, and another is for signal value. If you have 2 arrays like this, and each array has 3 items, the Cartesian product evaluation pairs each item from the first set with each item from the second set, which will produce 9 pairs (3x3). Without Cartesian product evaluation, only matching position items are paired, which will produce 3 pairs (equal to the number of items). \ No newline at end of file +Use the **Cartesian product** checkbox with caution. In most cases, you should deselect this checkbox. For more information, see [Cartesian product](/docs/platform-services/automation-service/automation-service-playbooks/#cartesian-product). \ No newline at end of file diff --git a/static/img/platform-services/automation-service/array-icon-combine.png b/static/img/platform-services/automation-service/array-icon-combine.png new file mode 100644 index 0000000000..adf11f4954 Binary files /dev/null and b/static/img/platform-services/automation-service/array-icon-combine.png differ diff --git a/static/img/platform-services/automation-service/array-icon-loop.png b/static/img/platform-services/automation-service/array-icon-loop.png new file mode 100644 index 0000000000..581ab41896 Binary files /dev/null and b/static/img/platform-services/automation-service/array-icon-loop.png differ diff --git a/static/img/platform-services/automation-service/playbook-array-looped-example.png b/static/img/platform-services/automation-service/playbook-array-looped-example.png new file mode 100644 index 0000000000..45230ee039 Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-array-looped-example.png differ diff --git a/static/img/platform-services/automation-service/playbook-cartesian-product-disabled.png b/static/img/platform-services/automation-service/playbook-cartesian-product-disabled.png new file mode 100644 index 0000000000..aac1e23d0a Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-cartesian-product-disabled.png differ diff --git a/static/img/platform-services/automation-service/playbook-get-value-from-previous-action-2.png b/static/img/platform-services/automation-service/playbook-get-value-from-previous-action-2.png new file mode 100644 index 0000000000..4ccda6e8c6 Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-get-value-from-previous-action-2.png differ diff --git a/static/img/platform-services/automation-service/playbook-get-value-from-previous-action.png b/static/img/platform-services/automation-service/playbook-get-value-from-previous-action.png new file mode 100644 index 0000000000..e5f4ca474e Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-get-value-from-previous-action.png differ diff --git a/static/img/platform-services/automation-service/playbook-insert-placeholder-icon.png b/static/img/platform-services/automation-service/playbook-insert-placeholder-icon.png new file mode 100644 index 0000000000..eb694f1e47 Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-insert-placeholder-icon.png differ diff --git a/static/img/platform-services/automation-service/playbook-split-by.png b/static/img/platform-services/automation-service/playbook-split-by.png new file mode 100644 index 0000000000..92342f34e9 Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-split-by.png differ diff --git a/static/img/platform-services/automation-service/playbook-variables-in-text-boxes.png b/static/img/platform-services/automation-service/playbook-variables-in-text-boxes.png new file mode 100644 index 0000000000..c18db49e88 Binary files /dev/null and b/static/img/platform-services/automation-service/playbook-variables-in-text-boxes.png differ diff --git a/static/img/platform-services/automation-service/playbooks-cartesian-product-checkbox.png b/static/img/platform-services/automation-service/playbooks-cartesian-product-checkbox.png new file mode 100644 index 0000000000..130bf1680d Binary files /dev/null and b/static/img/platform-services/automation-service/playbooks-cartesian-product-checkbox.png differ diff --git a/static/img/platform-services/automation-service/playbooks-output-arrays-icons.png b/static/img/platform-services/automation-service/playbooks-output-arrays-icons.png new file mode 100644 index 0000000000..a73616d59b Binary files /dev/null and b/static/img/platform-services/automation-service/playbooks-output-arrays-icons.png differ