Jira expressions types

This page defines all the types supported in Jira expressions along with their properties and methods.

You can examine the type of any expression at runtime with the typeof operator. For example, typeof issue will return "Issue", which is the name of the type of the issue context variable.

Issue

Constructors
  • N new Issue(number): Loads an issue from the database using the given ID.
  • N new Issue(string): Loads an issue from the database using the given key.

The constructors return null if the issue doesn't exist or you don't have permission to view it.

Properties
  • id: The issue ID (Number).
  • key: The issue key (String).
  • summary: The issue key (String).
  • description: The issue description (RichText).
  • environment: The value of the environment field (RichText).
  • priority: The priority of the issue (IssuePriority).
  • issueType: The issue type (IssueType).
  • status: The issue status (IssueStatus).
  • created: The creation time of the issue (Date).
  • updated: The time when the issue was last updated at (Date).
  • dueDate: The time the issue is due (CalendarDate).
  • resolutionDate: The time the issue was resolved at (Date).
  • resolution: The resolution of the issue (Resolution).
  • originalEstimate: The original estimate of how long working on the issue would take, in seconds (Number).
  • remainingEstimate: The estimate of how much longer working on the issue will take, in seconds (Number).
  • timeSpent: The time that was spent working on the issue, in seconds (Number).
  • securityLevel: The security level set for the issue (SecurityLevel).
  • 1 parent: The issue parent. During issue creation, only available in workflow validators for subtasks in company-managed projects. It's available for all existing issues. (Issue).
  • 1 project: The project the issue belongs to (Project).
  • 1 assignee: The assignee of the issue (User).
  • 1 reporter: The reporter of the issue (User).
  • 1 creator: The user who created the issue (User).
  • 1 votes: The number of voters of the issue. Returns an error if voting is disabled (Number).
  • 1 voters: The voters of the issue. Only returns the voters the requesting user has permissions to view. Returns an error if voting is disabled (List<User>).
  • 1 watches: The number of watchers of the issue. Returns an error if watching is disabled (Number).
  • 1 watchers: The watchers of the issue. Only returns the watchers the requesting user has permissions to view. Returns an error if watching is disabled (List<User>).
  • 1 labels: The list of labels associated with the issue (List<String>).
  • 1 versions: The list of versions the issue affects (List<Version>).
  • 1 fixVersions: The list of versions where the issue was fixed (List<Version>).
  • 1 components: The list of project components the issue belongs to (List<Component>).
  • 1 attachments: The list of issue attachments (List<Attachment>).
  • 1 worklogs: The worklogs of the issue ordered by creation date - oldest first (List<Worklog>).
  • N len 1 subtasks: The list of subtasks (List<Issue>).
  • N len 1 comments: The list of issue comments (List<Comment>).
  • N links: The list of issue links (List<IssueLink>).
  • N changelogs: The ordered changelogs of the issue - newest first (List<Changelog>).
  • properties: The properties of the issue (EntityProperties).

In addition to these, all custom fields are available and can be referenced by one of the following:

  • 1 ID: issue.customfield_10010
  • 1 key: issue['com.my.app.field-key']

Custom fields are returned as JSON values, in the same format as in the Get issue REST API.

Any field that is hidden in the field configuration active for the current issue will be returned as null, regardless of its actual value. Read more about hiding and showing fields in the documentation on the Changing a field configuration page.

Functions
  • 1 getNewestChangelog(string, Map?): Returns the newest changelog for the given field. Changelogs can be filtered by a subset of properties of the ChangelogItem type: from, fromString, to, toString. For example, to get information about the last time the issue status changed from "In Progress" to "Done", write: issue.getNewestChangelog('status', {fromString: 'In Progress', toString: 'Done'}).

Jira Software Fields

If Jira Software is licensed for the current user, the following fields will also be available.

  • isEpic: true if the issue is an epic, false otherwise (Boolean).
  • N epic: The epic the issue belongs to (Issue).
  • N sprint: The sprint the issue belongs to (Sprint).
  • N closedSprints: The list of all past sprints the issue belonged to (List<Sprint>).
  • N flagged: true if the issue is flagged, false otherwise (Boolean).

Epics

Epics (issues that have issue.isEpic equal to true or returned by issue.epic) have additional, epic-specific fields. These fields are null for regular issues.

  • N name: The epic name (String).
  • N done: true if the epic is completed, false otherwise (Boolean).
  • N color: The epic color (String: 'color_1', 'color_2', ..., 'color_9').
  • N stories: The list of all stories in the epic (List<Issue>).

