Use data paths to present data to the Splunk Phantom web interface

Data paths are a way for each command to pass down information about the data that needs to be presented to the UI layer. Data paths have the following supported starting locations:

Location	Description
action_result.data	Used to access the data added to a CommandResult.
action_result.message	Used to access the message added to a CommandResult.
action_result.parameter	Used to access the parameters passed to a command.
action_result.status	Used to access the status from a CommandResult.
action_result.summary	Used to access the summary information added to the CommandResult.
artifact	Used to access artifacts in a container when authoring playbooks.
summary	Used to access the summary of the entire connector operation.

Each starting point is a collection. The action_result.data collection is always an array. Each element of this array is an object of arbitrary complexity added by the connector. Whoever creates the data path must understand the data structure used by the connector. Both the action_result.summary and action_result.summary starting points reference a dictionary. While a connector writer can potentially add complex data structures to the summary, the intended purpose of these areas are for simple summary data and the view writer will typically not have to go more than one level into the summary areas.

The path separator is the . character. The path may be constructed out of the following data types:

Data type	Description
Non-numeric text characters	If the path segment is a non-numeric value, then the container must be a dictionary and the path segment is assumed to be a key in the dictionary.
Numeric characters	If the path is strictly numeric, then the container is expected to be an array and the path segment accesses the 0-based index into the array. While it is possible that a dictionary with a numeric key can work, it is discouraged and is not guaranteed.
An empty string	An empty path segment accesses all items in the container. Either all elements in the array or all values in a dictionary. Typically this is used to construct a view over multiple entries in the action_result.data. Since the action_result.data is an array and widgets expect to show multiple results, this allows the widget to access all the individual results.

Consider the data path action_result.data.*.information.0.leaf. The following data structure is added to each CommandResult:

{
  "information": [
    {
      "leaf": "important information is here!",
      "other_data": ...
    },
    {
       "other data": ...
    }
  ]
  "other data": ...
}

This path is accessing the action_result.data. For every command result it is accessing the information key. The information key is an array and the path is explicitly only accessing the 0th element of the array. Inside the array are dictionaries in which you find a key called leaf which contains the data the widget renders.

Specifying an invalid path attempting to index into an array will cause an exception and the widget will not render.

Only data for fully matching paths will be returned. Since a connector may not guarantee that data is always there, this will not generate an error. For example if the path asks for A.B.C but only some instances of A contain B and only some instances of B contain C, the result skips the missing B and C entries.

In virtually all cases, widgets expect the data from a data path to result in strings or numbers. If your path does not evaluate to one of these types, the Splunk Phantom web interface will not show anything.

Do not use spaces in your key names.