| Section | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Nunjucks in JMWE for JIRA Cloud
Nunjucks in JMWE for JIRA Cloud is used to insert information while setting a field value or creating the body of a comment by a post-function. You might want to insert issue and transition information into the value using the templating features available in Nunjucks. Some basic templating features are described in the next section, and more are documented on the Nunjucks website.
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 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. 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 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:
...
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.fixVersions | dump }} dumps the array of Fix Version/s of the issue in JSON format.
first
The first filter gets the first value/object in the array. For example:
...
{{ 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.labels | last }} returns the last label of the issue.
join
The join filter returns a string which is a concatenation of strings. For example:
...
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.
...
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.
...
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.
...
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.
...
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.
...
| Code Block |
|---|
{% set subtasks = issue | subtasks %}
{% set count = 0 %}
{% for subtask in subtasks %}
{% set count = count + 1 %}
{%endfor%}
{{ count }} |
field
field is 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.
...
{{ issue | parentIssue | field("fields['Original Estimate']") }} returns the original estimate of the issues' parent issue.
sprints
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 :
...
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 Nunjucks. You might also want to refer here for use cases with Nunjucks annotations.