Task 3. Add tasks

Add tasks to a playbook in Cortex XSOAR 8.10 On-prem.

Playbook tasks are the building blocks of playbooks. Tasks enable you to run scripts and sub-playbooks, communicate with end users, set conditions, and store relevant data.

Cortex XSOAR supports different task types for different actions to be taken in a playbook, and each task can receive and generate data in the form of inputs and outputs. For example, for enrichment, you might want to run an enrichment sub-playbook or a command that returns additional information for an indicator.

Tasks can be reused across playbooks and you can copy, cut, paste, and delete tasks within or between playbooks using keyboard shortcuts. To see a list of keyboard shortcuts, see Keyboard shortcuts.

The Task Library contains scripts, tasks, and playbooks. You can create new tasks from scripts, repurpose existing tasks, and use existing playbooks as sub-playbooks.

You can add a brief description for each task, explaining what the task does. Descriptions are added in the Task Description task field. When you view your playbook, clicking the icon for a task displays the description, without requiring you to open the task.

Note

To open multiple playbooks at the same time, edit the first playbook and then click the New icon next to the playbook name to create a new tab. You can either create a new playbook, or add an existing one.

Once you add tasks to your playbook, connect the tasks in their logical order by dragging and dropping a wire from one task to another.

Task type	Description
Section	Use a section header task to group related tasks to organize and manage the flow of your playbook. Section headers can also be used for time tracking between phases in a playbook. This data can be used to display in dashboards and report time trends. For example, in a phishing playbook you would have a section for the investigative phase of the playbook such as indicator enrichment, and a section for communication tasks with the user who reported the phishing. You can easily navigate playbooks and focus on the parts you need to work on by collapsing and expanding playbook sections. Collapsing sections provides a condensed view of the playbook flow, reducing visual clutter and enabling quick access to specific sections. Expanding sections allows you to view or edit specific parts of a playbook while keeping the rest of the playbook compact and maintaining focus on the relevant playbook details. You can also hover over a Section Header to highlight all tasks under the section and easily identify the section scope. For more information, see Create a section header.
Standard	Standard tasks can be manual tasks such as manual verification to prompt an analyst to verify the severity or classification of an incident before proceeding with automated actions. They can also be automated tasks such as parsing a file or enriching indicators. Automated tasks are based on scripts that exist in the system. These scripts can be created by you or come out-of-the-box as part of a content pack. For example, the !ad-get-user command retrieves detailed information about a user account using the Active Directory Query V2 integration. You can also automatically remediate an incident by interacting with a third-party integration, open tickets in a ticketing system such as Jira, or detonate a file using a sandbox. For more information, see Create a standard task.
Conditional	Use conditional tasks to validate conditions based on values or parameters and take appropriate direction in the playbook workflow, like a decision tree in a flow chart. For example, a conditional task may ask whether indicators are found. If yes, you can have a task to enrich them, and if not you can proceed to determine that the incident is not malicious. Alternatively, you can use conditional tasks to check if a certain integration is available and enabled in your system. If yes, you can use that integration to perform an action, and if not, you can continue on a different branch in the decision tree. Conditional tasks can also be used to communicate with users through a single question survey, the answer to which determines how the playbook will proceed. For more information, see Create a conditional task.
Data Collection	Use a data collection task to interact with users through a survey, for example to collect responses or escalate an incident. All responses are collected and recorded in the incident context data, from a single user or multiple users. You can use the survey questions and answers as input for subsequent playbook tasks. You can collect responses in custom fields, for example, a grid field. For more information, see Create a communication task.

Set playbook inputs and outputs

Depending on the task type that you select and the script that you are running, your playbook task may have inputs and outputs.

Inputs are data pieces used in a task. The inputs are often manipulated or enriched and they produce outputs. Outputs generated from the result of a task or command can be used as inputs to subsequent tasks or as information generated to help resolve or escalate an investigation.

An input may come from an incident, such as the role to assign an incident to, or an input can be provided by an integration, for example the Active Directory integration can be used in a task to extract a user's credentials.

At the beginning of any playbook, click the Playbook Triggered task and enter the playbook inputs and outputs, grouping them as relevant.

Use the task cheat sheet to use context keys in playbook inputs and outputs

