| Excerpt |
|---|
Filters are essentially functions that can be applied to variables. Filters are called with a pipe operator (|) and can take arguments. This document details custom Nunjucks filters created for JMWE. |
In this page:
| Table of Contents | ||||
|---|---|---|---|---|
|
...
allIn
This is a allIn is a custom Nunjucks filter that operates returns true if every element of the input array is included in the parameters, false otherwise. The parameters can be scalar values and/or arrays of scalar values to compare against the input. This applies to an array of scalar values (string, number, etc.). For example:
{{ ["a","c"] | allIn( ["a","b"], "c" ) }} outputs true because both a and c are in the parameters{{ ["a","z"] | allIn( ["a","b"], "c" ) }} outputs false because z is not in the parameters{{ issue.fields.components | field("name") | allIn("Comp1","Comp2") }} outputs true if the issue's Components are Comp1 and/or Comp2.
availableOptions
This is a custom Nunjucks filter that operates on a string representing the name or ID of a select-type custom field implemented by a third-party add-on, such as Tempo's Account and Team fields and returns the list of values available for a Select-type field. 
Note the filter can be slow. Use with parsimony.
...
{{ issue.fields.comment.comments | last | commentProperty("sd.public.comment") | field("internal") }} returns true if the latest comment of the issue is a Jira Service Desk "internal" comment.
...
This is a custom Nunjucks filter that offers rich date manipulation and formatting features. For more information, see here.
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 :
...
{% set duedate = issue.fields.created | dateadd(2,"w") %} sets the duedate variable to two weeks after the creation date of the issue.
emailAddress
This is a custom Nunjucks filter that operates on a user's accountId, a user object, an array of accountIds, or an array of user objects and returns the email address of one or more users. This Nunjucks filter is now the only way to return the email address of a user, since Jira removed the emailAddress property of user objects.
...
{{ issue.fields.reporter | emailAddress}} returns the email address of the Reporter.
{{ issue.fields.Approvers | emailAddress}} returns an array of the emails of the issue's Approvers.
...
{{issue | epic("status") | field("fields.status.name") returns the name of the status of the Epic.
...
{% set stories = issue | epic("key") | stories("status") %} creates a variable 'stories' that holds all stories of the parent Epic of the current issue (i.e. the current issue and all its sibling stories), limiting the fields returned for each story.
Note: For better performance, it is recommended to specify the fields to return, whenever possible.
field
field is a custom Nunjucks filter that returns the value of a field of an object. It applies to an object or an array of objects and takes the field name as a parameter. In the case of an array of objects, it returns an array containing the values of the specified field for each object of the input array. 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.
...
{{ linkedIssue | fieldHistory( "assignee" ) | field("to_string") | dump(2) }} returns an array of display names of users the linked issue is assigned to.
filter
This is a custom Nunjucks filter that filters an array, searching for either a scalar value (e.g. string) or an object whose fields must match with those of the array members, or an array of a path followed by a value to match. The filter returns an array of objects. When no value matches the criteria, an empty array is returned.
You can inverse the filter using its exclude parameter. Passing true in this parameter returns an array of objects that do not match the search.
...
{{ issue.fields.fixVersions | filter({name:"3.0"}) | dump(2) }} filters the fixVersions, for a version with name 3.0 and dumps it in "pretty" JSON format, using 2 spaces as indentation.
{{ issue.fields['MWEC_Check'] | filter({value:"Option 1"}) }} filters the options, for an option with value Option 1 and returns an array containing that option.
...
{{ issue.fields.versions | filter({name:"2.0"} , true) | dump(2) }} filters the fixVersions, for versions that do not have the name 2.0 and dumps them in a "pretty" JSON format, using 2 spaces as indentation.
...
{{issue.fields.comment.comments | filter(["author.active",true]) | join("\n","body")}} returns the body text of all comments made by active users, separated by newlines.
find
This is a custom Nunjucks filter that finds the first element of an array matching the condition, searching for either a value (string) or an object based on the value of a field, and returns an object. When no match is found, null is returned.
...
{{ issue.fields.fixVersions | find({name:"3.0"}) | dump(2) }} finds for the first version with the name 3.0 and dumps it in "pretty" JSON format, using 2 spaces as indentation.
{{ issue.fields['MWEC_Check'] | find({value:"Option 1"}) }} finds for the first option with the value Option 1 and returns the option.
...
{{ issue.fields.labels | find("test") }} finds label test and returns it. Can be useful to check whether the labels field contains a specific label.
find(path, value)
This is a custom Nunjucks filter that finds the first element of an array of objects matching the condition, searching for the specified value at the specified path. When no match is found, null is returned.
...
{{ issue.fields.fixVersions | find("name", "3.0"}) | dump(2) }} finds for the first version with the name 3.0 and dumps it in "pretty" JSON format, using 2 spaces as indentation.
{{issue.fields.comment.comments | find("author.active", true) | field("body") }} returns the body text of the first comment made by an active user.
findUsers
This is a custom Nunjucks filter that returns the list of active users that match a specified string. The string will be searched for in the accountId, emailAddress and displayName fields. This filter returns an array of users. When no match is found, an empty array is returned. Note that the search string is not case-sensitive.
For example:
...
{{ issue.fields['Custom text field'] | findUsers | first | field("emailAddress") }} returns the email Address of the first user that matches the string in the custom text field.
groupMembers
This is a custom Nunjucks filter that returns the members (users) of a group. The input to the filter can be either the name of the Group or a Group object. The maximum number of users that the filter can return is 1000. When no match is found, an empty array is returned.
...
| Code Block | ||
|---|---|---|
| ||
{% set names = [] %}
{% for group in issue.fields["MWEC_Group picker"] %}
{% set ignored = names.push( group | groupMembers | join(",","accountId") )%}
{% endfor %}
{{names}} |
in
in is a custom Nunjucks filter that returns returns true if the input is contained in the parameters, false otherwise. The parameters can be scalar values and/or arrays of scalar values to compare against the inputagainst the input. If the input is an array, then at least one element of the array must be included in the parameters for the filter to return true. This applies to any scalar value (string, number, etc.) or an array of scalar values. For example:
{{ "a" | in("a","b") }} outputs true
{{ "a" | in( ["a","b"], "c" ) }} outputs true
{{ ["a","z"] | in( ["a","b"], "c" ) }} outputs true because a is in the parameters{{ ["y","z"] | in( ["a","b"], "c" ) }} outputs false because neither y nor z is in the parameters
{{ issue.fields.project.key | in("TEST","KAN") }} outputs outputs true if the issue belongs to projects TEST or KAN.
{{ issue.fields.assignee.accountId | in(issue.fields.watches | field("accountId"), issue.fields["Request Participants"] | field("accountId")) }} outputs true if the Assignee of the issue is watching the issue or is a requesting participant.
initiative
initiative is a custom Nunjucks filter that returns the Initiative of an issue, or more precisely the "parent" issue in the Jira Portfolio hierarchy of the issue visible through the "Parent Link" field. If you don't specify which fields to return, you can access all the fields of the Initiative, just like with any issue object.
...
{{ issue | initiative("status") | field("fields.status.name") }} returns the name of the status of the Initiative.
...
{% set epics = issue | initiative("key") | membersOfInitiative("status") %} creates an epics variable that holds all epics of the parent Initiative of the current issue (i.e. the current issue and all its sibling epics), limiting the fields returned for each Initiative.
Note: For better performance, it is recommended to specify the fields to return, whenever possible.
...
{{issue.fields.reporter | isActiveUser}} returns true if the Reporter of the issue is still active.
isInGroup
The isInGroup filter is a custom Nunjucks filter that returns true if the user is in the specified group name (passed as a parameter to the filter). The user, provided as input to the filter, can be either an accountId or a user object.
...
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 accountId or a user object. Expected parameters are:
...
{{ issue | issueProperty("a.property") }} returns the value of the "a.property" property of the current issue
...
{% set myObj = '{"f1":"val"}' | JSONparse %}{{ myObj.f1 }} outputs val
linkedIssues
linkedIssues is a custom Nunjucks filter that returns an array of the issues linked to the current issue, optionally specifying one or more issue link type name(s) as they appear on the issue.
...
{{ issue | linkedIssues('blocks', ['status','summary']) }} returns an array of issues linked with the 'blocks' link type, with only the Summary and Status fields.
{{ issue | linkedIssues('blocks', ['status']) | first | field("fields.status.name")}} returns the name of the status of the first linked issue with the 'blocks' link type.
{{ issue | linkedIssues('belongs to Initiative') | field("fields.status.name")}} returns the name of the status of the issue's Initiative.
Note: For better performance, it is recommended to specify the fields to return, whenever possible.
...
{{ issue | membersOfInitiative("assignee") | last | field("fields.assignee.accountId") }} returns the accountId of the user the last epic belonging to the Initiative is assigned to.
{{ issue | membersOfInitiative("key") | join(",","key") }} returns the issuekey of all epics of the Initiative, separated by a comma.
Note: For better performance, it is recommended to specify the fields to return, whenever possible.
optionID
The optionID filter is a custom Nunjucks filter that returns the Option ID (numerical ID) of an Option value applicable to a select-type field implemented by third party add-ons, such as the Tempo' s Team and Account fields. The filter is applied to a string representing an Option value and takes the fieldNameOrID as a parameter.
...
{{ "Shared Team" | optionID("customfield_14589") }} returns the numerical ID of the Tempo team whose name is "Shared Team"
| Note |
|---|
Note that this filter can be slow. When setting the field to a constant value, it is, therefore, preferable to directly input the numerical ID in the post-function configuration, which you will get by running the Nunjucks expression above in the Nunjucks Tester. |
organizationID
The organizationID filter is a custom Nunjucks filter that returns the Jira Service Desk Organization numerical ID of one or more Organization(s). The filter is applied to a string representing an Organization name, or to an array of Organization names.
...
{{ issue | parentIssue("status") | field("fields.status.name") }} returns the status of the parent issue.
{{ issue | parentIssue | field("fields['Epic Link']") }} returns the Epic link of the current issue's parent.
Note: For better performance, it is recommended to specify the fields to return, whenever possible.
...
remoteLinks is a custom Nunjucks filter that returns an array of all remote links (for example a Confluence page or an issue in another Jira instance) from the issue. It applies to an issue object or an issue key.
...
{{ 'Administrators' | roleMembers("TEST", true) }} returns the displayNames of all members of the Administrators project role of the project "TEST"
searchIssues
This is a custom Nunjucks filter that runs a JQL query and returns matching issues. The filter operates on a string (the JQL query) and takes the following optional, named parameters:
maxResults: maximum number of issues to return (default 10, maximum 1000 and minimum 1)
startAt: index of the first result to return (default 0), useful for paginating through results
fields: (default: "summary") either a comma-separated string or an array of strings listing fields to return for each issue. Examples:
"*all"- include all fields - use only if you are limiting the number of results to 10 or less"*navigable" - include just navigable fields (fields that can be added as a column in list view) - use only if you are limiting the number of results to 10 or less"summary,comment"or["summary","comment"] - include just the summary and comments"-description"- include navigable fields except for the description (the default is *navigable for search)"*all,-comment"- include everything except comments - use only if you are limiting the number of results to 10 or less
...
("assignee=" + issue.fields.assignee._accountId) | searchIssues(maxResults = 30) returns the first 30 issues that have the same assignee as the current issue.
serverInfo
This is a custom Nunjucks filter that displays the current server information. This allows post functions to perform actions based on the server (environment, e.g. Prod, Dev, QA) they are running on.
...
{{ "deploymentType" | serverInfo == "Cloud"}} returns true if the deployment type is Cloud (which will obviously always be true)
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.
...
{{ 11 | sprints("active") | field("values") | first | dump(2) }} returns first active sprint of the board. You can find the board ID in its URL, after "rapidView="
stories
stories is a custom Nunjucks filter that returns an array of stories associated with the issue (which should be an Epic). If you don't specify which fields to return, you can access all the fields of the parent, just like with any issue object.
For example:
{{ issue | stories }} returns an array of the stories associated with the Epic.
...
{{ issue | stories("key") | join(",","key") }} returns the issuekey of all stories of the Epic, separated by a comma.
Note: For better performance, it is recommended to specify the fields to return, whenever possible.
...
{{ issue | subtasks("key") | length }} returns the number of subtasks for an issue.
Note: When you need minimal information for better performance, it is recommended to use either the subtasks field of the issue or the subtasks filter specifying the fields to return, whenever possible. For example to get the status of the subtasks of the current issue
Using the subtasks field
Code Block {{ issue.fields.subtasks | field("fields.status.name") }}Using the subtasks filter
Code Block {{ issue | subtasks("status") | field("fields.status.name") }}
text2html
This is a custom Nunjucks filter that converts a multi-line text value to html, as expected in the html body in the Email Issue post-function. The newlines are converted to paragraphs and html tags are escaped. The input for the filter is either a multi-line text or a multi-line text field.
...
Text or Multi-line text value | Template | Returns |
|---|---|---|
Hi <i>This is a test Email<i> Regards |
|
|
Your issue has been resolved.\nPlease provide your feedback.\nThanks. |
|
|
userInfo
This is a custom Nunjucks filter, which when provided with a accountId, or a user object containing a accountId field, returns the corresponding user object. You can dump the object, view its fields (in the template test result panel) and then either use the field filter to get a field value or pass the field as a parameter to the filter.
For example:
{{currentUser | userInfo | dump(2) }} dumps the current user object in a "pretty" JSON format, using 2 spaces as indentation.
...
{{ issue.fields.assignee | userInfo | field("groups.size") }} returns the number of groups the current assignee belongs to.
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 an accountId or a user object. If the requested user property cannot be found, the filter returns undefined (which is equivalent to an empty string).
...
The usersInOrganization filter is a custom Nunjucks filter that returns the users that belong to a Jira Service Desk Organization. The filter is applied to a number or string representing an Organization ID. If the organization is not found, returns undefined (which is displayed as an empty string).
...