> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.7/configure-cortex-xsoar/playbooks/customize-your-playbook/configure-a-sub-playbook.md).
# Configure a sub-playbook
Playbooks can be divided into two categories, depending on their use.
* Parent playbooks are playbooks that run as the main playbook of an incident. For example, [Phishing - Generic v3](https://xsoar.pan.dev/docs/reference/playbooks/phishing---generic-v3) and [Malware Investigation & Response Incident Handler](https://xsoar.pan.dev/docs/reference/packs/malware-investigation-and-response).
* Sub-playbooks are playbooks that are nested under other playbooks. They appear as tasks in the parent playbook flow and are indicated by the sub-playbook icon . A sub-playbook can also be a parent playbook in a different use case. For example, [IP Enrichment - Generic v2](https://xsoar.pan.dev/docs/reference/playbooks/ip-enrichment---generic-v2) and [Retrieve File From Endpoint - Generic v3](https://xsoar.pan.dev/docs/reference/playbooks/retrieve-file-from-endpoint---generic-v3). These playbooks are usually used as part of a bigger investigation.
Since sub-playbooks are building blocks that can be used in other playbooks and use cases, you should define generic inputs for them.
Inputs can be passed to sub-playbooks from the parent playbook, used and processed in the sub-playbook, and sent as output to the parent playbook.
{% hint style="info" %}
### Note
Any change made to a sub-playbook impacts the parent playbook in the next run of the parent playbook.
{% endhint %}
See this video for an example of creating a sub-playbook: [Sub-playbooks](https://www.youtube.com/watch?v=sPp5PXgFg1A).
**Sub-playbook loops**
Looping uses sub-playbooks to create loops within a parent playbook. When running the loop, the values are calculated based on the context data for the sub-playbook and not the parent playbook.
{% hint style="info" %}
### Note
Consider the following when adding a loop:
* The maximum number of loops (default is 100). A high number of loops or a high wait time combined with a large number of incidents may affect performance.
* Periodically check looping conditions to ensure they are still valid for the data set.
* When the task input is an array, it is iterated automatically (no need to define a loop).
{% endhint %}
How to create a sub-playbook loop
1. In the **Playbooks** page, select the parent playbook that contains the sub-playbook task you want to run in a loop.
2. Click **Edit**.
If the playbook is installed from a content pack, you need to either detach or duplicate the playbook before editing.
3. Select the task that contains the sub-playbook for which you want to create the loop.
4. Click the **Loop** tab.
5. Click one of the following options to define loop settings:
* **None**: (Default) The sub-playbook does not loop.
* **Built-in**: Use built-in functions to define loop settings:
| Option | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Exit when | Enables you to define when to exit the loop. Click {} and expand the source category. Hover over the required source and click **Filter & Transform** to the left of the source to manipulate the data. |
| Equals (String) | Select the operator to define how the values should be evaluated. |
| Max iterations | The number of times the loop should run. |
| Sleep | The number of seconds to wait between iterations.
recommends that you balance between the number of iterations and the number of seconds to wait between iterations so you don't overload the server.
|
* **For each input**: Runs the sub-playbook based on defined inputs. Enter the number of seconds to wait between iterations.
* **Choose Loop automation**: Select the automation from the drop-down list to define when to exit the loop. The parameters that appear are applicable to the selected automation.
6. To save the changes, click **OK**.
Example: Exit looping after running for each input
In the parent playbook (the task that contains the sub-playbook), you can configure to exit a loop running the sub-playbook automatically when the last item in the sub-playbook input is executed.
* If the input is a single item, the sub-playbook runs once, but if the input is a list of items (such as a list of incident IDs), the sub-playbook runs as many times as there are items in the list. Each iteration of the sub-playbook uses the next item in the list as the input.
* If there are multiple input lists with the same amount of items, the sub-playbook runs once for each set of inputs.
* If there are multiple input lists with different amounts of items, the sub-playbook runs the first set of inputs, followed by the second, third, and so on, until the end.
For example:
| Input | Value |
| ------- | ------- |
| Input x | 1,2,3,4 |
| Input y | a,b,c,d |
| Input z | 9 |
The first loop: 1, a, 9
The second loop: 2, b, 9
The third loop: 3, c, 9
The fourth loop: 4, d, 9
The following example shows how a sub-playbook loop works using the **Palo Alto Networks Cortex XDR - Investigation and Response integration**.
After you install the **Palo Alto Networks Cortex XDR - Investigation and Response** content pack, configure the **Palo Alto Networks Cortex XDR - Investigation and Response** integration to fetch incidents. By default, the integration uses the `Cortex XDR` classifier, which automatically classifies `Cortex XDR` incident types. In this example, we are using the `Cortex XDR` incident type which runs the **Cortex XDR incident handling v3** playbook.
{% hint style="info" %}
### Note
Verify the integration is enabled to fetch incidents.
{% endhint %}
1. Go to **Incidents**, open a Cortex XDR incident, and go to the **Work Plan** tab.
You can see the incident uses the **Cortex XDR incident handling v3** playbook.
2. The playbook starts retrieving incident data from Cortex XDR and finds similar incidents by fields. If similar incidents are found, the analyst can close them as duplicates.
3. If the alert is not a duplicate, the playbook continues to **Loop on alert id - Alert enrichment**.
4. The playbook runs the **Cortex XDR Alerts Handling** sub-playbook in a loop, by categorizing and enriching alerts until completion.
* Under the **Inputs Results** tab, you can see the **`alert_ID`** that the playbook processes.
To view the looping settings, go to **Playbooks** and open the **Cortex XDR Alerts Handling** playbook. In the **Inputs** tab, view the playbook returns incident and alerts IDs. In the **Loop** tab, the **For Each Input** option is selected. This means the playbook iterates over all defined playbook inputs until complete.
* The playbook determines if the alert is malware, a port scan, or anything else and enriches according to the category.
* If the alert is malware, the **Malware** sub-playbook runs.
* If the alert is a port scan, the **Port Scan** sub-playbook runs.
* If the alert is not malware or port scan, the playbook completes the processing.
* The applicable sub-playbook processes the enriched information and outputs the problematic endpoints.
* After completing the processing of an alert ID, the playbook iterates through the remaining inputs until all alert IDs have been processed (looping).
* Go to the **Cortex XDR Alerts Handling** playbook task and click the **Results** tab. You can see information returned and the number of times the playbook looped.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.7/configure-cortex-xsoar/playbooks/customize-your-playbook/configure-a-sub-playbook.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.