Advanced: Placeholders
Insight supports a wide range of different placeholders that allow you to dynamically replace a specified placeholder with anything from an Issue field value, Insight Object attribute value or other Insight related information depending on the context.
When to use placeholders?
Here are some use cases that will show you how placeholders work:
- Get an email when a license is about to expire, with the name and end date of that specific license.
- Set/update an object attribute with the value from an issue field when issue is transitioned to a specific status.
What these use cases have in common is that you know where to find the value, but not what the value will be at the time when you'll need it. Placeholders will find the right value.
Placeholder structure
The placeholders are structured like this:
${Name of placeholder}
or
${Name of placeholder${Number}}The following table describes how placeholders are used, with some examples:
| 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} | user@example.com,anotheruser@example.com | ||
| ${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}} | user@example.com,anotheruser@example.com | ||
| ${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}} | user@example.com | ||
| ${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}} | user@example.com | ||
| ${Email${4}} | <empty value> |
Placeholder context
Placeholders can replace different data for different contexts (custom fields, automation, post functions).
Automation rules
For more info on automation rules, see Automation rules.
| 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 / edit
When creating or editing objects with object reference attributes you can specify an IQL that is used to limit the selection of objects. The placeholders available are all the attributes available 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. |
Here's a video if you'd like to see how this can be done:
Post-functions
For more info on post-functions, see Post-functions.
The following post-functions support placeholders:
- Email user(s) based on attribute in a selected Insight Object
- Set the value of an object attribute with a predefined value
- Assign object/s based on an IQL query
Custom fields
For more info on custom fields, see Insight custom fields.
The standard Insight custom field "Insight Object/s" supports placeholders for any issue field data. This is configured in the "Issue Scope IQL" and can be constructed as the following example:
Organisation = ${customfield_12345.name} AND Location = ${Country} AND "Issue Type" like ${issuetype.name}The placeholders will be replaced with the identifiers for the specific underlying objects. Remember to use IN in the IQL if you have multiple values.
| Custom field key | Custom field name | ${placeholder.id} / ${placeholder.key} | |
|---|---|---|---|
| ${customfield_xxxxx} | <Custom Field Name> | The identifier | The label / name |
The table below shows the keys for issue placeholders to use for Jira fields. Make sure to use IN for multi values to not break the IQL:
| Issue key | Label / Description | Multiple | Type | ${key.id} | ${key.label} |
|---|---|---|---|---|---|
| key | The Issue Key | false | String | key | key |
| affectedVersions | Affected Versions | true | Version | Id | Name |
| assignee | Assignee | false | ApplicationUser | userKey | Display Name |
| description | Description | false | String | description | description |
| duedate | Due Date | false | Date | duedate | duedate |
| fixVersions | Fix Versions | true | Version | Id | Name |
| issuekey | Issuekey | false | String | key | key |
| environment | Environment | false | String | environment | environment |
| issuetype | Issue Type | false | IssueType | Id | Name |
| creator | Creator | false | ApplicationUser | userKey | Display Name |
| labels | Labels | true | String | labels | labels |
| components | Components | true | ProjectComponent | Id | Name |
| attachments | Attachments | true | Attachment | Id | filename |
| priority | Priority | false | Priority | Id | Name |
| pid | Project | false | Project | Id | Name |
| reporter | Reporter | false | ApplicationUser | userKey | Display Name |
| resolution | Resolution | false | Resolution | Id | Name |
| votes | Votes | true | Long | votes | votes |
| watchers | Watchers | true | Long | watchers | watchers |
| resolutiondate | Resolution Date | false | Date | resolutiondate | resolutiondate |
| created | Created | false | Date | created | created |
| updated | Updated | false | Date | updated | updated |
| status | Status | false | Status | Id | Name |
| summary | Summary | false | String | summary | summary |
The issuetype placeholder won't work for Jira Service Management requests. You must use a custom field instead:
"Related Jira Projects" = currentProject() AND "Related Jira Issue Types"."Name" in (${issuetype.label}) AND Status = "Active""Related Jira Projects" = currentProject() AND ("Related Jira Issue Types"."Name" in (${issuetype.label}) OR "Related Jira Issue Types"."Name" in (${customfield_10654})) AND Status = "Active"