Use Replacement Syntax

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.

The $issue variable is based on the Issue object from Jira Server/Data Center. All other Jira objects e.g. users and projects are based on their JSON representation from the REST API.

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

Object	Usage	Explanation
`$issue`	`$issue.summary` or `${issue.summary}` or `$issue.getSummary()` `$!issue.getDescription()` `$!issue.getAssignee().getDisplayName()` `$!issue.getReporter().getDisplayName()` `$!issue.getFixVersions().iterator().next()` `$issue.getProject().getName()` `$!issue.getResolution().getName()`	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 separated 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 value of rich text fields as Confluence storage format. Use this in storage format templates for the description, environment and multi-line text custom fields.
	`$!fieldHelper.convertWikiMarkup($!fieldHelper.getValue("description"))`	This is the same as `$!fieldHelper.getWikiMarkupValue("description")`, just in an extra step.
	`$!fieldHelper.getViewHtml("description")` `$!fieldHelper.getViewHtml($issue, "description")`	Gets the value of rich text fields as HTML. Use this in PDF templates for the description, environment and multi-line text custom fields.
	`$!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.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.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 the first 100 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.getComments()` `$issueHelper.getComments($issue)`	Returns a list containing all comments for the current (or the given) issue. As an example on how to handle this list see the "Default Single Issue Template with Comments".
	`$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.
	`$issueHelper.getIssueProperties($issue)`	Returns all property keys and corresponding values for the given issue in a map.
	`$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.
	`$issueHelper.getCommentProperties($comment)`	Returns all property keys and corresponding values for the given comment in a map.
`$mainIssue`	`$mainIssue.summary`	This can be used inside a loop to get the main issue.

Project related variables for replacement

Object	Usage	Explanation
`$project`	`$project.getKey()` `$!project.getLead()` `$!project.getEmail()`	The current project.

User related variables for replacement

Object	Usage	Explanation
`$currentUser`	`$!currentUser.getDisplayName()` `$!currentUser.getAccountId()`	The current user who triggered this operation. This might be empty if the current user is anonymous.
`$executingUser`	`$!executingUser.getDisplayName()` `$!executingUser.getAccountId()`	The user who is executing the operation. If not configured otherwise, this will be the same as `$currentUser`.
`$userHelper`
	`$!userHelper.getUserByAccountId("5b10ac8d82e05b22cc7d4ef5")`	Gets a user by its account ID.
	`$!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")`	Gets all users that are in the given group.
	`$!userHelper.getGroup("jira-users")`	Gets a group by its name.

Confluence related variables for replacement

Object	Usage	Explanation
`$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 admin access to Confluence.
	`$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 admin access to Confluence.
	`$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. This only works if publishing on Confluence Server / Data Center.
	`$macroHelper.getJiraMacroBodyForIssue($issue.key)` `$macroHelper.getJiraMacroBodyForIssue($issue)`	Adds the standard Jira macro showing a single issue to the page. Requires admin access to Confluence.
	`$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 admin access to Confluence.
	`$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 admin access to Confluence.
	`$macroHelper.getUserProfileMacroBody($!fieldHelper.getValue("reporter"))`	Adds the standard User Profile macro for the given user or account ID. If Confluence does not know the user, the display name of the passed user or the passed user name is returned.
`$confluenceHelper`
	`$confluenceHelper.getPage("12345")` `$confluenceHelper.getPage("12345").getTitle() $confluenceHelper.getPage("12345").getSpace().getName()`	Gets a Confluence page by its ID. You can access the ID, title, body, labels and space 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, labels and space 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.getPageProperty($currentPage, "my.property")`	Returns the property for the given page and property key.
	`$confluenceHelper.getPageProperties($currentPage)`	Returns all property keys and corresponding values for the given page in a map.
	`$confluenceHelper.getSpace("SpaceKey")$confluenceHelper.getSpace("SpaceKey").getName()$confluenceHelper.getSpace("SpaceKey").getHomepage().getTitle()`	Gets a Confluence space by its key.
	`$!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} ${currentPage.space.name} ${currentPage.space.homepage.title}`	The title, body, labels and space 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, labels and space of the referenced template page. This is only available when using a Confluence page as template.

Response related variables for replacement

Object	Usage	Explanation
`$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.parseJson($response)`	Parses the JSON response (or any other JSON string) into a Java object. A JSON object (starting with a '{') will become a Java Map. A JSON list (starting with a '[') will become a Java List.

Other variables for replacement

Object	Usage	Explanation
`$item`		When iterating over items (other than issues), this will be the current item.
`$valueCollector` (only available when mentioned)	`$valueCollector.add($fieldHelper.getValue("reporter"))`	Adds a single value to the value collector.
	`$valueCollector.addAll($fieldHelper.getValue("My multi user picker field"))` `$valueCollector.addAll($issue.subtasks)`	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.
	`$collectionHelper.size($collection)`	Returns the number of elements in the given collection.
	`$collectionHelper.newTreeMap()`	Returns a new, empty TreeMap, using the natural ordering of its keys.
	`$collectionHelper.newLinkedHashMap()`	Returns a new, empty LinkedHashMap.
	`$collectionHelper.newTreeSet()`	Returns a new, empty TreeSet, sorted according to the natural ordering of its elements.
	`$collectionHelper.newLinkedHashSet()`	Returns a new, empty LinkedHashSet.
`$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`	$`stringUtils`.`isNotBlank($issue.description)`	See StringUtils.
`$numberUtils`	`$numberUtils.toLong($!fieldHelper.getValueAsString("My text field containing a number"))`	See NumberUtils.

How to get the values of standard fields

Field	Usage
affectedVersions	`$!fieldHelper.getValueAsString("affectedVersions")`
assignee	`$!fieldHelper.getValueAsString("assignee")`
components	`$!fieldHelper.getValueAsString("components")`
created	`$!fieldHelper.getValueAsString("created")`
creator	`$!fieldHelper.getValueAsString("creator")`
description	`$!fieldHelper.getWikiMarkupValue("description")` (for Confluence storage format templates) `$!fieldHelper.getViewHtml("description")` (for PDF templates) `$!fieldHelper.getValueAsString("description")` (for other places)
dueDate	`$!fieldHelper.getValueAsString("dueDate")`
environment	`$!fieldHelper.getWikiMarkupValue("environment")` (for Confluence storage format templates) `$!fieldHelper.getViewHtml("environment")` (for PDF templates) `$!fieldHelper.getValueAsString("environment")` (for other places)
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")`