JQ can be used with both regular Input and Output Attributes as well as with Published Attributes, but it functions in different ways for each. This section explains the differences. We first start by describing how it is used with regular Input Attributes and Output Attributes for context and then describe how it works with Published Attributes.

JQ with Input Attributes

Regular Input Attributes in a workflow can define a JQ filter that gets applied to the incoming payload. If specified, the JQ filter acts as a selector and possibly a transformer as well. As the selector, it identifies the key in the payload that contains the value that should be used for the Input Attribute or, it can possibly choose the appropriate key from one of several, depending on the keys that exist in the payload. Once the key is determined, it can also apply transformations to the value of the key that was selected.

The JQ filter is optional and applies only to that specific Input Attribute in the given workflow.

JQ with Output Attributes

Regular Output Attributes can also use JQ to transform values. Since in this case there is no incoming payload, there is no need for it to operate as a selector. It can be used, for example, to apply a floor or ceiling function to the value that was computed. As with regular Input Attributes, the JQ filter applies only to the specific attribute in the given workflow.

JQ with Published Attributes

Even within Published Attributes, JQ is handled differently when new values initially come into the system vs when new Published Attribute values are created within the system via Output Attributes.

JQ for Incoming Values

When a Published Attribute is defined, a JQ filter may be specified as part of the definition by selecting the 'Parse incoming values with JQ?' option. When selected, an additional input is displayed where you can enter the JQ formula. (You may need to scroll down to see it.)

This JQ filter will be applied to all new values that come into the system to be published, regardless of how they are received. The filter will be applied and the resulting value will be published as the new value rather than the actual value that was received. Note that the filter will specifically not be applied to values that are computed as Output Attributes in a workflow. See the section below for details.

Because new values can be received in a variety of different ways as described in Publishing New Values, the filter cannot and must not function as a selector in the same way it can for regular Input Attributes that are used when calling the /evaluations API. Instead, the system will look for exactly the name that is configured for the Published Attribute and will select that key only. Once that key is found, the JQ filter will be applied to the value that is associated with that key. This means that the JQ filter must be limited to only functionality that will transform the value, not select it - e.g., by identifying one or more elements from a list, applying a ceiling or floor function, etc.

Because the JQ filter will only transform functionality, this allows us to apply the filter regardless of how it was received into the system. For example, if the value is received via the /published-attributes API (and we strongly encourage you to publish new values in this way), there is no payload to parse to look for the Published Attribute name, so the filter must not include functionality to try to select the key.

JQ for Published Attributes as Output Attributes

When Published Attributes are used in a workflow as Output Attributes, a JQ filter can also be applied to the generated values, but in this case, the JQ filter is defined at part of the Output Attribute, just as is done for regular Output Attributes. A different JQ filter is defined for each Output Attribute, if desired, and is applied before the new value is published in the system.