Use datapaths to present data to the web interface

Datapaths are a way for each command to pass down information about the data that needs to be presented to the UI layer. Datapaths 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.
custom_function_result	Used to access the action result list object.
legacy_custom_function_result	Used to access playbook-specific and custom functions from the classic playbook editor. The classic playbook editor will be deprecated soon, in 2024. For information on converting your playbooks, see Convert classic playbooks to modern playbooks.
playbook:launching_user	Used to access the user who launched the current playbook run.
summary	Used to access the summary of the entire connector operation.

Each starting location is a collection that leads to specific, filtered data. 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 datapath must understand the data structure used by the connector. Both the action_result.summary and action_result.summary starting locations 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 dot (.) character. The path might be constructed from 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. Avoid using a dictionary with a numeric key.
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 datapath 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 is returned. Since a connector might 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 datapath to result in strings or numbers. If your path does not evaluate to one of these types, the web interface will not show anything.

Do not use spaces in your key names.