Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column

Introduction to Nunjucks

Nunjucks is a sophisticated templating engine for JavaScript. It lets you insert dynamic content in any text through the use of templates. A template contains variables and/or expressions, which get replaced with values when a template is rendered; and tags, which control the logic of the template. See here for an overview of the templating features available in Nunjucks.

Nunjucks in JMWE for JIRA Cloud

Nunjucks in JMWE for JIRA Cloud is used to insert information while 

  • Setting a field value by a post-function
  • Creating the body of a comment by a post-function
  • Conditional execution of a post-function

You can insert issue and transition information into the value using the templating features available in Nunjucks. Some basic templating features are described in this document, and more are documented on the Nunjucks website.

Column
width400px
Panel
borderColorsilver
bgColor#f5f5f5
borderWidth1
borderStylesolid

On this page:

Table of Contents

...

A variable looks up a value from the template context. If you want to insert the value of a variable in your template, you can use the following syntax: {{ myVar }}. This looks up for the myVar variable from the context and displays it. Variable names can have dots in them which look up properties, just like in javascript.

Variables available in JMWE

JMWE makes the issue, transition, linkedIssue, parentIssue and currentUser variables available to templates. You can access their properties using "." or "[ ]". For example, you can access the current issue key using {{issue.key}}.

issue variable

The issue variable is used to insert data from the issue being transitioned. You can access the issue data by looking up at its properties.

...

Expand
titleClick here to see the properties of the parentIssue variable

Properties

Description

parentIssue.idInternal Id number of the parent issue
parentIssue.keyParent issue key
parentIssue.fields.summaryParent issue summary
parentIssue.fields.descriptionParent issue description
parentIssue.fields.issuetype.nameParent issue type
parentIssue.fields.issuetype.descriptionParent issue Issue type description
parentIssue.fields.creator.nameUsername of the person who created the parent issue
parentIssue.fields.creator.emailAddressEmail address of the person who created the parent issue
parentIssue.fields.creator.displayNameDisplays name of the person who created the parent issue
parentIssue.fields.creator.timeZoneTime zone of the creator
parentIssue.fields.reporter.nameUsername of the person who reported the parent issue
parentIssue.fields.reporter.emailAddressEmail address of the person who reported the parent issue
parentIssue.fields.reporter.displayNameDisplay name of the person who reported the parent issue
parentIssue.fields.reporter.timeZoneTime zone of the reporter of the parent issue
parentIssue.fields.assignee.nameUsername of the person assigned to the parent issue
parentIssue.fields.assignee.emailAddressEmail address of the person assigned to the parent issue
parentIssue.fields.assignee.displayNameDisplay name of the person assigned to the parent issue
parentIssue.fields.assignee.timeZoneTime zone of the assignee of the parent issue
parentIssue.fields.createdDate and time the parent issue was created
parentIssue.fields.updatedDate and time the parent issue was last updated
parentIssue.fields.priority.nameParent Issue priority name
parentIssue.fields.project.nameParent Issue project name
parentIssue.fields.project.keyParent Issue project key
parentIssue.fields.lastViewedDate and time the parent issue was last viewed by the current user
parentIssue.fields.fixVersions[0].nameName of the first Fix Version/s
parentIssue.fields.fixVersions[0].descriptionDescription of the firstFix Version/s
parentIssue.fields.fixVersions[0].releaseDateRelease date of the firstFix Version/s
parentIssue.fields.versions[0].nameName of the firstAffects Version/s
parentIssue.fields.versions[0].descriptionDescription of the first Affects Version/s
parentIssue.fields.versions[0].releaseDateRelease date of the first Affects Version/s
parentIssue.fields.components[0].nameName of the first component
parentIssue.fields.components[0].descriptionDescription of the first component
parentIssue.fields.duedateDue date
parentIssue.fields.timespentTime spent
parentIssue.fields.timeoriginalestimateThe original estimate of the time required to resolve the parent issue
parentIssue.fields.resolution.nameResolution of the parent issue
parentIssue.fields.watches.watchcountThe number of people watching the parent issue
parentIssue.fields.labelsLabels the parent issue relates to
parentIssue.fields.environmentThe hardware or software environment the parent issue relates to
parentIssue.fields.votesThe number of votes a parent issue has

