Our new Appfire Documentation Space is now live!

Take a look here! If you have any questions please email support@appfire.com

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 131 Next »

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
  • Commenting an issue by a post-function
  • Conditionally executing 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.

Templating features in Nunjucks


On this page:

Variables

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, now 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 of the issue being transitioned. You can access the issue data by looking up at its properties.

For example:

{{issue.fields.labels}} returns an array of label values, e.g. [ "1", "2" ]

{{issue.fields.reporter.name}} returns the username of the reporter, e.g. carter


 Click here to see some properties of the issue variable
Properties
Description
issue.idInternal Id number of the issue
issue.keyIssue key
issue.fields.summaryIssue summary
issue.fields.descriptionIssue description
issue.fields.issuetype.nameIssue type
issue.fields.issuetype.descriptionIssue type description
issue.fields.creator.nameUsername of the person who created the issue
issue.fields.creator.emailAddressEmail address of the person who created the issue
issue.fields.creator.displayNameDisplays name of the person who created the issue
issue.fields.creator.timeZoneTime zone of the creator
issue.fields.reporter.nameUsername of the person who reported the issue
issue.fields.reporter.emailAddressEmail address of the person who reported the issue
issue.fields.reporter.displayNameDisplay name of the person who reported the issue
issue.fields.reporter.timeZoneTime zone of the reporter
issue.fields.assignee.nameUsername of the person assigned to the issue
issue.fields.assignee.emailAddressEmail address of the person assigned to the issue
issue.fields.assignee.displayNameDisplay name of the person assigned to the issue
issue.fields.assignee.timeZoneTime zone of the assignee
issue.fields.createdDate and time the issue was created
issue.fields.updatedDate and time the issue was last updated
issue.fields.priority.nameIssue priority name
issue.fields.project.nameIssue project name
issue.fields.project.keyIssue project key
issue.fields.lastViewedDate and time the issue was last viewed by the current user
issue.fields.fixVersions[0].nameName of the first fix Version/s
issue.fields.fixVersions[0].descriptionDescription of the first fix Version/s
issue.fields.fixVersions[0].releaseDateRelease date of the first Fix Version/s
issue.fields.versions[0].nameName of the first Affects Version/s
issue.fields.versions[0].descriptionDescription of the first Affects Version/s
issue.fields.versions[0].releaseDateRelease date of the first Affects Version/s
issue.fields.components[0].nameName of the first component
issue.fields.components[0].descriptionDescription of the first component
issue.fields.duedateDue date of the issue
issue.fields.timespentTime spent on the issue
issue.fields.timeoriginalestimateThe original estimate of the time required to resolve the issue
issue.fields.resolution.nameResolution of the issue
issue.fields.watches.watchcountThe number of people watching the issue
issue.fields.labelsLabels the issue relates to
issue.fields.environmentThe hardware or software environment the issue relates to
issue.fields.votesThe number of votes an issue has
transition variable

The transition variable is used to insert information of the transition being executed.

For example:

{{transition.transitionName}} returns the name of the transition, e.g. Start Progress

{{transition.to_status}} returns the status of the transition, e.g. In Progress


 Click here to see the properties of the transition variable
PropertiesDescription
transition.transitionNameName of the current transition
transition.transitionIdNumerical ID of the current transition
transition.from_statusSource status of the transition
transition.to_statusDestination status of the transition
transition.workflowNameName of the current workflow
transition.workflowIdNumerical ID of the current workflow
linkedIssue variable

The linkedIssue variable, which is only available from post-functions that work on linked issues, is used to insert data of the linked issue being processed by the post-function.

For example:

{{linkedIssue.fields.description}} returns the description of the linked issue being processed.


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

The parentIssue variable, which is only available from post-functions that work on the parent issue, is used to insert data of the parent issue being processed by the post-function.

For example:

{{parentIssue.fields.priority.name}} returns the priority of the parent issue being processed.


 Click 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 first Fix Version/s
parentIssue.fields.fixVersions[0].releaseDateRelease date of the first Fix Version/s
parentIssue.fields.versions[0].nameName of the first Affects 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 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 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 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 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 %}

Tags

Tags are special blocks that perform operations on sections of the template. Nunjucks comes with several built-in tags, such as:

set

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.

if

The if tag tests a condition.

For example:

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

returns This is a task if and only if the issue type is "Task".

for

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

For example:

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

iterates over the comments variable and displays each comment body.

You might want to look here for some more built-in tags in Nunjucks.

Filters

Filters are essentially functions that can be applied to variables. They are called with a pipe operator (|) and can take arguments. Some examples:

dump

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

For example:

{{ issue.fields.reporter | dump(2) }} dumps the Reporter user object in "pretty" JSON format, using 2 spaces as indentation.

{{ issue.fields.fixVersions | dump }} dumps the array of Fix Version/s of the issue in un-prettyfied JSON format.


first

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

For example:

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

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


last

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

For example:

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

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


join

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 Version/s, separated by commas. For example: 1,1.0,2.0


dateadd

This is a custom Nunjucks filter that adds (or substracts) hours, days, weeks or months from a date. Its syntax is dateadd(<number>,<units>) where : 

    • <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.


date

This is a custom Nunjucks filter that offers rich date manipulation and formatting features. For more information, see here.