When you create your playbook task inputs, the task cheat sheet enables quick access to system and custom fields to populate playbook task inputs and outputs.

1. Click .

   The cheat sheet opens displaying incident fields.
2. Select an incident field, it populates the task input with the corresponding context key.

   

The following example uses incident context data as the playbook input from the Access Investigation - Generic playbook.

Click the top task Playbook Triggered. The playbook is triggered based on incident context data.

Inputs

The first two inputs are SrcIP, retrieved from the incident.src key, and DstIP, retrieved from the incident.dest key.

Outputs

The Access Investigation - Generic playbook creates an output object that can be used in subsequent playbook tasks.

For example, the Access Investigation - Generic playbook Endpoint.IP output creates a list of endpoint IP addresses which can later be enriched by an IP enrichment task, and the Endpoint.MAC output creates a list of endpoint MAC addresses which can be used to get information about the hosts that were affected by the incidents.

Outputs can also be data that was extracted or derived from the inputs. For example, the Access Investigation - Generic playbook contains the Account Enrichment - Generic v2.1 sub-task, which uses the account username (and optionally domain) as input to Active Directory to retrieve user information as output, such as the user's email address, manager, and any groups to which they belong.

An output can then serve as input for a subsequent task. For example, in the Account Enrichment - Generic v2.1 sub-task, the Get account info from Active Directory task output Account.Username is used as an input for the Active Directory - Get User Manager Details task to retrieve manager details for that user.

Group playbook inputs and outputs

Playbook input and output fields are collected into groups. This organizes the inputs and outputs, providing clarity and context to understand which inputs are relevant to which playbook flow.

For example, the following playbook inputs are grouped under Mailbox selection.

Playbook group permissions

Users with permission to edit playbooks can add, edit, and delete groups and input and output fields. Users without this permission can only view groups, inputs, and outputs.

Work with playbook groups

You can do the following with groups:

• Add or delete a group. Deleting a group deletes all the fields defined in the group.
• Change the name and/or description of the group.
• Change the order groups appear by dragging.
• Collapse and expand a group.

How to add a new group

1. Click + Add Input Group or + Add Output Group.
2. Enter a group name and description and click the check mark.
3. Add fields to the group.

   Note

   If you do not add any fields, the group will be deleted when you click Save.

Manage input or output fields within a group

You can do the following with input or output fields within a group:

• Add, edit, or delete fields within a group. Input or output fields are always part of a group.
• Move fields between groups by dragging.
• Change field order within a group by dragging.

How to add an input or output field in a group

Inputs

1. Within a group, click + Add Input at the bottom of the list of input fields. You may need to scroll down to see it.
2. Enter the input field Name (required), Value, and Description.
3. When you are done adding fields, click Save.

Outputs

1. Within a group, click + Add Output or + Add Manually at the bottom of the list of output fields. You may need to scroll down to see these options.

   • If you click + Add Output, select from the outputs from previous tasks.
   • If you click + Add Manually, enter the context path and description for the output.
2. When you are done adding fields, click Save.

Create a section header

Section headers are used to manage the flow of your playbook and help you organize your tasks efficiently. You create a section header to group a number of related tasks.

Section headers can also be used for time tracking between phases in a playbook. When you start time tracking, apply the Start action for the section header. Because you are using this to time track a particular phase of an investigation, add a stop timer section header when the phase completes. The time tracking data can be used to display in dashboards and report time trends.

1. In a playbook, click + to create a task.
2. Select the Section Header option.
3. Enter a meaningful name in the Task Name field for the section header.
4. Configure the relevant fields.

   Tab	Fields in the tab
   Details	Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room. Sub Section: If selected, this section becomes a subsection of the parent section above it, and it collapses when its parent section collapses. Task description (Markdown supported): Provide a description of what this task does. In the Playbooks page, click on the section header to display the description.
   Timers	For a time tracking header, select the action to take when the timer is triggered (start, stop, or pause). Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down. Add Trigger: You can add other trigger timer fields from the drop down.

5. Click Save.

Collapse and expand playbook sections

