Replacement Syntax Help

General

For variable replacement Velocity is used. See the User Guide and Reference for more information.

Using a ! after the $ prevents the variable from being printed if it's empty. You can enclose your variables in curly brackets, e.g. $!{issue.description}, to make sure Velocity knows where they should end.

Not all of these variables are available everywhere. But if a variable makes sense in a context it is most likely available.

Issue related variables for replacement

ObjectUsageExplanation
$issue$issue.summary or $issue.getSummary()
$!issue.getDescription()
$!issue.getReporterUser().getDisplayName()
$!issue.getFixVersions().iterator().next()
The current issue.
$fieldHelper$!fieldHelper.getValueAsString("components")
$!fieldHelper.getValueAsString("customfield_10200")
$!fieldHelper.getValueAsString("My custom field")
$!fieldHelper.getValueAsString($issue, "My custom field")
Gets the field value and converts it to string.
$!fieldHelper.getValue("description")
$!fieldHelper.getValue($issue, "reporter").getDisplayName()
Gets the field value without converting the value to a string. For fields that save their value as string (e.g. summary and description), this is the same as the above $!fieldHelper.getValueAsString("...").
$!fieldHelper.getAsString($anything)Converts the value to a string. If the value is a collection, the elements are separeted with a comma.
$!fieldHelper.getAsListOfString($anything)Converts the value to a list of strings. If the value is not some sort of collection, the list will only contain one string.
$!fieldHelper.getWikiMarkupValue("description")
$!fieldHelper.getWikiMarkupValue($issue, "description")
Gets the field value and converts it to Confluence storage format. Use this for fields that contain wiki markup like description or environment. Requires Confluence 5.5 or later.
$!fieldHelper.convertWikiMarkup($!fieldHelper.getValue("description"))This is the same as $!fieldHelper.getWikiMarkupValue("description"), just in an extra step. Requires Confluence 5.5 or later.
$!fieldHelper.getColumnViewValue("reporter")
$!fieldHelper.getColumnViewValue($issue, "reporter")
Gets the fields text value as it would appear in the issue list view.
$!fieldHelper.getColumnViewHtml("reporter")
$!fieldHelper.getColumnViewHtml($issue, "reporter")
Gets the field HTML as it would appear in the issue list view. Make sure that the field actually produces HTML that Confluence accepts.
$!fieldHelper.getViewValue("reporter")
$!fieldHelper.getViewValue($issue, "reporter")
Gets the fields text value as it would appear in the issue view. Try to use $!fieldHelper.getColumnViewValue first and only use this if that one does not work in your case.
$!fieldHelper.getViewHtml("reporter")
$!fieldHelper.getViewHtml($issue, "reporter")
Gets the field HTML as it would appear in the issue view. Make sure that the field actually produces HTML that Confluence accepts. Try to use $!fieldHelper.getColumnViewHtml first and only use this if that one does not work in your case.
$!fieldHelper.getDateOnlyAsString($issue.created)Converts the given date into Jira's date format.
$!fieldHelper.getDateTimeAsString($!fieldHelper.getValue("customfield_10500"))Converts the given date into Jira's date/time format.
$!fieldHelper.getDateWithFormat($issue.created, "yyyy-MM-dd HH:mm")Converts the given date into the given date/time format.
$!fieldHelper.getNumberWithFormat($!fieldHelper.getValue("My number field"), "#,${double_hash}0.00 €;-#,${double_hash}0.00 €")
$!fieldHelper.getNumberWithFormat($!fieldHelper.getValue("My number field"), "#,${double_hash}0.00 €;-#,${double_hash}0.00 €", ",", ".")
Converts the given number with the given format. Optionally a decimal separator and grouping separator can be specified. Since ## marks a comment in velocity use ${double_hash} instead.
$!fieldHelper.getFormattedDuration($!fieldHelper.getValue("timeSpent"))Formats the given duration (a Long) into a human readable form (e.g. 1 hour, 20 minutes).
$!fieldHelper.getShortFormattedDuration($!fieldHelper.getValue("timeSpent"))Formats the given duration (a Long) into a short human readable form (e.g. 1h 20m).
$!fieldHelper.doNotEscape($!fieldHelper.getValue("description"))Prevents XML escaping. Use this if your field contains e.g. a HTML table.
$!fieldHelper.replace($!fieldHelper.getValueAsString("labels"), ".", "-")
$!fieldHelper.replace($!fieldHelper.getValueAsString("labels"), ".", "-", "&", "+")
Replaces all occurrences of one string with another. The first parameter is the text the replacement should happen on. The second parameter is the search string and the third parameter is the replacement string. The search and replacement strings can be repeated multiple times (the fourth parameter would be the second search string and so on).
$issueHelper
$issueHelper.getCurrentIssue()This is the same as $issue.
$issueHelper.getMainIssue()This can be used inside the body part of a multi issue template to get the main issue.
$issueHelper.getAdditionalIssues()The list of additional issues.
$issueHelper.getAdditionalIssuesCounter()The number for the current additional issue, starting at 1. This is only available in the body part of a multi issue template.
$!issueHelper.getIssue("TEST-123")Gets an issue by its key or ID.
$!issueHelper.getIssues("TEST-123, OTHER-456")Gets multiple issues by their key or ID.
$!issueHelper.findIssue("key = TEST-123")Finds the first issue matching the JQL. If your JQL contains double quotes, use single quotes for the entire JQL string.
$!issueHelper.findIssues("project = TEST")Finds all issues matching the JQL. If your JQL contains double quotes, use single quotes for the entire JQL string.
$issueHelper.getLinkedIssues($issue)
$issueHelper.getLinkedIssues($issue, "Relates")
Gets all issues that are linked to the given issue. Optionally they can be limited to a link type.
$issueHelper.getInwardLinkedIssues($issue, "Blocks")Gets all issues where the given issue has an inward link of the given type towards them. For the link type 'Blocks' this means the given issue 'is blocked by' the returned issues.
$issueHelper.getOutwardLinkedIssues($issue, "Blocks")Gets all issues where the given issue has an outward link of the given type towards them. For the link type 'Blocks' this means the given issue 'blocks' the returned issues.
$!issueHelper.getPageIdFromFirstConfluenceLink($issue)Gets the page ID from the first Confluence link on the given issue or -1 if none can be found.
$!issueHelper.getPageIdFromConfluenceLink($myConfluenceLink)Gets the page ID from the given Confluence link.
$issueHelper.getConfluenceLinks($issue)Returns a list of all Confluence links from the given issue. These should be ordered primarily by their global ID and secondly by their ID.
$issueHelper.getRemoteJiraLinks($issue)Returns a list of all remote Jira links (to Jira issues on a different server) from the given issue.
$issueHelper.getWebLinks($issue)Returns a list of all web links from the given issue. This includes links to Confluence pages created by the Issue Publisher when the connection to Confluence is not made via an application link.
$!issueHelper.getCurrentUser()
$!issueHelper.getCurrentUser().getDisplayName()
$!issueHelper.getCurrentUser().getName()
The current user who triggered this operation. This might be empty if the current user is anonymous.
$!issueHelper.getExecutingUser()The user who is executing the operation. If not configured otherwise, this will be the same as $!issueHelper.getCurrentUser().
$!issueHelper.getCurrentComment()In the Publish Issue post function this will contain the comment text the user has entered. If no comment was entered this will be empty.
$issueHelper.getComments()
$issueHelper.getComments($issue)
Returns a list containing all comments for the current (or the given) issue, including the ones the current user can't view. In the post function this list might contain the current comment depending on where the post function was added. As an example on how to handle this list see the "Default Single Issue Template with Comments".
$issueHelper.getCommentsForUser()
$issueHelper.getCommentsForUser($issue)
Like the above function this returns a list of comments, but in this case only the ones the current user can view.
$issueHelper.getWorklogs($issue)Returns a list containing all work logs for the given issue.
$issueHelper.getIssuePropertiesKeys($issue) Returns a list containing the keys of all properties for the given issue.
$issueHelper.getIssueProperty($issue, "my.property") Returns the property for the given issue and property key. Use $responseHelper to parse the returned JSON string.
$issueHelper.getIssueProperties($issue) Returns all property keys and corresponding values for the given issue in a map. Use $responseHelper to parse the values.
$issueHelper.getCommentPropertiesKeys($comment) Returns a list containing the keys of all properties for the given comment.
$issueHelper.getCommentProperty($comment, "my.property") Returns the property for the given comment and property key. Use $responseHelper to parse the returned JSON string.
$issueHelper.getCommentProperties($comment) Returns all property keys and corresponding values for the given comment in a map. Use $responseHelper to parse the values.
$issueHelper.getPrintableIssueView($issue)Returns the printable issue view in HTML format.

