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 user keys.
- Create global keys.
- Work with nesting levels in keys.
- Filter for the presence of a string in a key.
Viewing Keys, Disabling/Enabling Keys, and Creating User 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, action, or external action, select the Output Keys tab. Here, you can:
- View the keys that the component generates. Where applicable, the component generates separate sets of output keys for the success (✔) and failure (x) ports of a component. Run a Workspace actions that reference workspaces configured with FME Server Automations writers also generate output keys for each writer feature type. For more information, see Routing Data from Workspaces.
- Disable or enable keys. By default, all applicable keys are enabled in the outgoing message as it passes downstream.
- Create user keys with a user-defined name, and prefixed with the user. tag. You can assign the value of a user key from an existing key, or a constant.
The primary benefit of disabling keys or creating user 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 user 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 user 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.
You can create global keys in the following ways:
- On the Automations toolbar, click the Global Keys Editor button.
- Dynamically, when specifying a parameter value in a workflow. From an applicable parameter drop-down list, select Add to Global Keys.
In the Global Keys Editor, click + to start a new Global Key, enter a name (global.<your_name>), specify a Value, and click OK.
Working with Nesting Levels in Keys
When an automation encounters messages with keys that contain multiple levels of nesting, the automation parses the 0th, 1st, 2nd, and 3rd innermost levels of a key to resolve, or create, output keys.
For example, consider a message key {route.apple} assigned value apple. The following message has zero nested key levels:
{
"{route.apple}"
}
This message resolves to the value apple as an output key.
The following message contains 0-4 nested key levels:
{
"{route.{route.{route.{route.{route.apple}}}}}"
}
This message resolves to the value route.apple as an output key because the outermost, or 4th, nested level is unresolved.
Filtering on an Output Key
You can use the Filter Messages action to test for the presence of a string in an output key, and route messages in your workflow accordingly. For example, if the email.subject key from an Email - SMTP trigger contains a specific string, you might choose to route the message differently from other emails that do not contain that string.