Specify a datapath in your playbook

Playbooks work with data values from the playbook's container, its artifact CEF values, the results of an action or playbook that was previously run, or static data. You specify this data using datapaths within most playbook blocks.

When you add a playbook block, you specify the datapath in the configuration panel for that block. After the initial configuration, select the block to open its configuration panel.

To specify the datapath, follow these steps:

1. In the playbook block configuration panel, select the parameter you want to specify. Available parameters are based on the type of block. For example, you might specify an if statement in a utility block or as a container ID for an action block, shown in this image. The datapath picker appears.



2. In the datapath picker, select the starting location for the data, including events, incident, and playbook. More specific data options display based on your selection. Select the data type to use for your playbook input. Use the search field to narrow down the list, if needed. In the previous example, a user selected the input ip, then the starting location artifacts, and then, from the artifact fields, src.
• For specific input data types, like IP, only appropriate data types display by default, indicated by the callout box in the example image. You can choose to clear the filter to show all possible data types.
• CEF values are described in more detail in Datapaths and CEF fields, later in this topic.
• Within the datapath picker, you can use the single-line up and down arrow () icons to navigate results. You can also expand or collapse the lists by using the double-line up and down arrow () icons.
• If you have paired Splunk SOAR with Splunk Enterprise Security, see the next section.
3. After you complete your selections, the datapath displays in the parameter field.
4. For multiple parameters, repeat this process for each additional parameter.

The datapath that appears in the parameter field might differ slightly from the names you selected in the datapath picker. This is due to internal mappings and is expected.

You can edit the generated datapath if you choose. For example, you might want to change the final section to point to a different variable. If you prefer, you can enter the datapath directly, without using the datapath picker. For details on the different sections of the datapath, see the next section, Datapath structure.

Use Splunk Enterprise Security data

You can specify Splunk Enterprise Security data in a datapath when you pair with Splunk Enterprise Security. When the two security solutions are paired, the first panel of the datapath picker is divided into two sections:

• Enterprise Security: Section to specify datapaths from findings in Splunk Enterprise Security or any outputs from Enterprise Security API blocks.
• Splunk SOAR: Section to specify datapaths with Splunk SOAR data, including artifacts, events, and playbooks.

Select a data type from the appropriate section and proceed as described in the previous section.

Enterprise Security datapaths follow a similar structure to Splunk SOAR datapaths.

For details on Splunk Enterprise Security data types, see Administer Splunk Enterprise Security.

Datapaths in the Data preview panel

You can copy datapaths that appear in the Data preview panel and paste them into the configuration panel for any playbook block. For details on using the Data preview panel, see Use Data Preview to build, test, and edit playbooks.

Datapath structure

Datapaths have the same general structure, shown in the following image and described here. Datapaths with CEF fields are described in the next section, Datapaths and CEF fields.

• The name before the last colon describes the data's location. Examples include: artifact, custom_function, playbook_input, and an action block name like run_query_1. The datapath might contain multiple names before the last colon, which indicate block names in your playbook.
• Everything after the last colon is the JSON-compatible structure for the data's location.
  • Periods ( . ) denote moving down a layer into the data structure.
  • Asterisks ( * ) denote arrays or lists. If the data is not an array or a list, there is no asterisk.

The example shown in the previous image has the following specific structure:

• The name artifact denotes the object where the data is located
• The asterisk ( * ) denotes that you are iterating through all artifacts, rather than just one.
• The period ( . ) moves you down one layer.
• The name severity is the data for the artifact's metadata field.

attempts to access the value at that location and return a list of values based on how many artifacts it searched. If that datapath is empty, returns a list of None values.

Splunk SOAR (Cloud) uses dotted notation to delineate between keys in a JSON structure. Splunk SOAR (Cloud) does not currently support field names with periods in them.

Datapaths and CEF fields

Common Event Format (CEF) fields are a system of key-value pairs with data about artifacts. For details about CEF fields, see Create custom CEF fields in .

Datapaths with CEF fields are similar to other datapaths described in the previous section, but they include the cef key within the datapath and usually have at least two period separators.

The example shown in the image has the following specific structure:

• The name artifact denotes the object where the data is located
• The asterisk ( * ) denotes that you are iterating through all artifacts rather than just one.
• The first period ( . ) moves you down one layer.
• The cef key denotes a CEF field.
• The second period ( . ) moves you down another layer into the data.
• sourceHostName is the key for the source's host name.

CEF fields as action results

When an action block receives CEF data as an input, it creates result CEF data output, which is correlated to the input data through the artifact ID. You can access that action result CEF data from any playbook block located downstream from the action block that created it. For example, you might want to run an IP reputation action on a list of source addresses. Your datapaths might look like this:

• input datapath: artifact:*.cef.sourceAddress
• action name: ip_reputation
• output datapath: ip_reputation_1:artifact:*.cef.sourceAddress

The following diagram shows how when 2 artifacts are processed by the IP reputation action, the action result data corresponds to the input data and includes all of the artifact's data.

User-based datapaths

You can dynamically specify a user associated with a playbook without knowing their name or ID. For example, you might want to send a message to, or refer to, the user who initiated the current run of a playbook, rather than to a group or admin who might not know as much about the current playbook. For playbooks launched by automation, the result is automation.

Action, code, custom function, decision, and filter blocks

In the playbook block configuration, select playbook, then launching_user, then specify either the id or name of the user who launched the current run of this playbook.

Prompt blocks

In the prompt block User or Role configuration, specify the appropriate dynamic user or role:

• Event owner: The user or role the container is assigned to when the playbook is run.
• Playbook run owner: The user who initiated the current run of this playbook.

Now datapath

Use the Now datapath in Condition or Filter blocks to compare against a time measure associated with the current time, for example, the current month or year. When configuring your block, select the now parameter, then select the associated datapath you want to use: datetime, date, year, month, day of month, day of week, or time. When the playbook is run, if the current date is May 15, you can use day of month to evaluate whether an artifact was resolved after the 15th of any month or use datetime to evaluate whether an event occurred before or after the playbook initiated its run.

Create a custom datapath

If the datapath you need isn't available, create a custom datapath. This can happen when you run actions with dynamic results. When you add a custom datapath, it is available only for the block you add it to.

To create a custom datapath, follow these steps:

1. Hover over a datapath field title and select +.
2. Enter the datapath name.
3. Select either Key or List from the drop-down menu. Use Key to use one value, and use List to use a list of values. Using List adds a .* value to the datapath and it appears as <list_name [] > with datapaths nested below it in the datapath picker.
4. To add more values to your List, select the + icon under the top value of the list.
5. Select Save.

Example: Add a custom datapath to a playbook block

If you run a run query action on the Splunk app in , the action result output includes a dynamic list of fields that are defined as part of the query that was run. These fields don't appear in the datapath picker, but you can add them by creating a custom datapath. In this example, if the name of the action result output wasn't available, you can create the custom datapath action_result.data.*.hostname. Custom datapaths appear only in the block where they are added.

To create this example custom datapath in an action block, follow these steps:

1. Add an action block to your playbook by dragging the half-circle icon attached to any existing block in the editor. Select an Action block from the menu that appears.
2. In the block configuration, select the By Action tab, then search for and select the run query action associated with the Splunk app.
3. In the Configure tab, enter the Search Processing Language (SPL) search host="web_application" to run a run query action on the Splunk app within .
4. Select the block you want to add the custom datapath to and select the datapath run_query_1. After you make the selection, you see that the hostname isn't available, even though it was visible when running your query in Splunk.
5. Add the custom datapath hostname under data [].
6. Hover over the data field title and select +.
7. Enter the datapath name hostname as a Key.
8. Select Save. The custom datapath appears in the list under data [] as hostname.

Datapaths and the Playbook API

For information on APIs involved with datapaths, see Understanding datapaths in the Python Playbook API Reference for manual.

Datapaths for looped playbook blocks

Datapaths for looped playbook blocks are slightly different from standard datapaths. For details, see Loops in the datapath picker in the Repeat playbook blocks with looping article.

Specify data through the format method

In addition to using the datapath picker, you can specify your parameters by using the format method in action, prompt, and format blocks. To use the format method, follow these steps:

1. In the configuration panel, select the format button () instead of the datapath button ().
2. Specify the datapaths, but format them in a template.

For details, see Customize the format of your playbook content.