You can easily navigate playbooks and focus on the parts you need to work on by collapsing and expanding playbook sections. Collapsing sections provides a condensed view of the playbook flow, reducing visual clutter and enabling quick access to specific sections. Expanding sections allows you to view or edit specific parts of a playbook while keeping the rest of the playbook compact and maintaining focus on the relevant playbook details. You can also hover over a Section Header to highlight all tasks under the section and easily identify the section scope.

To collapse and expand a section, in the Playbooks page, after selecting a playbook from the library or creating a new playbook and adding tasks, click on a section header.

When you collapse a section, you can see the number of tasks included under the section. For example:

Click to collapse or expand the entire playbook.

Create a standard task

Standard tasks can be manual tasks such as manual verification to prompt an analyst to verify the severity or classification of an incident before proceeding with automated actions. They can also be automated tasks such as parsing a file or enriching indicators.

1. In a playbook, click + to create a task.
2. Select the Standard option.
3. Enter a meaningful name in the Task Name field for the task that corresponds to the data you are collecting.
4. Select the options you want to configure for the Standard task.

   Standard tasks include the following field and tabs.

   Field / tab	Settings
   Choose script field	From a drop down list, select a script for the playbook to run. In the following tabs you can set: Inputs: Each script has its own set of input arguments (or none). You can set each argument to a specific value (by typing directly on the line under the argument name) or you can click the curly brackets to define a source field to populate the argument. Outputs: Each script has its own set of output arguments (or none). Mapping: Map the output from a playbook task directly to an incident field. The value for an output key populates the specified field per incident. This is a good alternative to using a task with the setIncident command. Note The output value is dynamic and is derived from the context at the time that the task is processed. As a result, parallel tasks that are based on the same output may return inconsistent results. 1. In the Mapping tab, click Add custom output mapping. 2. Under Outputs, select the output parameter whose output you want to map. Click the curly brackets to see a list of the output parameters available from the script. 3. Under Field to fill, select the field that you want to populate with the output. 4. Click Save. Advanced: Includes the following fields. Using: Choose which integration instance will execute the command, or leave empty to use all integration instances. Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "\path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb'" Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs). Execution timeout (seconds): Sets the command execution timeout in seconds. Indicator Extraction mode: Choose when to extract indicators: None: Do not perform indicator extraction Inline: Before other playbook tasks Out of band: While other tasks are running Mark results as note Mark results as evidence Run without a worker Skip this branch if this script/playbook is unavailable Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level. Details: Includes the following fields. Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room. Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs. Timers: Includes the following fields. Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down. Add Trigger: You can add other trigger timer fields from the drop down. On Error: Includes the following fields. Number of retries: How many times the task should retry running if there is an error. Default is 0. Retry interval (seconds): How long to wait between retries. Default is 30 seconds. The maximum retry interval is 800 seconds (13.3 minutes). If you enter a value greater than 800 seconds, the retry interval will be limited to 800 seconds. Error handling: How the task should behave if there is an error. Options are: Stop Continue Continue on error path(s) This option configures the task to handle potential errors that may occur when executing the current task's script.
   Manual task settings tab	Default assignee: Assign an owner to this task. Only the assignee can complete the task: Stop the playbook from proceeding until the task assignee completes the task. By default, in addition to the task assignee, the default administrator can also complete the blocked task. You can also block tasks until a user with an external email address completes the task. Task SLA: Set the SLA in granularity of weeks, days, hours, and minutes. Set task Reminder at: Set a reminder for the task in granularity of weeks, days, hours, and minutes.
   Advanced tab	Quiet Mode: Determines whether this task uses the playbook default setting for quiet mode. When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.
   Details tab	Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room. Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
   Timers tab	Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop down. Add Trigger: You can add other trigger timer fields from the drop down.

Create a conditional task

Conditional tasks are used for determining different paths for your playbook. For example, in a playbook for handling phishing emails, a conditional task can be used to check if an email contains suspicious attachments. If the attachment is identified as malicious, the playbook can automatically quarantine the email; otherwise, it can proceed to manual review by a security analyst.

Conditional task types

You can create different types of conditional tasks.