Project

Constructors
  • N new Project(number): Loads a project from the database using the given ID.
  • N new Project(string): Loads a project from the database using the given key.

The constructors return null if the project doesn't exist or you don't have permission to view it.

Properties
  • id: The project ID (Number).
  • key: The project key (String).
  • style: The style of the project (String: 'next-gen', 'classic').
  • name: The name of the project (String).
  • projectTypeKey: The key of the project type (String).
  • projectCategory: The category of the project (ProjectCategory).
  • lead: The project lead (User).
  • avatarUrls: A map of avatar URLs, indexed by size, for example, "32x32" (Map<String, String>).
  • properties: The properties of the project (EntityProperties).

Project Category

  • id: The project category ID (Number).
  • name: The name of the project category (String).
  • description: The description of the project category (String).

User

Constructors
  • new User(string): Loads a user from the database using the given account ID.

The constructor returns null if the user doesn't exist.

Properties

IssuePriority

  • id: The priority ID (Number).
  • name: The name of the priority (String).
  • description: The priority description (String).

IssueStatus

  • id: The status ID (Number).
  • name: The name of the status (String).
  • description: The status description (String).
  • category: The status category (StatusCategory).

StatusCategory

  • id: The category ID (Number).
  • key: The key of the category (String).
  • name: The category name (String).
  • colorName: The color name associated with the category (String).

IssueType

  • id: The ID of the issue type (Number).
  • name: The name of the issue type (String).
  • description: The description of the issue type (String).
  • iconUrl: The absolute URL of the icon that represents the issue type (String).
  • hierarchyLevel: The hierarchy level of the issue type. 1 is for epics, -1 for subtasks, and 0 for issues (Number).
  • properties: The issue type properties (EntityProperties).

Resolution

  • id: The ID of the resolution (Number).
  • name: The name of the resolution (String).
  • description: The description of the resolution (String).

Comment

  • id: The ID of the comment (Number).
  • body: (RichText).
  • author: The author of this comment (User).
  • created: The creation time of the comment (Date).
  • updated: The time when the comment was last updated at (Date).
  • properties: The comment properties (EntityProperties).

RichText

This type represents fields with text. It provides one property:

  • plainText to obtain the plain text representation of the field value (String).
Constructors
  • 1 new RichText(Map): Creates a RichText value based on a map that contains ADF (Atlassian Document Format).

In version 3 of the REST API, this constructor allows you to access the plain text value of multi-line custom fields. It also works whenever the expression is evaluated in a context where such fields are returned as ADF instead of plain text.

To write an expression that always returns the plain text value of a field regardless of the API version, use the typeof operator to examine the runtime type of the field value:

1
2
let plainTextValue = value => typeof value == 'Map' ? new RichText(value).plainText : value ;
plainTextValue(issue.customfield_10000)
  • id: The ID of the issue link (Number).
  • type: (IssueLinkType).
  • direction: Direction of the link, from the point of view of the issue the link was obtained for (String: 'inward', 'outward').
  • outwardIssue: The outward issue of the link (Issue).
  • inwardIssue: The inward issue of the link (Issue).
  • linkedIssue: The issue linked to (Issue).

IssueLinkType

  • id: The ID of the issue link type (Number).
  • name: The name of the issue link type (String).
  • inward: The name of the link when it points to the issue (String).
  • outward: The name of the link when it points out of the issue (String).

SecurityLevel

  • id: The security level ID (Number).
  • name: The security level name (String).
  • description: The description of the security level (String).

Version

  • id: The version ID (Number).
  • name: The version name (String).
  • description: The version description (String).
  • archived: true if the version has been archived, false otherwise (Boolean).
  • released: true if the version has been released, false otherwise (Boolean).
  • releaseDate: The release date of the version (CalendarDate).
  • startDate: The start date of the version (CalendarDate).

Component

  • id: The component ID (Number).
  • name: The component name (String).

Attachment

  • id: The attachment ID (Number).
  • author: The user who created the attachment (User).
  • filename: The name of the attachment (String).
  • size: The size of the attachment, in bytes (Number).
  • mimeType: The media type of the attachment (String).
  • created: The attachment creation date (Date).

