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:
- 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
ifstatement in a utility block or as a container ID for an action block, shown in this image. The datapath picker appears.
- 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
events, and then, from the event fields,
- 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.
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.
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:
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
artifactdenotes 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
severityis 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
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
artifactdenotes 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.
cefkey denotes a CEF field.
- The second period ( . ) moves you down another layer into the data.
sourceHostNameis the key for the source's host name.
Datapaths in logic loops
For details on specifying datapaths in looped blocks, refer to Loops in the datapath picker in the Repeat actions with logic loops topic.
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
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.
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.
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:
- Hover over a datapath field title and select +.
- Enter the datapath name.
- 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.
- To add more values to your List, select the + icon under the top value of the list.
- 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:
- 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.
- In the block configuration, select the By Action tab, then search for and select the run query action associated with the Splunk app.
- 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 .
- 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.
- Add the custom datapath
- Hover over the data field title and select +.
- Enter the datapath name
hostnameas a Key.
- Select Save. The custom datapath appears in the list under
Datapaths and the Playbook API
For information on APIs involved with datapaths, see Understanding datapaths in the Python Playbook API Reference for manual.
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:
- In the configuration panel, select the format button () instead of the datapath button ().
- Specify the datapaths, but format them in a template.
For details, see Customize the format of your playbook content.
Repeat actions with logic loops
Save a playbook so can access it
This documentation applies to the following versions of Splunk® SOAR (Cloud): current