Velocity

Single line comments

Multi-lines comments

Set a variable

Access a variable

Shorthand notation:

$myVariable

Formal reference notation (useful when you want to concatenate a velocity variable to a preset text)

#set($myVariable = "123.45")
${myVariable}Euros
## will be evaluated as "123.45Euros"

Quiet reference notation: evaluate non resolved variable to an empty string (blank)

$!myVariable

Loops

Conditional

Relational and logical operators

Escaping Valid VTL References

## The following line defines $email in this template:
#set( $email = "foo" )
$email
\$email

renders as

foo
$email

Maths

Velocity has a handful of built-in mathematical functions that can be used in templates with the set directive.

#set( $foo = $bar + 3 )
#set( $foo = $bar - 4 )
#set( $foo = $bar * 6 )
#set( $foo = $bar / 2 )
#set( $foo = $bar % 5 )

Range operator

The range operator can be used in conjunction with #set and #foreach statements.

Useful for its ability to produce an object array containing integers, the range operator has the following construction:

[n..m]

example:

#foreach( $foo in [1..5] )
$foo
#end

List<string>

 For fields of any type but Live User

^{$currentCustomfieldValue}

Value currently stored in the Elements Connect field.
Returns a list of string if the field contains many values.

This variable works only for Live fields and not for Snapshot fields (see CO-3752)

All queries

Empty when the field does not have any value.

List<user>

 For fields of type Live User

user

^$currentUser

Current user connected on the screen.

All queries

string

^{$currentUserLocale}

Locale of the current user (ie: fr_FR, no_NO, ...)

All queries

issue

^$issue

Current issue

All queries, expect the "Dashboard Gadget" view of the display query.

Velocity

^$query

Direct access to the query to execute

All queries

string

^$userInput

Characters typed by the user in the autocomplete text box.

Edit query when the editor is set to "Autocomplete".

Velocity

^$util

Set of useful functions

All queries

context

^$context 

Current context of the Search query

Search query

string

^isoDate

Iso date format 'yyyy-MM-dd'.

ex: 2015-02-22

string

^isoDateTime

Iso date time format 'yyyy-MM-dd HH:mm:ss.SSS'.

ex: 2015-08-22 17:31:15.123

string

^{isoDateTimeZone}

Iso date time zone format 'yyyy-MM-dd HH:mm:ss.SSSXXX'.

ex: 2015-08-22 17:31:15.123+02:00

string

^{format("...")}

This function allows you to format your date freely, if you need a specific formatting.

List<named-value>

^{affectedVersions}

Affected versions

user

^assignee

Issue assignee

List<named-value>

^components

Components

date

^created

Date when the issue has been created

user

^creator

Issue creator

date or

string

^{customfield_xxxx}

A custom field value - xxxx is the field id

>> Return a List if the field contains multiple values

The return type depends on the type of the custom field. If this is a date custom field (Date or Datetime picker), the return type is a dat. If this is a third party add-on custom field, you can have a look Customfields

In any other case, the value is returned as a st.

string

^description

Description

date

^duedate

Issue due date

string

^environment

Environment

string

^estimate

Estimate

List<named-value>

^fixVersions

Fix versions

string

^id

ID

Only available on existing issues, on the "Create issue" screen this variable is empty (the issue does not exists)

named-value

^{issuetype or issueType}

Issue type

string

^key

Key

Only available on existing issues, on the "Create issue" screen this variable is empty (the issue does not exists)

string

^{originalEstimate}

Original estimate

issue

^parent

Parent of the issue
Available on sub-tasks only, not available on the "Create sub-tasks" screen.

named-value

^priority

Priority

Project

^project

Project key of the the current issue

user

^reporter

Issue reporter (note: not available on the Create issue screen)

named-value

^resolution

Resolution

date

^{resolutiondate}

Content of the "Resolution date" field

date

^{resolutionDate}

Content of the "Resolution date" field (since 5.9.3)

named-value

^security

Security level

named-value

^status

Status

string

^summary

Summary

string

^timeSpent

Time spent

date

^updated

Date when the issue has been updated for the last time

string

^vote

This field is deprecated (mispelled). It is still supported for now but we recommend to use votes below instead.

string

votes

Votes count (since 5.9.3)

string

^watchers

This field is deprecated (mispelled). It is still supported for now but we recommend to use watches below instead.

string

watches