Changelog

  • id: The changelog ID (String).
  • author: The user who made the change (User).
  • items: The list of items changed (List<ChangelogItem>).
  • created: The changelog creation date (Date).

ChangelogItem

  • field: The name of the changed field (String).
  • fieldId: The ID of the changed field (String).
  • from: The details of the original value. Can be null or empty (String).
  • fromString: The details of the original value as a string. Can be null or empty (String).
  • to: The details of the new value. Can be null or empty (String).
  • toString: The details of the original value as a string. Can be null or empty (String).

For example, if an issue is moved from the backlog to a sprint, the "Sprint" field is modified and the changelog item takes the following values:

  • field: "Sprint" (The field name.)
  • fieldId: "customfield_10020" (The field ID.)
  • from: "" (The ID of the previous sprint, which is empty because there was none.)
  • fromString: "" (The name of the previous sprint, also empty.)
  • to: "1" (The ID of the sprint the issue was moved to.)
  • toString: "SPRINT-1" (The name of the new sprint.)

Worklog

  • id: The worklog ID (String).
  • author: The user who created the worklog (User).
  • updateAuthor: The user who updated the worklog (User).
  • created: The creation time of the worklog (Date).
  • updated: The time when the worklog was last updated (Date).
  • started: The date the worklog started (Date).
  • timeSpent: The time reported by the author (String).

ProjectRole

  • id: The project role ID (Number).
  • name: The project role name (String).
  • description: The project role description (String).

App

Represents the Connect or Forge app that provides or executes the expression.

Forge apps have access to the following properties:

  • id: The app ID, for example "ari:cloud:ecosystem::app/80b358f5-d4a1-4258-9c90-31a9df65d874" (String).
  • license: Status of the app license on this Jira instance. If the license status is not available, this returns null (License).
  • properties: The app properties (EntityProperties).

Connect apps have access to the following properties:

License

  • active: Indicates if the license is active on this instance (Boolean).

Sprint

  • id: The sprint ID (Number).
  • state: The state of the sprint (String: 'future', 'active', 'closed').
  • name: The sprint name (String).
  • goal: The sprint goal (String).
  • startDate: When the sprint started (Date).
  • endDate: When the sprint is planned to end (Date).
  • completeDate: The actual date of ending the sprint (Date).
  • properties: The sprint properties (EntityProperties).

Board

  • id: The board ID (Number).
  • N hasBacklog: true if this board can have a backlog, false otherwise (Boolean). For example, classic Kanban boards don't have backlogs, and SCRUM boards do.
  • N hasSprints: true if this board supports sprints, false otherwise (Boolean). For example, Kanban boards don't have sprints, and SCRUM boards do.
  • N activeSprints: The list of all active sprints on this board (List<Sprint>).
  • N futureSprints: The list of all planned sprints on this board (List<Sprint>).
  • N closedSprints: The list of all completed sprints on this board (List<Sprint>).
  • N canAdminister: true if the current user has permissions to administer this board, false otherwise (Boolean).
  • properties: The board properties (EntityProperties).

ServiceDesk

  • id: The service desk ID (Number).
  • N project: The Jira project this service desk is based on (Project).

CustomerRequest

CustomerRequestStatus

  • name: The name of this status (String).
  • category: The category of this status (String: 'new', 'indeterminate', 'done', 'undefined').
  • date: The time when this status was set (Date).

CustomerRequestType

  • id: The ID of this request type (Number).

Transition

Type of the transition context variable, available in Jira expressions used to implement workflow conditions and validators. It contains information about the transition that is currently happening and allows to inspect the source and target status.

  • id: The transition ID (Number).
  • name: The transition name (String).
  • from: The current status of the issue (IssueStatus).
  • to: The target status of the transition (IssueStatus).
  • hasScreen: true if there is a screen configured for this transition, false otherwise (Boolean).

EntityProperties

This object can be thought of as a map of all properties, indexed by their keys.

There are a few ways to interact with this map. It is possible to:

  • 1 Get the value of a property using static member access. For example, issue.properties.myProperty.
  • 1 Get the value of a property using computed member access. For example, issue.properties['myProperty'].
  • 1 Get the value of a property using the get() method. For example, issue.properties.get('myProperty').
  • N Get a list of keys of all available properties using the keys() method. For example, issue.properties.keys().