linkedIssues

linkedIssues is a custom Nunjucks filter that returns an array of the issues linked to the issue through a specified issue link type name.

    • If the link type is not specified the filter returns all linked issues except epic, parentIssue, stories and subtasks of the issue.
    • If the specified link type is invalid, an error is logged.

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.

{{ issue | linkedIssues | last }} returns the last linked issue.

{{ issue | linkedIssues('blocks') }} returns an array of issues linked to the current issue with 'blocks' link type.

To get the status of the first issue that is blocked by the current issue: {{ issue | linkedIssue('blocks') | first | field("fields.status.name") }}. See below for information on field filter.


epic

epic is a custom Nunjucks filter that returns the Epic of the issue. You can access all the fields of an Epic, similar to the issue object.

For example: 

{{ issue | epic }} returns the Epic of the issue

To get the name of the current issue's Epic: {{ issue | epic | field("fields['Epic Name'].name") }}. See below for information on field filter.


stories

stories is a custom Nunjucks filter that returns an array of stories associated with the issue (which should be an Epic). You can access all the fields of a Story, similar to the issue object.

For example: 

{{ issue | stories }} returns an array of stories of the Epic

Description of the last story associated to the Epic: {{ issue | stories | last | field("fields.description") }}. See below for information on field filter.


parentIssue

parentIssue is a custom Nunjucks filter that returns the Parent of the issue. You can access all the fields of the parent issue, similar to the issue object.

For example: 

{{ issue | parentIssue }} returns the parent of the issue

To get the Epic link of the current issue's parent: {{ issue | parentIssue | field("fields['Epic Link']") }}. See below for information on field filter.


subtasks

subtasks is a custom Nunjucks filter that returns an array of subtasks associated with the current issue. You can access all the fields of a subtask, similar to the issue object.

For example: 

{{ issue | subtasks }} returns an array of subtasks of the issue

The number of subtasks for an issue: 

{% set subtasks = issue | subtasks %}
{% set count = 0 %}
{% for subtask in subtasks %}
	{% set count = count + 1 %}
{%endfor%}
{{ count }}


field

field is a custom Nunjucks filter that returns the value of a field of an object. It applies to an object and takes the field name as a parameter. The field name can also be a path (using dot notation). This is useful to access the field of the result of another filter, instead of having to use an intermediate variable.

For example: 

{{ issue.fields.versions | first | field("name") }} returns the name of the first Affects Version/s.

{{ issue | epic | field("fields.reporter.name") }} returns the username of the reporter of the Epic of the issue.

{{ issue | parentIssue | field("fields['Original Estimate']") }} returns the original estimate of the issues' parent issue. 


sprints

sprints is a custom Nunjucks filter that returns the sprints of an issue or a board. It applies to an issue object or a board ID. For an issue, it uses the first scrum board to which the issue's project belongs. It takes an optional state or a list of comma-separated states as a parameter. See below the structure:

[
	{
    	"id": 37,
        "self": "http://www.example.com/jira/rest/agile/1.0/sprint/23",
        "state": "closed",
        "name": "sprint 1",
        "startDate": "2015-04-11T15:22:00.000+10:00",
        "endDate": "2015-04-20T01:22:00.000+10:00",
        "completeDate": "2015-04-20T11:04:00.000+10:00",
        "originBoardId": 5
    },
    {
        "id": 72,
        "self": "http://www.example.com/jira/rest/agile/1.0/sprint/73",
        "state": "future",
        "name": "sprint 2"
    }
]

For example: 

{{ issue | sprints }} returns a list of sprints. See below the structure: 

{{ issue | sprints | join("," , "name") }} returns the names of the Sprints, separated by commas.

{{ issue | sprints("active") | first | field("id") }} returns the currently active sprint ID.


isInGroup

The isInGroup filter is a custom Nunjucks filter that returns true if the user is in the specified group (passed as a parameter to the filter). The user, provided as input to the filter, can be either a username or a user object.

For example:

{{ currentUser | isInGroup("jira-administrators") }} returns true if the current user is in the "jira-administrators" group.

{{ issue.fields.assignee | isInGroup("jira-servicedesk-users") }} returns true if the assignee of the issue is in the "jira-servicedesk-users" group.


isInRole

The isInRole filter is a custom Nunjucks filter that returns true if the user is in the named role (passed as a parameter to the filter). The user, provided as input to the filter, can be either a username or a user object. Expected parameters are:

    • 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.

{{ issue.fields.reporter | isInRole("Developers","ARM") }} returns true if the current user is in the "Developers" project role of the project whose key is "ARM"

{{ currentUser | isInRole("Developers",linkedIssue) }} returns true if the current user is in the "Developers" project role of the project of the first issue linked to the current issue with 'blocks' link type.


userProperty(<property key>)

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

{{ issue.fields.assignee | userProperty("State") }} returns the value of the key State


You will find a lot more Nunjucks built-in filters here.

Expressions

You can use many types of literal expressions similar to those in javascript, such as:

Mathematical expressions

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.

{{ OriginalEstimate*2 }} doubles the original estimate of the issue.

Comparisons

Nunjucks allows you to compare two values or objects.

For example:

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

If

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 want to look here for some more built-in expressions in Nunjucks.

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.

  • No labels