Watchers count (since 5.9.3)

date or

string

^{get("<custom field name>")}

or

^{get("customfield_xxx")}

Not recommended

We do not recommend to use this function.
Custom field names are not unique within a Jira instance, therefore Elements Connect picks the first field with the corresponding name.

You shall use the customfield_xxxx notation described above.

>> The return type depends on the type of the custom field

A custom field value - xxxx is the field id

>> Return a List if the field contains multiple values

The return type depends on the type of the custom field. If this is a date custom field (Date or Datetime picker), the return type is a d. If this is a third party add-on custom field, you can have a look c

In any other case, the value is returned as a st.

 Not for System fields: This is only available for custom fields (native or brought by third party). For system fields, please use notation described abobe (ie. $issue.summary).

string

^id

Id of the value

string

^name

Name of the value

string

^id

The project id

string

^key

The project key

string

^name

The project name

string

^id

The project category id

(ex: $issue.project[0].projectCategory.id)

string

^name

The project category name

(ex: $issue.project[0].projectCategory.name)

string

^description

The project category description

(ex: $issue.project[0].projectCategory.description)

^abort()

If this instruction is encountered during the evaluation of the query, the query won't be executed.

It is useful if we know in advance that the query won't return any result if certain conditions are not met.

In this example, the query is aborted if the summary of the issue is empty.

^{#if($issue.summary.length() == 0)
$query.abort()
#end
summary ~ $issue.summary}

Integer

^length()

Returns the String length

^{$issue.customfield_xxxxx.length()}

^{> 42}

string

^intList()

Shortcut for $var.serialize(",")

^{$issue.affectedVersions.id.intList()} 

^{> 10000,10001,10002}

string

^{prefix(<string>)}

Append a string before the string

^{$issue.issuetype.prefix("hello ")}

^{> hello Bug}

String

^{replace(<old str>, <new str>)}

Replace first string by another string

^{#set($variable = 'User story')
$variable.replace("story","tale")}

^{> User tale}

String

^{replaceAll(<old str>, <new str>)}

Returns a new string in which all occurrences of the first parameter are replaced by the second parameter.

The first parameter can be a string or a regex.

<sup>#set($variable = 'Jira (v8.6.1)')
$variable.toString().replaceAll(' (.*)',"") 

> Jira</sup>

string

^{serialize(<string>)}

Join the string using a delimiter

^{$issue.affectedVersions.name.serialize(";")}

^{> 1.0;1.1;1.2}

string

^stringList()

Append ' before and after each string and serialize them with a , separator

^{$issue.affectedVersions.id.stringList()}

^{> '1.0','1.1','1.2'}

string

^{suffix(<string>)}

Append a string after the string

^{$issue.issuetype.suffix(" world")}

^{> Bug world}

string

^urlEncode()

Convert all characters to be readable in an URL

^{$issue.summary.urlEncode()} 

^{> Elements Connect+in+a+nutshell}

string

^{encodeURIComponent()}

Convert a text to be readable in an URL parameter.

^{$issue.description.encodeURIComponent()}

^{> hello%20world%20%3F}

string

^encodeURI()

Convert a text to be readable in an URL.

^{$issue.description.encodeURI()}

^{> https%3A%2F%2Fvaliantys.atlassian.net%2Fsecure%2FDashboard.jspa}

string

^displayName

Display name of the user

string

^emailAddress

Email address of the user

string

^name

Name of the user

string

^userName

Username of the user

boolean

^{isInGroup(<jira group>)}

Is the user member of the given group ?

boolean

^{isInProjectRole(<role name>,<project key>)}

Does the user have the role in the project ?

Raw text

^{encodeURIComponent(<string>)}

Convert a text to be readable in an URL parameter.

^{$util.encodeURIComponent("hello world ?")}

^{> hello%20world%20%3F}

Raw text

^{encodeURI(<string>)}

Convert a text to be readable in an URL.

^{$util.encodeURI("https://valiantys.atlassian.net/secure/Dashboard.jspa")}

^{> https%3A%2F%2Fvaliantys.atlassian.net%2Fsecure%2FDashboard.jspa}

string

name 

Current execution context

string

SEARCH_BASIC_GENERATE_OPTIONS

Generate options list in the basic search mode

Velocity variables available:

• $issue 

• $userInput

• $currentCustomfieldValue

• $currentUser

• $currentUserLocale 

• $util

