This documentation is for Insight for Server/Data Center only.

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 and why would we want to use placeholders?

Some use cases to illustrate when placeholders would come to the rescue: 

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 moved to a specific status.

What these two use cases have in common is that we know "where to find the value" but not what the specific value will be at the time we are setting up our configuration. That's when / why we need to use placeholders to "find the desired value" when needed.  

The placeholder is something to use when configuring an actions and the value that we want to have is dependent on the context of the runtime. E.g. we do not know which object will be triggering the action and therefore we do not know the value. 

Placeholder structure

The placeholders are structured like this

Syntax
${Name of placeholder}
or
${Name of placeholder${Number}}


Why do we have these multiple structures that are hard to grasp? It is because it offers the most configuration possibilities. The following table describes how they are used with the example shown in the screenshot below.

Example object

PlaceholderWhat 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

The following section describes what data can be replaced in different contexts

Sometimes placeholder can supply multiple values. If that is the case the placeholder ${Name of placeholder${i}} can be used.
The most common configuration is ${Name of placeholder${0}} which renders a comma separated list of all values provided by the placeholder e.g.

Attribute IN ( ${Name of placeholder${0}} )

It is possible to use ${Name of placeholder${1}} to get hold of only the first value as well.


Import

Read more about the placeholder in the import documentation

Placeholder NameValue
Data locatorThe value that is found in the external data source from the data locator

The placeholders are used as part of the IQL 

Automation

Read more about the automation 

Placeholder NameValueDescription
Attribute NameThe attribute valueThe value of the attribute with the same name as the placeholder. This will render the attribute in the human readable form.
Attribute Name.idThe attribute value as storedThe 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.
labelThe label of the objectThe value is replaced by the configured label for the object.
objectTypeThe object type name of the objectThe value is replaced by the object type name.
objectTypeIdThe object type idThe value is replaced by the id of the object type of the current object.
objectIdThe objects id (not the key)The integer that identifies this object.
KeyThe key of the objectThe 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 NameValueDescription
Attribute NameThe attribute valueThe value of the attribute with the same name as the placeholder. This will render the attribute in the human readable form
Attribute Name.idThe attribute value as storedThe 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 used by the IQL are always the value to the right hand side of the configuration and the placeholders are replaced by values from the current object but the IQL is referencing attributes from the target object type. 

There is a video available demonstrating how this can be configured:



Post functions

Insight comes with a bunch of post functions. Some of them support placeholders to get issue data. The following ones support placeholders:


Custom Fields

The standard Insight custom field "Insight Object/s" supports placeholders where any issue field data can be applied. This is configured in the "Issue Scope IQL" and can be constructed as the following example:

Issue Scope IQL:

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 keyCustom field Name${placeholder.id} / ${placeholder.key}${placeholder.name} / ${placeholder.label}
${customfield_xxxxx}<Custom Field Name>The identifierThe label / name


This is the keys for the issue placeholders to use for JIRA fields. Make sure to use IN for multi values to not break the IQL

Issue keyLabel / DescriptionMultipleType${key.id}${key.label}
keyThe Issue KeyfalseStringkeykey
affectedVersionsAffected VersionstrueVersionIdName
assigneeAssigneefalseApplicationUseruserKeyDisplay Name
descriptionDescriptionfalseStringdescriptiondescription
duedateDue DatefalseDateduedateduedate
fixVersionsFix VersionstrueVersionIdName
issuekeyIssuekeyfalseStringkeykey
environmentEnvironmentfalseStringenvironmentenvironment
issuetypeIssue TypefalseIssueTypeIdName
creatorCreatorfalseApplicationUseruserKeyDisplay Name
labelsLabelstrueStringlabelslabels
componentsComponentstrueProjectComponentIdName
attachmentsAttachmentstrueAttachmentIdfilename
priorityPriorityfalsePriorityIdName
pidProjectfalseProjectIdName
reporterReporterfalseApplicationUseruserKeyDisplay Name
resolutionResolutionfalseResolutionIdName
votesVotestrueLongvotesvotes
watchersWatcherstrueLongwatcherswatchers
resolutiondateResolution DatefalseDateresolutiondateresolutiondate
createdCreatedfalseDatecreatedcreated
updatedUpdatedfalseDateupdatedupdated
statusStatusfalseStatusIdName
summarySummaryfalseStringsummarysummary

The "issuetype" placeholder does not work in Service Desk requests. You must use a custom field instead. For example, this query in JSD will not return any objects:

"Related JIRA Projects" = currentProject() AND "Related JIRA Issue Types"."Name" in (${issuetype.label}) AND Status = "Active"

Whereas this will:

"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"