• Built-in: Creates a logical statement using an entity from within the playbook. For example, in an access investigation playbook, you can determine that if the Asset ID of the person whose account was being accessed exists in a VIP list, set the incident severity to High. Otherwise, proceed as normal.
• Manual: Creates a conditional task that must be manually resolved. For example, a security analyst is prompted to review and validate a suspicious file. The playbook task might involve instructions for the analyst to analyze the file, determine if it is malicious, and provide feedback or take specific actions based on their assessment.
• Ask: Creates a single-question survey communication task. The answer determines how the playbook proceeds. For more details, see Create a communication task.
• Choose script: Creates a conditional task based on the result of a script. For example, check if an IP address is internal or external using the IsIPInRanges script. When using a script, the inputs and outputs are generated by the automation script.

How to create a conditional task

1. In a playbook, click + Create Task.
2. Select the Conditional option.
3. In the Task Name field, type a meaningful name for the task that corresponds to the data you are collecting.
4. Select the relevant conditional task option. Some field configurations are required, and some are optional.

Built-in

• Condition: Define one or more logical conditions for the task.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
• Timers: Includes the following fields.

  • Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop-down.
  • Add Trigger: You can add other trigger timer fields from the drop-down.
• Advanced: Determines whether this task uses the playbook default setting for Quiet Mode. When in Quiet Mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn Quiet Mode on or off at the task or playbook level.
• On Error: Includes the following fields.

  • Number of retries: How many times the task should retry running if there is an error. Default is 0.
  • Retry interval (seconds): How long to wait between retries. Default is 30 seconds.

Manual

• Manual task settings: Include the following fields.

  • Default assignee: Assign an owner to this task.
  • Only the assignee can complete the task: Stop the playbook from proceeding until the task assignee completes the task. By default, in addition to the task assignee, the default administrator can also complete the blocked task. You can also block tasks until a user with an external email address completes the task.
  • Task SLA: Set the SLA in granularity of weeks, days, hours, and minutes.
  • Set task Reminder at: Set a reminder for the task in granularity of weeks, days, hours, and minutes.
• Advanced: Determines whether this task uses the playbook default setting for Quiet Mode. When in Quiet Mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn Quiet Mode on or off at the task or playbook level.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
• Timers: Include the following fields.

  • Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop-down.
  • Add Trigger: You can add other trigger timer fields from the drop-down.

Ask

• Message: Includes the following fields.

  • Ask by: The method for sending the message and survey. Options are:

    • Task (can always be completed directly in the Workplan)
    • Generated link (appears in the context data)
    • Email
  • To: The message and survey recipients. You can define by:

    • Selecting from a predefined drop down list.
    • Manually typing email addresses for users and/or external users.
    • Clicking the context icon to define recipients from a context data source.
  • CC of the email: A CC email address.
  • Subject of the email: The message subject that displays to message recipients. You can write the survey question in the subject field or in the message body field.
  • Message body: The text that displays in the body of the message. This field is optional, but if you don't write the survey question in the subject field, include it in the message body. This is a long-text field.
  • Reply options: Reply options are sent via the selected channels as options for an answer.
  • Require users to authenticate: Enable this option to have your SAML or AD authenticate the recipient before allowing them to answer. You must first set up an authentication integration instance and check Use this instance for external users authentication only in the integration instance settings.
• Timing: Includes the following fields.

  • Retry interval (minutes): Determines the wait time between each execution of a command. For example, the frequency (in minutes) that a message and survey are resent to recipients before the response is received.
  • Number of retries: Determines how many times a command attempts to run before generating an error. For example, the maximum number of times a message is sent. If a reply is received, no additional retry messages will be sent.
  • Task SLA: Set the SLA in granularity of weeks, days, and hours.
  • Set task Reminder at: Set a task reminder in granularity of weeks, days, and hours.
  • Complete automatically if SLA passed without a reply: Select this checkbox to complete the task if the SLA is breached before a reply is received. You can select yes or no.
• Advanced: Includes the following fields.

  • Using: Choose which integration instance will execute the command, or leave empty to use all integration instances.
  • Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "\[path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb'\]"
  • Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs).
  • Execution timeout (seconds): Sets the command execution timeout in seconds.
  • Indicator Extraction mode: Choose when to extract indicators:

    • None: Do not perform indicator extraction
    • Inline: Before other playbook tasks
    • Out of band: While other tasks are running
  • Mark results as note
  • Mark results as evidence
  • Run without a worker
  • Skip this branch if this script/playbook is unavailable
  • Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.

Choose script

From a drop down list, select a script for the playbook to run. In the following tabs you can set:

• Inputs: Each script has its own set of input arguments (or none). You can set each argument to a specific value (by typing directly on the line under the argument name) or you can click the curly brackets to define a source field to populate the argument.
• Outputs: Each script has its own set of output arguments (or none).
• Mapping:

  Map the output from a playbook task directly to an incident field.

  The value for an output key populates the specified field per incident. This is a good alternative to using a task with a set incident command.

  The output value is dynamic and is derived from the context at the time that the task is processed. As a result, parallel tasks that are based on the same output may return inconsistent results.

  1. In the Mapping tab, click Add custom output mapping.
  2. Under Outputs, select the output parameter whose output you want to map. Click the curly brackets to see a list of the output parameters available from the automation.
  3. Under Field to fill, select the field that you want to populate with the output.
  4. Click Save.
• Advanced: Includes the following fields.

  • Using: Choose which integration instance will execute the command, or leave empty to use all integration instances.
  • Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "\[path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb'\]"
  • Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs).
  • Execution timeout (seconds): Sets the command execution timeout in seconds.
  • Indicator Extraction mode: Choose when to extract indicators:

    • None: Do not perform indicator extraction
    • Inline: Before other playbook tasks
    • Out of band: While other tasks are running
  • Mark results as note
  • Mark results as evidence
  • Run without a worker
  • Skip this branch if this script/playbook is unavailable
  • Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.
• Details: Includes the following fields.

  • Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room.
  • Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
• Timers: Include the following fields.

  • Timer.start: The trigger for starting to send a message or survey to recipients. You can change this trigger or add a trigger for Timer.stop or Timer.pause. Select the trigger timer field from the drop-down.
  • Add Trigger: You can add other trigger timer fields from the drop-down.
• On Error: Includes the following fields.

  • Number of retries: How many times the task should retry running if there is an error. Default is 0.
  • Retry interval (seconds): How long to wait between retries. Default is 30 seconds.
  • Error handling: How the task should behave if there is an error. Options are:

    • Stop
    • Continue
    • Continue on error path(s)

      This option configures the task to handle potential errors that may occur when executing the current task's script.

1. Click Save.

Create a communication task

Communication tasks enable you to send surveys to users, both internal and external, to collect data for an incident. The collected data can be used for incident analysis, and also as input for subsequent playbook tasks. For example, you can send a scheduled survey requesting analysts to send specific incident updates or send a single (stand-alone) question survey to determine how an issue was handled.

There are two types of communication tasks:

• Ask tasks: A conditional task that sends a single question survey. The answer is used to determine how the playbook proceeds.
• Data collection tasks: A data collection task sends a survey of one or more questions. The answers are recorded in context data and can be used as input for subsequent tasks.

About Ask tasks

An ask task is a type of conditional task that sends a single-question survey, the answer to which determines how a playbook proceeds. If you send the survey to multiple users, the first answer received is used, and subsequent responses are disregarded. For more information about ask task settings, see Create a conditional task.

Because this is a conditional task, you need to create a condition for each of the answers. For example, if the survey answers include, Yes, No, and Maybe, there should be a corresponding condition (path) in the playbook for each of these answers.

Users interact with the survey directly from the message, meaning the question appears in the message and they click an answer from the message.

The survey question and the first response is recorded in the incident context data. This enables you to use this response as the input for subsequent playbook tasks.

For all ask conditional tasks, a link is generated for each possible answer the recipient can select. If the survey is sent to more than one user, a unique link is created for each possible answer for each recipient. These links are visible in the context data of the incident's Work Plan. The links appear under Ask.Links in the context data.

In this example, the message and survey will be sent to recipients every hour for six hours, until a reply is received (it is repeated every 60 minutes, 6 times). The SLA is six hours. If the SLA is breached, the playbook will proceed according to the Yes condition.

ask-timer.png

In this example, a message and survey are sent by email to all users with the Analyst role. We are not including a message body because the message subject is the survey question we want recipients to answer. There are three reply options: Yes, No, and Not sure. In the playbook, we will only add conditions for the Yes and No replies. We require recipient authentication, which first involves setting up authentication.

ask-task-example-email-8-4.png

Create a data collection task

The data collection task is a multi-question survey (form) that survey recipients access from a link in the message. Users do not need to log in to access the survey, which is located on a separate site.

All responses are collected and recorded in the incident context data, whether you receive responses from a single user or multiple users. This enables you to use the survey questions and answers as input for subsequent playbook tasks. If responses are received from multiple users, data for multi-select fields and grid fields are aggregated. For all other field types, the response received most recently will override previous responses as it displays in the field. All responses are always available in the context data.

For all data collection tasks, a single link is generated for each recipient of the survey. These links are visible in the context data of the incident's Work Plan. The links appear in the context data under the Links section of that survey.

You can include the following types of questions in the survey.

• Stand alone questions. These are presented to users directly in the message, and from which users answer directly in the message (not an external survey).
• Field-based questions. These are based on a specific incident field (either system or custom), for example, an Asset ID field. The response (data) received for these fields automatically populates the field for this Incident. For single-select field based questions, the default option is taken from the field’s defined default.

How to create a Data Collection task

1. In a playbook, click + to create a new task.
2. Select the Data Collection option.
3. Enter a meaningful name in the Task Name field for the task that corresponds to the data you are collecting.
4. Select the communication options you want to use to collect the data.

   Tabs and configuration fields

   Tab	Configuration fields in the tab
   Message	Ask by: The method for sending the message and survey. Options are: Task (can always be completed directly in the Workplan) Generated link (appears in the context data): A link to the data collection survey is available in the context data of the task. Email: If you select this option, enter below the subject and message of the email and the email addresses of the users who should receive this message or survey. To: The message and survey recipients. You can define by: Selecting from a predefined drop down list. Manually typing email addresses for users and/or external users. Clicking the context icon to define recipients from a context data source. CC of the email: A CC email address. Subject of the email: The message subject that displays to message recipients. You can write the survey question in the subject field or in the message body field. Message body: The message question body to be used in the notification sent to the given users along with the reply options. Require users to authenticate: Enable this option to have your SAML or AD authenticate the recipient before allowing them to answer. You must first set up an authentication integration instance and check Use this instance for external users authentication only in the integration instance settings.
   Questions	Web Survey Title: The title displayed for the web survey. Short Description: A description displayed above the questions on the web survey. Click Preview to see how it displays. Question: A question to ask recipients. Answer Type: The field type for the answer field. Options are: Short text Long text Number Single Select (requires you to define a reply option) Multi select/Array (requires you to define a reply option) Date picker Attachments Mandatory: If this checkbox is selected for a question, survey recipients will not be able to submit the survey until they answer this question. Help Message: The message that displays when users hover over the question mark help button for the survey question. Placeholder: A sample value displayed until a real value is entered. You can drag questions to rearrange the order in which they display in the survey.
   Timing	Retry interval (minutes): Determines the wait time between each execution of a command. For example, the frequency (in minutes) that a message and survey are resent to recipients before the response is received. Number of retries: Determines how many times a command attempts to run before generating an error. For example, the maximum number of times a message is sent. If a reply is received, no additional retry messages will be sent. Retries are not supported for data collection tasks that have errors sending emails (indicated by a server timeout). This is because retries only work on automation execution failures, not on email delivery issues. Task SLA: Set the SLA in granularity of weeks, days, and hours. Set task Reminder at: Set a task reminder in granularity of weeks, days, and hours. Complete automatically if: Reached task SLA (with or without a reply): This option is grayed out. Received <enter a number> reply
   Details	Tag the result with: Add a tag to the task result. You can use the tag to filter entries in the War Room. Task description (Markdown supported): Provide a description of what this task does. You can enter objects from the context data in the description. For example, in a communication task, you can use the recipient’s email address. The value for the object is based on what appears in the context every time the task runs.
   Advanced	Using: Choose which integration instance will execute the command, or leave empty to use all integration instances. Extend context: Append the extracted results of the action to the context. For example, "newContextKey1=path1::newContextKey2=path2" returns "[path1:'aaa',path2: 'bbb', newContexKey1: 'aaa',newContextKey2:'bbb']" Ignore outputs: If set to true, will not store outputs into the context (besides the extended outputs). Execution timeout (seconds): Sets the command execution timeout in seconds. Indicator Extraction mode: Choose when to extract indicators: None: Do not perform indicator extraction Inline: Before other playbook tasks Out of band: While other tasks are running Mark results as note Mark results as evidence Run without a worker Skip this branch if this script/playbook is unavailable Quiet Mode: When in quiet mode, tasks do not display inputs and outputs or extract indicators. Errors and warnings are still documented. You can turn quiet mode on or off at the task or playbook level.