Apart from static and computed member access, the following methods are available:

  • 1 get(string): Returns the property with the given key.
  • N keys(): Returns the keys of all properties (List<String>).
  • 1 updated(): Returns the last time any property was updated, or null if there are no properties (Date).
  • 1 updated(string): Returns the last time the property with the given key was updated, or null if the property does not exist (Date).

Accessing a property that is not defined will return null. Properties that are JSON objects are returned as Maps, other values can be returned as List, Boolean, String, or Number, depending on the actual type stored in the property.

UserPermissions

This is a step-through object that enables access to users' permissions.

Properties
Examples
  • To get your global permissions, write: user.permissions.global.
  • To get another user's global permissions, write: new User(accountId).permissions.global.

Error

The type used for errors that can be thrown at runtime by the Jira expressions interpreter. See runtime error handling for more details.

Properties
  • message: The error message that explains what went wrong (String).
  • location: The part of the expression where the error happened. Not available if an error was thrown by the expression itself with the throw keyword (String).

Date

This object is based on the JavaScript Date API.

Read more about dates and times in Jira expressions in the general documentation.

Jira expressions provide these additional methods:

  • toString(): Returns a string in the human-readable format, according to the current user's locale and timezone (String).
  • toCalendarDate(): Transforms this into a calendar date, according to the current user's locale and timezone (CalendarDate).
  • toCalendarDateUTC(): Transforms this into a calendar date in the UTC timezone (CalendarDate).
  • plusMonths(number): Returns a date with the given number of months added (Date).
  • minusMonths(number): Returns a date with the given number of months removed (Date).
  • plusDays(number): Returns a date with the given number of days added (Date).
  • minusDays(number): Returns a date with the given number of days removed (Date).
  • plusHours(number): Returns a date with the given number of hours added (Date).
  • minusHours(number): Returns a date with the given number of hours removed (Date).
  • plusMinutes(number): Returns a date with the given number of minutes added (Date).
  • minusMinutes(number): Returns a date with the given number of minutes removed (Date).

Constructors

  • new Date(): Creates a date that represents the current time.
  • new Date(number): Creates a date based on a number of milliseconds that elapsed since the Unix epoch.
  • new Date(string): Creates a date based on a string in the ISO 8601 format (for example, 2008-09-15T15:53:00+05:00). The current user's timezone is used if none is included in the string.

CalendarDate

A time-zone agnostic Date with the same set of methods, but limited only to year, month, and day.

Constructors

  • new CalendarDate(string): Creates a calendar date based on a string in the yyyy-MM-dd format. For example, 2008-09-15.

List

Lists are a basic building block of Jira expressions. By design, the language does not support imperative constructs, so instead of writing loops, you need to employ the functional style of processing lists with lambda functions.

For example, to return the number of comments with contents longer than 100 characters, first map the comments to their texts, then filter them to leave only those long enough, and finally get the length of the resulting list:

1
2
issue.comments                              
     .map(c => c.body.plainText)         
     .filter(text => text.length > 100)  
     .length                             

The following properties and methods are available for lists:

  • length: Returns the number of items stored in the list (Number).
  • map(Any => Any): Maps all items in the list to the result of the provided function (List).
  • sort((Any, Any) => Number): Returns the list sorted by the natural ordering of elements or by the optional comparison function. The comparison function accepts two items from the list and returns a negative number if the first argument should go first, or a positive number otherwise. For example, to sort a list of issues by keys, write: issues.sort((i1,i2) => i1.key < i2.key ? -1 : 1) (List).
  • filter(Any => Any): Leaves only items that satisfy the predicate (List).
  • every(Any => Any): Checks if all elements in the list satisfy the predicate (Boolean).
  • some(Any => Any): Checks if the list contains at least one element that satisfies the predicate (Boolean).
  • includes(Any): Checks if the given argument is stored in the list (Boolean).
  • indexOf(Any) Returns the index of the first occurrence of the item in the list, or -1 (Number).
  • slice(Number, Number?): Returns a portion of the list, with the index starting from the first argument (inclusive), and ending with the second one (exclusive). The second argument is optional, if not provided, all remaining elements will be returned. Negative numbers are allowed and mean indexes counted from the end of the list (List).
  • flatten(): Flattens a multi-dimensional list (List).
  • flatMap(Any => Any): Maps all items in the list and flattens the result (List).
  • concat(Any): Returns a new list, consisting of all elements of this list with the argument appended to the end. If the argument is a list: return a concatenation of the two lists (List).
  • reduce((Any, Any) => Any, Any?): Aggregates all elements of the list using the function provided in the first argument. The operation starts from the first element of the list, unless the initial value is provided in the optional second argument. If the list is empty and no initial value is given, an error will be returned (List).
  • join(String?): Converts all items in the list to strings and concatenates them separated by the first argument (, by default). If the resulting string exceeds 10,000 characters, it is trimmed and terminated with .... (String).