currentUser variable

The currentUser variable currentUser variable is used to insert information about the current user, i.e. the user triggering the transition. Only two properties of the current user are available: key and name. For  

For example:

{{currentUser.name}} returns the name of the user triggering the transition, e.g. carter

{{currentUser.key}} returns the key of the user triggering the transition, e.g. carter001

now variable

The now variable now variable is used to insert the current date and time. This is useful to save a transition's execution date/time in a custom field. For  

For example:

{{now}} returns the current date and time, e.g. 2016-09-30T13:57:23.608Z

User-defined variables

In addition to the above variables, you can also create your own variables within the template using the set Nunjucks tag.

For example:

{% set x = "High" %} sets the value of the variable x to High. You can also set the variable to an object. For example: {% set assignee = issue.fields.assignee %}

...

The set tag creates or modifies a variable.

For example:

{% set comments = issue.fields.comment.comments %} sets the comments variable with all the comment objects of the issue.

...

The if tag tests a condition.

For example:

Code Block
{% if issue.fields.issuetype.name == "Task"}
This is a task
{% endif %} 

...

The for tag iterates over an array of values or objects. For  

For example:

Code Block
{% set comments = issue.fields.comment.comments %}
{% for comment in comments %}
{{ comment.body }}
{% endfor %}

...

The dump filter dumps an object as a JSON string into the template.

For example:

{{ issue.fields.reporter | dump }} dumps the Reporter user object in JSON format.

...

The first filter gets the first value/object in the array.

For example:

{{ issue.fields.fixVersions | first }} returns the first Fix version Version/s object of the issue.

{{ issue.fields.labels | first }} returns the first label of the issue.

...

The last filter gets the last value/object in the array. For  

For example:

{{ issue.fields.components | last }} returns the last component object of the issue.

...

The join filter returns a string which is a concatenation of strings. 

For example:

{{ issue.fields.fixVersions | join("," , "name") }} joins the names of the Fix versions Version/s, separated by commas. For example: 1,1.0,2.0

...

    • <number> is the number of units to add to the date (can be negative)
    • <units> is one of "days", "hours", "weeks" or "months" (or their equivalent: "d", "h", "w", "m")

For example: 

{% set duedate = issue.fields.created | dateadd(2,"w") %} sets the duedate variable to two weeks after the creation date of the issue.

...

You can access all the fields of a linked issue, similar to the issue object.

For example : 

{{ issue | linkedIssues }} returns the array of linked issues.

...

    • isInRole(roleName): returns true if the user is in the named project role of the project of the current issue
    • isInRole(roleName, projectKey): returns true if the user is in the named project role of the project whose key is the specified projectKey
    • isInRole(roleName, issueObject): returns true if the user is in the named project role of the project of the given issue object

For example:

{{ currentUser | isInRole("Developers") }} returns true if the current user is in the "Developers" project role.

...

The userProperty filter is a custom Nunjucks filter that returns the value of the user property key (passed as a parameter to the filter) from the user entity properties that are set on the User properties editor page. The user, provided as input to the filter, can be either a username or a user object. If the requested user property cannot be found, the filter returns undefined (which is equivalent to an empty string).

For example:

{{ currentUser | userProperty("Location") }} returns the value of the key Location

...

Nunjucks allows you to do simple calculations on numbers.

For example:

{{ issue.fields.Field1 + issue.fields.Field2 }} outputs the sum of two custom field values, where Field1 and Field2 are the custom field names.

...

Nunjucks allows you to compare two values or objects.

For example:

{{ issue.fields.issuetype.name == "Task" }} compares both values.

...

Nunjucks allows you to use if as an inline expression.

For example:

{{ "true" if var else "false" }} outputs the string "true" if the variable var is defined, else it outputs "false".

...

You might also want to look at Accessing the details of an issue or a transition in Nunjucks to know how to access the details of an issue or a transition.

See here for more templating features available in NunjucksYou might also want to refer here for use cases with Nunjucks annotations.