Project related variables for replacement

ObjectUsageExplanation
$project$project.getKey()
$!project.getProjectLead()
$!project.getEmail()
The current project.
$projectHelper
$projectHelper.getProject("TEST")Gets a project by its key or ID.
$projectHelper.getProjects("TEST, OTHER")Gets multiple projects by their key or ID.
$projectHelper.getUsersInRole($project, "Developers")
$projectHelper.getUsersInRole("TEST", "Administrators")
Gets all users that currently have the role in the given project.
$projectHelper.getProjectPropertiesKeys($project) Returns a list containing the keys of all properties for the given project.
$projectHelper.getProjectProperty($project, "my.property") Returns the property for the given project and property key. Use $responseHelper to parse the returned JSON string.
$projectHelper.getProjectProperties($project) Returns all property keys and corresponding values for the given project in a map. Use $responseHelper to parse the values.
$!projectHelper.getMetadata("some_metadata_key")
$!projectHelper.getMetadata($project, "some_metadata_key")
Gets the value for the given project metadata key.
$profieldsHelper
(only available if Projectrak (formerly Profields) is installed)
$!profieldsHelper.getValueAsString("My project field")
$!profieldsHelper.getValueAsString("12")
$!profieldsHelper.getValueAsString($project, "My project field")
Gets the value of a project field and converts it to string. You can use the fields name or ID.
$!profieldsHelper.getValue("My project field")
$!profieldsHelper.getValue($project, "My project field")
Gets the value of a project field without converting the value to a string.
$!profieldsHelper.findProject('lead = "admin" ORDER BY name ASC')Finds the first project matching the PQL. If your PQL contains double quotes, use single quotes for the entire PQL string.
$!profieldsHelper.findProjects('lead = "admin" ORDER BY name ASC')Finds all projects matching the PQL.

User related variables for replacement

ObjectUsageExplanation
$currentUser$!currentUser.getDisplayName()
$!currentUser.getName()
The current user who triggered this operation. This might be empty if the current user is anonymous.
$executingUser$!executingUser.getDisplayName()
$!executingUser.getName()
The user who is executing the operation. If not configured otherwise, this will be the same as $currentUser.
$userHelper
$!userHelper.getCurrentUser()The same as $currentUser.
$!userHelper.getExecutingUser()The same as $executingUser.
$!userHelper.getUserByName("admin")Gets a user by its user name (the login name).
$userHelper.getUsersByName($userNames)Returns a list of users for the given collection of user names (login names).
$!userHelper.getUserByKey("JIRAUSER10000")Gets a user by its user key.
$userHelper.getUsersByKey($userKeys)Returns a list of users for the given collection of user keys.
$userHelper.getDisplayNames($users)Returns a list of display names for the given collection of users.
$userHelper.getDisplayNamesAsString($!fieldHelper.getValue("My multi user picker field"))Returns a String containing the comma separated display names for the given collection of users.
$userHelper.getUsersInGroup("jira-users")
$userHelper.getUsersInGroup($someGroup)
Gets all users that are in the given group.
$userHelper.getGroup("jira-users")Gets a group by its name.

Confluence related variables for replacement

ObjectUsageExplanation
$macroHelper
$macroHelper.newId()Creates a new unique macro ID.
$macroHelper.getJiraServerName()The server name this Jira has in the target Confluence. This can be used for the server parameter in the standard Jira macro. Requires Issue Publisher Macros 5.5.3.0 or later.
$macroHelper.getJiraServerId()The server ID this Jira has in the target Confluence. This can be used for the serverId parameter in the standard Jira macro. Requires Issue Publisher Macros 5.5.3.0 or later.
$macroHelper.getFieldValueMacroBody("", "My customfield")
$macroHelper.getFieldValueMacroBody($issue.key, "My customfield")
$macroHelper.getFieldValueMacroBody($issue.key, "description", "wiki-markup")
$macroHelper.getFieldValueMacroBody($issue, "created", "date-format", "yyyy-MM-dd HH:mm")
Adds a Jira Field Value macro to the page. If the first parameter, the issue, its key or ID, is empty during page creation it will be replaced with the main issue's key. The optional third and fourth parameter are the format and format-string parameters for the Jira Field Value macro. Requires Issue Publisher Macros 5.5.3.0 or later.
$macroHelper.getJiraMacroBodyForIssue($issue.key)
$macroHelper.getJiraMacroBodyForIssue($issue)
Adds the standard Jira macro showing a single issue to the page. Requires Issue Publisher Macros 5.5.3.0 or later.
$macroHelper.getJiraMacroBodyForJql('text ~ "test"')
$macroHelper.getJiraMacroBodyForJql("project = TEST", "key,summary,status", "30")
Adds the standard Jira macro showing all issues matching the JQL to the page. Optionally the shown columns and the maximum number of shown issues can be defined. If your JQL contains double quotes, use single quotes for the entire JQL string. Requires Issue Publisher Macros 5.5.3.0 or later.
$macroHelper.getJiraMacroBodyForJqlCount("project = TEST")Adds the standard Jira macro showing the number of issues matching the JQL to the page. If your JQL contains double quotes, use single quotes for the entire JQL string. Requires Issue Publisher Macros 5.5.3.0 or later.
$macroHelper.getUserProfileMacroBody($!fieldHelper.getValue("reporter"))
$macroHelper.getUserProfileMacroBody("admin")
Adds the standard User Profile macro for the given user or user name. If Confluence does not know the user, the display name of the passed user or the passed user name is returned.
$confluenceHelper
$confluenceHelper.getUserKey("admin")
$confluenceHelper.getUserKey($!fieldHelper.getValue("reporter"))
Gets the Confluence user key for the given user or user name. This can be used to fill the corresponding parameter of a user mentioning or user profile macro. But make sure that Confluence knows the user, since Confluence wont accept a user profile macro without a user key.
$confluenceHelper.getPage("12345")
$confluenceHelper.getPage("12345").getTitle()
Gets a Confluence page by its ID. You can access the ID, title, body and labels of the page. If you want to get multiple values from the page you should save it with #set($myPage = $confluenceHelper.getPage("12345")) and then access them with e.g. $myPage.title or $myPage.getTitle(). To prevent escaping of the body use $myPage.unescapedBody or $myPage.getUnescapedBody().
$confluenceHelper.getPageFromUrl("http://confluence.example.com/display/TEST/Test+Page")
$confluenceHelper.getPageFromUrl("http://confluence.example.com/display/TEST/Test+Page").getId()
Gets a Confluence page by its URL. The URL has to match the current Confluence server.
$confluenceHelper.findPage("SpaceKey", "A Page Title")
$confluenceHelper.findPage("SpaceKey", "A Page Title").getId()
Finds a Confluence page by its space key and page title. You can access the ID, title, body and labels of the page.
$confluenceHelper.findPages("SpaceKey", "")
$confluenceHelper.findPages("", "A Page Title")
Finds Confluence pages by their space key or page title. You can even leave both parameters empty. The result is limited to 25 pages.

$!confluenceHelper.generateUniqueSpaceKey($issue.summary)
$!confluenceHelper.generateUniqueSpaceKey($issue.summary, 25, 45)

Generates a unique Confluence space key from the given string, e.g. "Test Space" becomes "TESTSPACE". The optional second and third parameter are the maximal length of the space key and the maximal number of tries a number is appended. The default for these values are 30 and 50.
$currentPage$currentPage.title
$currentPage.body
$currentPage.labels
The title, body and labels of the current page. When updating a page this will contain the current page contents. When creating a new page this will contain the contents of the parent page.
$templatePage$templatePage.title
$templatePage.body
$templatePage.labels
The title, body and labels of the referenced template page. This is only available when using a Confluence page as template.

Mail related variables for replacement

ObjectUsageExplanation
$recipient
$recipient.getEmail()The recipient's email address.
$!recipient.getDisplayName()The recipient's display name if available.
$!recipient.getName()The recipient's name (login name) if available.
$recipientCollector$recipientCollector.add("mail@company.com")
$recipientCollector.add("mail@company.com, mail2@company.com")
$recipientCollector.add($fieldHelper.getValueAsString("My custom field with emails"))
$recipientCollector.add($currentUser)
$recipientCollector.add($fieldHelper.getValue("reporter"))
$recipientCollector.add($fieldHelper.getValue("My user picker custom field"))
$recipientCollector.add($fieldHelper.getValue("My group picker custom field"))
$recipientCollector.add($userHelper.getUserByName("admin"))
$recipientCollector.add($userHelper.getUsersInGroup("jira-users"))
$recipientCollector.add($userHelper.getGroup("jira-users"))
$recipientCollector.add($projectHelper.getUsersInRole($project, "Developers"))
Add email addresses and users as recipients. Only available in the recipients field of the send mail action.

Response related variables for replacement

ObjectUsageExplanation
$response$response.getStatusCode()
$response.getContent()
$response.getHeaders()
The last response. Only available after a web request action.
$responseHelper
$responseHelper.getJsonElement("${dollar}.homepage.id")
$responseHelper.getJsonElement($response, ".homepage.id")
Gets a single element from a JSON response (or any other JSON string) using JsonPath. Use ${dollar} as $ or leave it at the beginning, as it will be added automatically.
$responseHelper.getJsonElements(".._links.webui")
$responseHelper.getJsonElements($response, ".._links.webui")
Gets multiple elements from a JSON response (or any other JSON string) using JsonPath.
$responseHelper.getJsonAsMap($response) Parses the JSON response (or any other JSON string) into a Map. Use this when the JSON start with a '{'.
$responseHelper.getJsonAsList($response) Parses the JSON response (or any other JSON string) into a List. Use this when the JSON start with a '['.

Other variables for replacement

ObjectUsageExplanation
$valueCollector
(only available in the template of the Set field value action)
$valueCollector.add($fieldHelper.getValue("reporter"))Adds a single value to the value collector.
$valueCollector.addAll($fieldHelper.getValue("My multi user picker field"))Adds multiple values to the value collector.
$valueCollector.remove($fieldHelper.getValue("reporter"))Removes a single value from the value collector. Useful if you added some values to the value collector before and now want to remove one of those values.
$valueCollector.removeAll($fieldHelper.getValue("My multi user picker field"))Removes multiple values from the value collector. Useful if you added some values to the value collector before and now want to remove some of those values.
$valueCollector.retainAll($fieldHelper.getValue("My multi user picker field"))Retains/keeps only the given values in the value collector. Useful if you added some values to the value collector before and now only want to keep the intersection of values.
$valueCollector.clear()Removes all values from the value collector.
$collectionHelper



$collectionHelper.first($collection)Gets the first element from a collection.
$collectionHelper.last($collection)Gets the last element from a collection.
$collectionHelper.reverse($collection)Returns a list with all elements from the given collection reversed. The passed collection itself is not changed. If null or an empty collection is given an empty list is returned.
$collectionHelper.isEmpty($collection)Returns true if the given collection is empty or null.
$collectionHelper.isNotEmpty($collection)Returns true if the given collection is not null and not empty.
$insightHelper
(only available if Insight is installed)
$!insightHelper.getObjectFromField($issue, "My Insight field")Gets the first object from an Insight field.
$!insightHelper.getObjectsFromField($issue, "My Insight field")Gets all objects from an Insight field. This is the same as $!fieldHelper.getValue("My Insight field")
$!insightHelper.getAttributeValueFromField($issue, "My Insight field", "Name")Gets the first attribute value of the first object from an Insight field. If the attribute value is no string, you can convert it with $!fieldHelper.getAsString($anything)
$!insightHelper.getAttributeValuesFromField($issue, "My Insight field", "Name")Gets all attribute values of all objects from an Insight field. If the attribute values are no strings, you can convert them with $!fieldHelper.getAsListOfString($anything) or $!fieldHelper.getAsString($anything)
$!insightHelper.getAttributeValue($singleInsightObject, "Name")Gets the first attribute value of a single Insight object.
$!insightHelper.getAttributeValues($singleInsightObject, "Name")
$!insightHelper.getAttributeValues($multipleInsightObjects, "Name")
Gets all attribute values of a single Insight object or a collection of objects (e.g. the result of $!insightHelper.getObjectsFromField($issue, "My Insight field")).
$!insightHelper.getObjectType($myInsightObject.getObjectTypeId()).getName()Gets an Insight object type by its ID. You can use this to get the object type name for an Insight object.
$!insightHelper.getObject("TEST-123")Gets an Insight object by its key or ID.
$!insightHelper.findObject(1, 'objectType = User AND Name = "Test User"')Finds the first object matching the IQL and object schema ID. If your IQL contains double quotes, use single quotes for the entire IQL string.
$!insightHelper.findObjects(1, "objectType = User")Finds all objects matching the IQL and object schema ID.
$!insightHelper.getObjectSchemaIdByName("My Scheme")Gets the ID of an object schema by its name.
$!insightHelper.getObjectSchemaId($singleInsightObject)
$!insightHelper.getObjectSchemaId($multipleInsightObjects)
Gets the ID of an object schema for a single Insight object or the first object of a collection.
$insightHelper.getComments($myInsightObject)Returns a list with all comments for the given Insight object. See How to publish an Insight object including its comments and history for an example on how to handle this list.
$insightHelper.getObjectHistory($myInsightObject)Returns a list with all history items for the given Insight object. See How to publish an Insight object including its comments and history for an example on how to handle this list.
$!insightHelper.getStatusCategoryColour($myStatusAttributeValue)Gets the colour ('Green', 'Yellow' or 'Red') for the value of a status attribute.
$!insightHelper.getHistoryTypeName($objectHistoryItem)Gets the type name (e.g. 'Created', 'Added Value' or 'Changed Value') for an Insight object history item.
$baseUrl
The base URL for this Jira.
$remoteServer$remoteServer.getDisplayUrl()
$remoteServer.getUrl()
$remoteServer.getName()
The current or the last target server.
$now

$fieldHelper.getDateTimeAsString($now)
$fieldHelper.getDateWithFormat($now, "yyyy-MM-dd HH:mm")

The current date/time.
$double_hash
Two hash characters.
$dollar
The dollar character.
$double_quote$issueHelper.findIssues("reporter = ${double_quote}${currentUser.displayName}${double_quote}")The double quote character.
$stringUtils
See StringUtils.
$textUtils


Deprecated objects:

Object
$comment
$mainIssue
$additionalIssues
$additionalIssuesCounter

Use the corresponding $issueHelper functions instead.


How to get the values of standard fields:

FieldUsage
affectedVersions$!fieldHelper.getValueAsString("affectedVersions")
assignee$!fieldHelper.getValueAsString("assignee")
components$!fieldHelper.getValueAsString("components")
created$!fieldHelper.getValueAsString("created")
creator$!fieldHelper.getValueAsString("creator")
description$!fieldHelper.getWikiMarkupValue("description")
dueDate$!fieldHelper.getValueAsString("dueDate")
environment$!fieldHelper.getWikiMarkupValue("environment")
estimate$!fieldHelper.getValueAsString("estimate")
fixVersions$!fieldHelper.getValueAsString("fixVersions")
id$!fieldHelper.getValueAsString("id")
issueType$!fieldHelper.getValueAsString("issueType")
key$!fieldHelper.getValueAsString("key")
labels$!fieldHelper.getValueAsString("labels")
originalEstimate$!fieldHelper.getValueAsString("originalEstimate")
priority$!fieldHelper.getValueAsString("priority")
project$!fieldHelper.getValueAsString("project")
reporter$!fieldHelper.getValueAsString("reporter")
resolution$!fieldHelper.getValueAsString("resolution")
resolutionDate$!fieldHelper.getValueAsString("resolutionDate")
securityLevel$!fieldHelper.getValueAsString("securityLevel")
status$!fieldHelper.getValueAsString("status")
summary$!fieldHelper.getValueAsString("summary")
timeSpent$!fieldHelper.getValueAsString("timeSpent")
updated$!fieldHelper.getValueAsString("updated")
votes$!fieldHelper.getValueAsString("votes")
watches$!fieldHelper.getValueAsString("watches")

You can also show the template help page with the tables above in your local Jira. Links to this page are shown in the description of every field where variables will be replaced.

This help page additionally has a table to get the values of all your custom fields at the end!