Working with Output Keys in Automations Workflows
Messages pass along the components of Automations workflows, from triggers to actions to external actions, in the form of JSON-formatted key-value pairs. These key-value pairs represent various properties that are derived from the components of the workflow, and form the content of the message. Each key that is output by a component can be sent downstream to the next component, and ultimately output by the workflow to a receiving application.
You can work with the output keys of workflow messages in the following ways:
- View keys, disable and enable keys, and create custom keys.
- Create global keys.
Viewing, Disabling/Enabling, and Creating Custom Keys
As you build an Automations workflow, you can control the keys that are sent to downstream components in a workflow, and that are ultimately included in the final message output. In the Details pane of a trigger or action, select the Output Keys tab. Here, you can:
- View the keys that the component generates.
- Disable or enable keys. By default, all applicable keys are enabled in the outgoing message as it passes downstream.
- Create custom keys from an existing key, with a user-defined name, and prefixed with the user. tag.
The primary benefit of disabling keys or creating custom keys is to prevent them from being overwritten, where desired. The values of JSON objects with the same key strings are overwritten as they pass through a workflow. For example, consider a workflow that contains two Run Workspace actions in sequence. Both actions pass a job.timeStarted key, but the value that key produces in the first action is overwritten by the second action. If you want to preserve only the job.timeStarted value of the first workspace, you can disable the job.timeStarted key in the configuration of the second action, and preserve it in the first.
But what if you wanted to preserve both job.timeStarted values? In this case, you can create a custom key in both workspaces, give them each unique names, and base their values on job.timeStarted. Optionally, you can also disable job.timeStarted in both workspaces.
You can use custom keys anywhere in a workflow that allows you to specify a key for a parameter value.
Creating Global Keys
You can create your own key-value pairs, prefixed with the global. tag. Global keys allow you to reference a value in multiple components of a workflow without having to explicitly define it each time. You can use global keys anywhere in a workflow that allows you to specify an output key for a parameter value.
On the Automations toolbar, click the Global Keys Editor button. In the Global Keys Editor, click + to start a new Global Key, enter a name (global.<your_name>), specify a Value, and click OK.