Using placeholders in AQL to dynamically replace information
Assets supports a variety of placeholders that let you dynamically replace specified placeholders with values from Jira work item fields, Assets object attributes, or other related information, depending on the context.
Examples of when to use placeholders
Placeholders are useful when configuring actions where the value depends on the runtime context. For instance, we may not know which object will trigger the action, so we can't determine the value in advance.
Example 1: Receive an email when a license is about to expire, including the license name and end date.
Example 2: Set or update an object attribute with the value from an Jira work item field when the work moves to a specific status.
In both examples, we know where to find the value, but not the specific value at the time of configuration. This is why placeholders are essential—they help us "find the desired value" when needed.
Placeholder structure
Syntax
|
These multiple structures provide a range of configuration options. The following table explains how each structure is used.
Placeholder | What it does | Example placeholder | Replaced with value |
|---|---|---|---|
${Name of placeholder} | Replaces the content ${Name of placeholder} with the value matched by Name of placeholder. | ${Name} | One object |
${Email} | myemail@fakse.se,anotheremail@fakse.se | ||
${Name of placeholder${0}} | Replaces the content ${Name of placeholder${0}} with all values matched by Name of placeholder. This is used to match multiple values e.g. when populating an attribute with multiple cardinality and all values will be one instance of that attribute. When replaced as text this is similar to the above example but when replaced in a multi value context this notation will render multiple values but the above will render one value as a comma separated string. | ${Price${0}} | 12 |
${Email${0}} | myemail@fakse.se,anotheremail@fakse.se | ||
${Name of placeholder${1}} | Replaces the content ${Name of placeholder${1}} with the first value matched by Name of placeholder. This is used when only the first value is required. | ${Price${1}} | 12 |
${Email${1}} | myemail@fake.se | ||
${Name of placeholder${n}} | Replaces the content ${Name of placeholder${n}} with the n:th value matched by Name of placeholder. This is used when only the n:th value is required. | ${Price${2}} | <empty value> |
${Email${2}} | anotheremail@fakse.se | ||
${Email${4}} | <empty value> |
Context with placeholders
Sometimes, placeholders can return multiple values. In such cases, you can use the placeholder format ${Name of placeholder${i}}, where i represents the index number.
The most common configuration is ${Name of placeholder${0}}, which generates a comma-separated list of all values provided by the placeholder, for example:
|
You can also use ${Name of placeholder${1}} to retrieve only the first value from the list of values provided by the placeholder.
Placeholders when importing
Learn more about placeholders when importing into Assets
Placeholder name | Value |
|---|---|
Data locator | The value that is found in the external data source from the data locator. |
The placeholders are used as part of the Assets Query Language (AQL).
Automation
Learn more about automating Assets
Placeholder name | Value | Description |
|---|---|---|
Attribute Name | The attribute value | The value of the attribute with the same name as the placeholder. This will render the attribute in the human readable form. |
Attribute Name.id | The attribute value as stored | The value of the attribute with the same name as the placeholder. This will render the attribute in the form that is stored. e.g. if the attribute is an object reference this will render the referenced object id. This will only work on attributes that are stored with another value than presented. |
label | The label of the object | The value is replaced by the configured label for the object. |
objectType | The object type name of the object | The value is replaced by the object type name. |
objectTypeId | The object type id | The value is replaced by the id of the object type of the current object. |
objectId | The objects id (not the key) | The integer that identifies this object. |
Key | The key of the object | The key value of the current object. |
Object create or edit
When creating or editing objects with reference attributes, you can use AQL to limit the selection of objects. The available placeholders are all the attributes in the create/edit dialog.
Placeholder name | Value | Description |
|---|---|---|
Attribute Name | The attribute value | The value of the attribute with the same name as the placeholder. This will render the attribute in the human readable form. |
Attribute Name.id | The attribute value as stored | The value of the attribute with the same name as the placeholder. This will render the attribute in the form that is stored. e.g. if the attribute is an object reference this will be the id of the object that is referenced. |
The placeholders in the AQL are always the values on the right-hand side of the configuration. These placeholders are replaced by values from the current object, while the AQL references attributes from the target object type.
Placeholders cannot be used in the Filter scope (AQL) field in the Objects field configuration screen.
Was this helpful?