Predicates accepted by functions such as filter or every do not have to return a (Boolean) value. Any value returned by the predicate will be coerced to true or false in accordance to JavaScript rules.

Map

If the returned property value is a JSON object, it will be converted to a Map.

  • Static or dynamic member access can be used to retrieve values from a map. For example, map.key is the same as map['key'].
  • Values can also be accessed using the get() method. For example, map.get('key').
  • Both of these methods will return null if there is no mapping for the given key.

To create a new map, write new Map(). Object literals are also evaluated to the Map object. For example, { id: issue.id, summary: issue.summary } will evaluate to a map with two keys: id and summary.

Apart from static and computed member access, the following methods are available for maps:

  • get(string): Returns the value mapped to the given key, or null (Any).
  • set(string, Any): Returns a new map that has all entries from the current map, plus the first argument mapped to the second (Map).
  • entries(): Returns a list of all entries in this map, each entry returned as a two-element list of key and value (List<[String, Any]>).

Constructors

  • new Map(): Creates an empty map. Equivalent to {}.

String

Strings are based on the JavaScript String object.

These properties and methods are available:

  • length: The string length (Number).
  • trim(): Removes whitespaces from beginning and end (String).
  • padStart(number, string?): Prepends the string or, if no string is provided, the space character (“ “)—multiple times, if needed—to the number of characters requested. The resulting string has a maximum length of 100 characters. For example, "abc".padStart(5) results in the string " abc (String).
  • padEnd(number, string?): Appends the string or, if no string is provided, the space character (“ “)—multiple times, if needed—to the number of characters requested. The resulting string has a maximum length of 100 characters. For example, "abc".padEnd(5) results in the string "abc " (String).
  • toLowerCase(): Returns the string with all characters in lowercase (String).
  • toUpperCase(): Returns the string with all characters in uppercase (String).
  • split(string?): Splits the string at each occurrence of the separator (List<String>).
  • repeat(number): Creates a string containing the specified number of copies of the original string, concatenated together. A maximum of 100 repetitions of the string can be included (String).
  • replace(string, string|string=>string): Replaces all occurrences of a regular expression given in the first argument with the second argument, which can also be a function that accepts the matched part (String).
  • match(string): Finds the first match of the regular expression in the string and returns the match along with all capturing groups from the regular expression (List<String>).
  • matchAll(string): Finds all matches of the regular expression in the string and returns the matches along with all capturing groups from the regular expression (List<List<String>>).
  • includes(string): Returns true if this string contains the given string, false otherwise (Boolean).
  • indexOf(string): Returns the index of the first occurrence of the given string in this string, or -1 (Number).
  • slice(number, number?): Returns a substring of this string, according to the given arguments (String).

Template literals

Temperate literals are used to embed expressions inside strings. To create a template literal, wrap your text in backtick characters and insert expressions by starting them with ${ and ending with }. Each expression is evaluated, converted into a string, and the expression replaced with the result.

For example, this template literal creates a string that describes how many comments an issue has:

1
2
`Issue ${issue.key} has ${issue.comments.length} comments.`

Assuming the issue key is ATL-1 and the issue has 4 comments, the result is:

1
2
"Issue ATL-1 has 4 comments."

Nested template literals are not supported. That is, it's not possible to use template literals in an embedded expression.

Number

All numbers in Jira expressions are double-precision 64-bit IEEE 754 floating points. The usual set of mathematical operations is available.

Strings can be cast to numbers with the Number function. For example:

1
2
Number('1') + Number('2') == 3

Note that if a string cannot be parsed as number, the function returns NaN (Not a Number).

Boolean

There are two boolean values: true and false.

The usual set of logical operators, with behavior following the rules of classical boolean algebra, is available:

  • conjunction (for example, a && b),
  • disjunction (for example, a || b),
  • negation (for example, !a).

Rate this page: