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 events, and then, from the event fields, src_ip.
• 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.
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.

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.

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.

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.

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.