string

SEARCH_BASIC_GENERATE_JQL_QUERY

Generate the JQL query from the option selected in the basic search mode

Velocity variables available:

• $issue 

• $currentCustomfieldValue

• $currentUser

• $currentUserLocale 

• $util

string

SEARCH_ADVANCED_GENERATE_OPTIONS

Generate options list in the advanced search mode

Velocity variables available:

• $issue 

• $userInput

• $currentUser

• $currentUserLocale 

• $util

string

SEARCH_ADVANCED_TILDE_SEARCH

Evaluation of  ~ and !~ clauses in the advanced search mod

Velocity variables available:

• $issue 

• $currentUser

• $currentUserLocale 

• $util

string

getOptionName() 

Returns the name of the selected option (first option in case of multi select)

$issue.customfield_10005.getOptionName()

> Red

List<string>

getOptionNames() 

Returns the names of the selected options

$issue.customfield_10005.getOptionName().stringList()

> 'Red', 'Blue', 'Green'

string

getOptionId() 

Returns the ID of the selected option (first option in case of multi select)

$issue.customfield_10005.getOptionId()

> 10001

List<string>

getOptionIds() 

Returns the IDs of the selected options

$issue.customfield_10005.getOptionIds().intList()

> 10001, 10002, 10003

List<string>

customfield_xxxxx.getNames() 

(where XXX is the ID of the Sprint field)

Display the Issue sprints names

Current Issue is in one sprint: "Welcome to the Jungle"

$issue.customfield_10005.getNames()

> Welcome to the Jungle

Current Issue is in two sprints: "Welcome to the Jungle" and "Hells Bells"

$issue.customfield_10005.getNames().stringList()

> 'Welcome to the Jungle', 'Hells Bells'

10005 is the ID of the Sprint field

List<string>

customfield_xxxxx.getIds()

(where XXX is the ID of the Sprint field)

Display the Issue sprints ids

Current Issue is in one sprint, with ID 10002

$issue.customfield_10005.getIds()

> 10002

Current Issue is in two sprints, with ID 10002 and 10003

$issue.customfield_10005.getIds().intList()

> 10002, 10003

10005 is the ID of the Sprint field

List<string>

customfield_xxxxx.getNames() 

(where XXX is the ID of the Organization field)

Display the request organization names

Current request is shared with one organization: "My fantastic organization"

$issue.customfield_10002.getNames()

> My fantastic organization

Current request is shared with two organizations: "My fantastic organization" and "Customers first"

$issue.customfield_10002.getNames().stringList()

> 'My fantastic organization', 'Customers first'

10002 is the ID of the Organization custom field

List<string>

customfield_xxxxx.getIds()

(where XXX is the ID of the Organization field)

Display the request organization ids

Current request is shared with one organization, with ID 6

$issue.customfield_10002.getIds()

> 6

Current request is shared with two organizations, with ID 6 and 7

$issue.customfield_10002.getIds().intList()

> 6, 7

10002 is the ID of the Organization custom field

string

^{customfield_xxxxx}

Display the display value of selected Account

^{$issue.customfield_10001}

^{> Account 1 (ACCOUNT1)}

string

^{customfield_xxxxx.id}

Display the id of selected Account

^{$issue.customfield_10001.id}

^{> 2}

string

^{customfield_xxxxx.name}

Display the name of selected Account

^{$issue.customfield_10001.name}

^{> Account 1}

Issue with one fix version "1.2"

$issue.fixVersions 

1.2

N/A

Issue with two fix versions "1.2" and "1.3"

$issue.fixVersions 

1.2

When we need to evaluate a query like "SELECT * FROM XXX where version='$issue.fixVersion'", we only take the first element if there are many.

To use the other elements, you need alternate expressions (see below)

Issue with two fix versions "1.2" and "1.3"

$issue.fixVersions.stringList() 

'1.2', '1.3'

This way you can write "SELECT * from XXX where version in ($issue.fixVersions.stringList())

Issue of type 'Bug'

$issue.issuetype 

Bug

Issue of type 'Bug'

$issue.issuetype.serialize("; ") 

Bug

As this is considered as a list of one issue type, you can apply the function serialise to it. This only has one element.

As you may also have noticed, the serialize function need a string input, and the default string evaluation for issue type (Named Value) is 'name'.

The expression is equivalent to $issue.issuetype.name.serialize("; "