5. (Optional) To customize the look and feel of your email message, click Preview.

   You can determine the color scheme and how the text in the message header and body appears, as well as the appearance and text of the button the user clicks to submit the survey.

Data collection task examples

Stand-alone question with a single-select answer

In this example, we create a stand-alone question with a single-select answer. This question is not mandatory. If we select the First option is default checkbox, the reply option "0" is the default value in the answer field.

data-collection-eg.png

In this example, we create a question based on a custom grid field that is marked as mandatory. For the question field, we included a descriptive sentence explaining how to fill in the grid.

data-collection-task-example-field-based-8-0.PNG

Configure communication task authentication

When sending a form in a communication task, you can configure user authentication to ensure only authorized users gain access to the form.

The authorized users are usually external, not in Cortex XSOAR, and they will not be able to access anything else in Cortex XSOAR.

Set up playbook communication task authentication

1. Set up your SSO if it is not already configured. See Authenticate users using SSO for more details.
2. In the Task details of your playbook communication task, check Require users to authenticate to have your SAML or AD authenticate the recipient before allowing them access to the form.

   

   playbook-comm-task-authenticate-2.png

Configure script error handling in a playbook

You can determine how the playbook behaves if there are script errors during execution.

When defining a standard task that uses a script or a conditional task that uses an script, you can define how a playbook task continues by selecting one of the following options:

• Stop: The playbook stops, if the task errors during execution. For example, if the task requires a manual review, you may want the playbook to stop until completion.
• Continue: The playbook continues to execute if the task errors. For example, the playbook task requires EWS, but EWS is not required for the playbook to proceed.
• Continue on error path: If a task errors, the playbook continues on an error path.

  The error path may be useful if you want to take action on an error, like clean-up, retry, etc. You may also want to handle errors in different ways. For example, in case of a quota expired error you may want to retry in 1 minute, but if you receive an internal error 500, you may want to stop the playbook.

  You may want to create a separate path when an analyst manually reviews the incident and research is needed outside Cortex XSOAR. Once an analysis is complete, you can add a task to consider escalating to a customer and, if so, generate a report which can be attached to a ticket system such as Jira or ServiceNow.

  Instead of a playbook waiting on manual input, which displays an error state, such as missing an argument in a script, you can add a separate path for these kinds of issues.

Use the GetErrorsFromEntry script (part of the Common Scripts Pack) to check whether the given entry returns an error and returns an error message. For example, when using the script in a playbook, you can fetch the error message from a given task, such as a runtime error. You can then add a step in the playbook flow to send those error messages to the relevant stakeholder through Slack, email, opening a Jira ticket, etc.

When errors are created, they are added to context under task.id.error.

How to set up error handling in your playbook

1. When adding the connector from this task to the following task, a dialog box appears which enables you to select one of the following paths:

   In a playbook, edit or create a new task by clicking +.

   If the task library is expanded, click + Create Task.
2. Select the task type you want to create or edit.

   You can set up script error handling when running a script in a Standard task or a Conditional task.

   Built-in Conditional tasks have On Error settings for number of retries and retry interval, but not Error Handling.
3. For new tasks, in the Task Name field, type a meaningful name for the task that corresponds to the data you are collecting.
4. Click the On Error tab.
5. In the Number of retries field, type the number of times the task attempts to run before generating an error.
6. In the Retry Interval (seconds) field, type the wait time between retrying the task.
7. In the Error Handling field, select one of the following:

   • Stop
   • Continue
   • Continue on error path(s)
8. Click Save.
9. When adding the connector from this task to the following task, a dialog box appears which enables you to select one of the following paths:

   • Standard Path: When adding a task to this path, it executes without any exceptions.

     If you select the Standard Path, the task continues on this path and executes without exceptions.
   • Error Path: When adding a task to this path, it executes where the source task errors during execution.

     If you select Error path, if the task errors, the playbook continues with this path.