Browse this sectionMiscellaneous / Expression functions

Expression functions

Expressions calculate the values a report shows: the text of a header, the value of a column, whether a row is shown, the JQL of a datasource and more. A property that starts with = is an expression, such as =Concat(Field.key, " - ", Field.summary).

This page lists every function of the Report Builder of Jira Assistant 3, available in the Jira Cloud app. The same list is inside the Report Builder: open the Functions panel on the left, or select the book button in any expression field to search the functions and insert one where you are typing. While you type a function, the field shows its parameters and marks the one you are on. Function names are not case sensitive.

Aggregate · Logic · Text · Number · Formatting · Date · List · Row · Conversion · Jira · Your preferences · Time tracking

Writing an expression

Values you can use
WriteTo get
Field.nameA field of the current row. Nested fields use dots, such as Field.status.name.
Parameters.nameThe value the viewer chose for a report parameter.
Variables.nameThe current value of a report variable.
BuiltInFields.nameA value given by the application, such as the signed-in user.
Datasources.NameEvery row of a datasource, for use with functions such as Sum or Count.
Datasources.Name.fieldThe values of one field across every row of a datasource.
RowGroup("name").keyInside a table group: the group value. Use .values for its rows.
Operators
OperatorMeaning
+ - * /Arithmetic. + also joins texts.
== != < > <= >=Comparison. Gives true or false.
&& || !And, or, not.
"text" 'text'A text value, in double or single quotes.
true false nullFixed values.
Parameter types
TypeAccepts
stringText.
numberA number.
booleantrue or false.
dateA date, or a text such as 2026-11-22 or 2026-11-22T10:30:00Z.
arrayA list of values.
rowsA list of rows, such as Datasources.Name or RowGroup("name").values.
anyAny kind of value.

Aggregate

Sum(values: array, field?: string) → number

Adds up the numbers in a list. Values that are not numbers are skipped.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • Sum(Datasources.Worklogs, "hours")
  • Sum(RowGroup("project").values, "hours")
  • Sum(Split("1,2,3", ",")) gives 6
Count(values: array, field?: string) → number

Number of items in a list. With a field, only the rows where that field has a value are counted.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • Count(RowGroup("status").values)
  • Count(Datasources.Issues, "assignee")
  • Count(Split("a,b", ",")) gives 2
CountDistinct(values: array, field?: string) → number

Number of different values in a list. Empty values are not counted.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • CountDistinct(Datasources.Issues, "assignee.displayName")
  • CountDistinct(Split("a,b,a", ",")) gives 2
Avg(values: array, field?: string) → number

Average of the numbers in a list. Gives 0 when there are no numbers.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • Avg(Datasources.Issues, "storyPoints")
  • Avg(Split("2,4,9", ",")) gives 5
Median(values: array, field?: string) → number

Middle value of the numbers in a list. Gives 0 when there are no numbers.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • Median(Pluck(Datasources.Issues, "storyPoints"))
  • Median(Split("1,5,9", ",")) gives 5
Min(values: array, field?: string) → number

Smallest number in a list. Gives 0 when there are no numbers.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • Min(Datasources.Worklogs, "hours")
  • Min(Split("4,2,8", ",")) gives 2
Max(values: array, field?: string) → number

Largest number in a list. Gives 0 when there are no numbers.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: number

Examples
  • Max(Datasources.Worklogs, "hours")
  • Max(Split("4,2,8", ",")) gives 8
Percent(part: number, total: number, decimals?: number) → number

Part as a percentage of the total, rounded. Gives 0 when the total is 0.

ParameterTypeDescription
partnumberThe share to measure.
totalnumberThe whole the part belongs to.
decimalsnumberoptionalNumber of digits after the decimal point, from 0 to 10. Default 0.

Returns: number

Examples
  • Percent(3, 8, 1) gives 37.5

Logic

IIf(condition: boolean, trueValue: any, falseValue: any) → any

Gives one value when the condition is true and another when it is false.

ParameterTypeDescription
conditionbooleanThe test to check.
trueValueanyGiven when the condition is true.
falseValueanyGiven when the condition is false.

Returns: any

Examples
  • IIf(Field.hours > 8, "Overtime", "Normal")
  • IIf(3 > 2, "yes", "no") gives yes
Switch(value: any, ...caseAndResult: any[]) → any

Compares a value with each case in turn and gives the result paired with the first case that matches. A last unpaired argument is the result when nothing matches; without it the result is null.

ParameterTypeDescription
valueanyThe value to compare.
...caseAndResultanyany numberPairs of a case and its result, then an optional fallback.

Returns: any

Examples
  • Switch(Field.priority.name, "Highest", 1, "High", 2, 3)
  • Switch("High", "Highest", 1, "High", 2, 3) gives 2
Coalesce(...values: any[]) → any

First argument that is not null. Gives null when all of them are null.

ParameterTypeDescription
...valuesanyany numberValues to try in order.

Returns: any

Examples
  • Coalesce(Field.assignee.displayName, Field.reporter.displayName, "Nobody")
  • Coalesce(null, "second") gives second
IfNull(value: any, fallback: any) → any

Gives the fallback when the value is null, otherwise the value itself.

ParameterTypeDescription
valueanyThe value to check.
fallbackanyGiven when the value is null.

Returns: any

Examples
  • IfNull(Field.storyPoints, 0)
  • IfNull(null, 0) gives 0
IsNull(value: any) → boolean

True when the value is null or missing.

ParameterTypeDescription
valueanyThe value to check.

Returns: boolean

Examples
  • IsNull(Variables.selectedStatus)
  • IsNull(null) gives true
IsEmpty(value: any) → boolean

True when the value is null, an empty text or an empty list.

ParameterTypeDescription
valueanyThe value to check.

Returns: boolean

Examples
  • IsEmpty(Parameters.projects)
  • IsEmpty("") gives true
InList(value: any, list: array) → boolean

True when the value is one of the items in the list. Items are also compared as text, so 5 matches "5".

ParameterTypeDescription
valueanyThe value to look for.
listarrayThe list to look in.

Returns: boolean

Examples
  • InList(Field.status.name, Split("Done,Closed", ","))
  • InList("b", Split("a,b", ",")) gives true
Between(value: any, min: any, max: any) → boolean

True when the value lies between min and max, both included. Numbers are compared as numbers and everything else as text, which also works for yyyy-MM-dd dates.

ParameterTypeDescription
valueanyThe value to check.
minanyLowest allowed value.
maxanyHighest allowed value.

Returns: boolean

Examples
  • Between(Field.date, StartOf("month", Today()), EndOf("month", Today()))
  • Between(5, 1, 10) gives true
Not(value: boolean) → boolean

Turns true into false and false into true. The same as writing ! before a value.

ParameterTypeDescription
valuebooleanThe value to negate.

Returns: boolean

Examples
  • Not(IsEmpty(Field.labels))
  • Not(1 > 2) gives true
Any(values: array) → boolean

True when the list has at least one item.

ParameterTypeDescription
valuesarrayThe list to check.

Returns: boolean

Examples
  • Any(Field.labels)
  • Any(Split("a", ",")) gives true
All(values: array) → boolean

True when the list has items and every item is truthy.

ParameterTypeDescription
valuesarrayThe list to check.

Returns: boolean

Examples
  • All(Pluck(Datasources.Checks, "passed"))
  • All(Split("a,b", ",")) gives true

Text

Concat(...values: any[]) → string

Joins all the arguments into one text.

ParameterTypeDescription
...valuesanyany numberValues to join, in order.

Returns: string

Examples
  • Concat(Field.key, " - ", Field.summary)
  • Concat("JSP", "-", 12) gives JSP-12
Upper(value: string) → string

The text in capital letters.

ParameterTypeDescription
valuestringThe text to change.

Returns: string

Examples
  • Upper("done") gives DONE
Lower(value: string) → string

The text in small letters.

ParameterTypeDescription
valuestringThe text to change.

Returns: string

Examples
  • Lower("DONE") gives done
Trim(value: string) → string

The text without spaces at the start and end.

ParameterTypeDescription
valuestringThe text to trim.

Returns: string

Examples
  • Trim(" done ") gives done
Len(value: string) → number

Number of characters in the text.

ParameterTypeDescription
valuestringThe text to measure.

Returns: number

Examples
  • Len("Sprint") gives 6
Length(value: any) → number

Number of items in a list, or number of characters in a text. Gives 0 for null.

ParameterTypeDescription
valueanyA list or a text.

Returns: number

Examples
  • Length(Field.labels)
  • Length(Split("a,b,c", ",")) gives 3
Mid(value: string, start: number, length: number) → string

Part of the text, starting at a position counted from 1.

ParameterTypeDescription
valuestringThe text to take from.
startnumberPosition of the first character to take. The first character is 1.
lengthnumberNumber of characters to take.

Returns: string

Examples
  • Mid("JSP-123", 5, 3) gives 123
Replace(value: string, find: string, replaceWith: string) → string

The text with every occurrence of find replaced.

ParameterTypeDescription
valuestringThe text to change.
findstringThe text to look for.
replaceWithstringThe text to put in its place.

Returns: string

Examples
  • Replace("In Progress", " ", "-") gives In-Progress
StartsWith(value: string, prefix: string) → boolean

True when the text starts with the prefix. Letter case matters.

ParameterTypeDescription
valuestringThe text to check.
prefixstringThe start to look for.

Returns: boolean

Examples
  • StartsWith(Field.key, "JSP-")
  • StartsWith("JSP-12", "JSP") gives true
EndsWith(value: string, suffix: string) → boolean

True when the text ends with the suffix. Letter case matters.

ParameterTypeDescription
valuestringThe text to check.
suffixstringThe end to look for.

Returns: boolean

Examples
  • EndsWith(Field.summary, "?")
  • EndsWith("Ready?", "?") gives true
Contains(value: string, search: string) → boolean

True when the text contains the other text. Letter case matters.

ParameterTypeDescription
valuestringThe text to search.
searchstringThe text to look for.

Returns: boolean

Examples
  • Contains(Lower(Field.summary), "login")
  • Contains("login page", "login") gives true
PadLeft(value: any, length: number, char?: string) → string

The value as text, filled on the left up to the given length.

ParameterTypeDescription
valueanyThe value to pad.
lengthnumberLength of the result.
charstringoptionalCharacter to fill with. Default " ".

Returns: string

Examples
  • PadLeft(7, 3, "0") gives 007
PadRight(value: any, length: number, char?: string) → string

The value as text, filled on the right up to the given length.

ParameterTypeDescription
valueanyThe value to pad.
lengthnumberLength of the result.
charstringoptionalCharacter to fill with. Default " ".

Returns: string

Examples
  • PadRight("A", 3, ".") gives A..
Split(value: string, separator?: string) → array

Splits a text into a list. Gives an empty list for an empty text.

ParameterTypeDescription
valuestringThe text to split.
separatorstringoptionalThe text between the parts. Default ",".

Returns: array The parts of the text.

Examples
  • Split("a,b,c", ",") gives ["a", "b", "c"]
Join(values: array, separator?: string) → string

Joins the items of a list into one text. Null items are skipped.

ParameterTypeDescription
valuesarrayThe list to join.
separatorstringoptionalText put between the items. Default ", ".

Returns: string

Examples
  • Join(Field.labels, " | ")
  • Join(Split("a,b", ","), " | ") gives a | b

Number

Round(value: number, decimals?: number) → number

The number rounded to the given number of decimals.

ParameterTypeDescription
valuenumberThe number to round.
decimalsnumberoptionalNumber of digits to keep after the decimal point. Default 0.

Returns: number

Examples
  • Round(2.456, 2) gives 2.46
Floor(value: number) → number

The number rounded down to a whole number.

ParameterTypeDescription
valuenumberThe number to round.

Returns: number

Examples
  • Floor(2.9) gives 2
Ceil(value: number) → number

The number rounded up to a whole number.

ParameterTypeDescription
valuenumberThe number to round.

Returns: number

Examples
  • Ceil(2.1) gives 3
Abs(value: number) → number

The number without its minus sign.

ParameterTypeDescription
valuenumberThe number.

Returns: number

Examples
  • Abs(-4) gives 4

Formatting

FormatNumber(value: number, decimals?: number, thousandsSeparator?: string) → string

The number as text with a fixed number of decimals and a thousands separator. Gives an empty text when the value is not a number.

ParameterTypeDescription
valuenumberThe number to format.
decimalsnumberoptionalNumber of digits after the decimal point, from 0 to 10. Default 2.
thousandsSeparatorstringoptionalText put between groups of thousands. Default ",".

Returns: string

Examples
  • FormatNumber(1234.5) gives 1,234.50
  • FormatNumber(Field.hours, 1)
FormatCurrency(value: number, symbol?: string, decimals?: number) → string

The number as an amount of money.

ParameterTypeDescription
valuenumberThe amount.
symbolstringoptionalCurrency symbol put in front. Default "$".
decimalsnumberoptionalNumber of digits after the decimal point, from 0 to 10. Default 2.

Returns: string

Examples
  • FormatCurrency(1500, "€") gives €1,500.00
FormatPercent(value: number, decimals?: number) → string

A fraction as a percentage, so 0.25 becomes 25%.

ParameterTypeDescription
valuenumberThe fraction, where 1 is 100%.
decimalsnumberoptionalNumber of digits after the decimal point, from 0 to 10. Default 0.

Returns: string

Examples
  • FormatPercent(0.256, 1) gives 25.6%
FormatDate(date: date, format?: string) → string

The date as text in the given pattern. Patterns use yyyy, yy, MMMM, MMM, MM, M, dddd, ddd, dd, d, HH, H, hh, h, mm, ss and a.

ParameterTypeDescription
datedateA date, a yyyy-MM-dd text or a date and time text.
formatstringoptionalThe pattern to write the date in. Default "yyyy-MM-dd".

Returns: string

Examples
  • FormatDate("2026-11-22", "dd MMM yyyy") gives 22 Nov 2026

Date

Today() → string

Today's date in your time zone.

Takes no parameters.

Returns: string The date as yyyy-MM-dd.

Examples
  • Today()
Now() → string

The current date and time.

Takes no parameters.

Returns: string The date and time as an ISO text in UTC.

Examples
  • FormatDate(Now(), "HH:mm")
DateAdd(unit: string, amount: number, date: date) → string

The date moved forward by an amount of time. Use a negative amount to move back. A yyyy-MM-dd date stays yyyy-MM-dd unless hours are added.

ParameterTypeDescription
unitstringOne of "day" (d), "week" (w), "month" (m), "year" (y) or "hour" (h).
amountnumberHow many units to add.
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: string

Examples
  • DateAdd("day", 7, Today())
  • DateAdd("month", 1, "2026-01-15") gives 2026-02-15
DateDiff(unit: string, from: date, to: date) → number

Time from the first date to the second, in whole units. Days count calendar days. Gives null when a date is not valid.

ParameterTypeDescription
unitstringOne of "day" (d), "week" (w), "month" (m), "year" (y), "hour" (h) or "minute" (mi). Any other unit gives milliseconds.
fromdateThe start date.
todateThe end date.

Returns: number

Examples
  • DateDiff("day", Field.created, Today())
  • DateDiff("day", "2026-11-01", "2026-11-22") gives 21
StartOf(unit: string, date: date) → string

First day of the week, month, quarter or year the date is in.

ParameterTypeDescription
unitstringOne of "week" (w), "month" (m), "quarter" (q) or "year" (y). Weeks start on Sunday.
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: string The date as yyyy-MM-dd.

Examples
  • StartOf("month", "2026-11-22") gives 2026-11-01
EndOf(unit: string, date: date) → string

Last day of the week, month, quarter or year the date is in.

ParameterTypeDescription
unitstringOne of "week" (w), "month" (m), "quarter" (q) or "year" (y). Weeks start on Sunday.
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: string The date as yyyy-MM-dd.

Examples
  • EndOf("quarter", "2026-11-22") gives 2026-12-31
Year(date: date) → number

The year of the date. Gives 0 when the date is not valid.

ParameterTypeDescription
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: number

Examples
  • Year("2026-11-22") gives 2026
Month(date: date) → number

The month of the date, from 1 for January to 12. Gives 0 when the date is not valid.

ParameterTypeDescription
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: number

Examples
  • Month("2026-11-22") gives 11
Day(date: date) → number

The day of the month, from 1 to 31. Gives 0 when the date is not valid.

ParameterTypeDescription
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: number

Examples
  • Day("2026-11-22") gives 22
WeekDay(date: date) → number

The day of the week, from 0 for Sunday to 6 for Saturday.

ParameterTypeDescription
datedateA date, a yyyy-MM-dd text or a date and time text.

Returns: number

Examples
  • WeekDay("2026-11-22") gives 0

List

Pluck(rows: rows, field: string) → array

The value of one field from every row.

ParameterTypeDescription
rowsrowsThe rows to read.
fieldstringThe field to read from each row. Nested paths are allowed.

Returns: array One value for each row.

Examples
  • Pluck(Datasources.Issues, "key")
Distinct(values: array, field?: string) → array

The different values of a list in the order they first appear. Null values are left out.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: array Each value once.

Examples
  • Join(Distinct(Datasources.Issues, "status.name"))
  • Join(Distinct(Split("a,b,a", ","))) gives a, b
First(values: array, field?: string) → any

The first item of a list. Gives null for an empty list.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: any

Examples
  • First(RowGroup("project").values, "project.name")
  • First(Split("a,b", ",")) gives a
Last(values: array, field?: string) → any

The last item of a list. Gives null for an empty list.

ParameterTypeDescription
valuesarrayA list of values, or a list of rows such as a datasource or the rows of a group.
fieldstringoptionalWhen values is a list of rows, the field to read from each row. Nested paths such as "fields.status.name" are allowed.

Returns: any

Examples
  • Last(Datasources.Sprints, "name")
  • Last(Split("a,b", ",")) gives b

Row

Field(path: string) → any

Reads a field of the current row by its path. Useful when the path contains characters Field.name cannot hold. Gives null outside a row.

ParameterTypeDescription
pathstringThe path of the field, with nested parts separated by dots.

Returns: any

Examples
  • Field("fields.customfield_10016")

Conversion

ToString(value: any) → string

The value as text. Null becomes an empty text.

ParameterTypeDescription
valueanyThe value to convert.

Returns: string

Examples
  • Concat("Sprint ", ToString(Field.id))
  • ToString(12) gives 12
ToNumber(value: any) → number

The value as a number.

ParameterTypeDescription
valueanyThe value to convert.

Returns: number

Examples
  • ToNumber("12.5") gives 12.5

Jira

IssueUrl(key: string) → string

Address of the issue in Jira. Gives an empty text when there is no key.

ParameterTypeDescription
keystringThe issue key, such as JSP-12.

Returns: string

Examples
  • IssueUrl(Field.key)
ProfileUrl(user: any) → string

Address of the Jira profile page of a user.

ParameterTypeDescription
useranyA user, such as Field.assignee.

Returns: string

Examples
  • ProfileUrl(Field.assignee)
GroupUsers(groupNames: any) → array

The members of the user groups you created in Jira Assistant.

ParameterTypeDescription
groupNamesanyA group name or a list of them, such as the value of a User groups parameter.

Returns: array The users of every group named. It loads data, so it can take a moment to give its result.

Examples
  • UserIds(GroupUsers(Parameters.teams))
UserIds(users: any) → array

Account ids of users, or user names on Jira Server and Data Center. The members of a user group are included.

ParameterTypeDescription
usersanyA user, a user group or a list of them, such as the value of a Users parameter.

Returns: array Each id once.

Examples
  • JqlList(UserIds(Parameters.users))
SprintIds(sprints: any) → array

Ids of the sprints chosen in a Sprints parameter.

ParameterTypeDescription
sprintsanyThe value of a Sprints parameter.

Returns: array The sprint ids. It loads data, so it can take a moment to give its result.

Examples
  • Join(SprintIds(Parameters.sprints), ",")
JqlList(values: any) → string

Values quoted and separated by commas, ready to put in a JQL query.

ParameterTypeDescription
valuesanyA value or a list of values.

Returns: string

Examples
  • Concat("project in (", JqlList(Parameters.projects), ")")

Your preferences

FormatUserDate(date: date) → string

The date in the date format chosen in your settings. Gives an empty text when there is no date.

ParameterTypeDescription
datedateThe date to show.

Returns: string

Examples
  • FormatUserDate(Field.created)
  • FormatUserDate(Today())
FormatUserDateTime(date: date) → string

The date and time in the formats chosen in your settings.

ParameterTypeDescription
datedateThe date and time to show.

Returns: string

Examples
  • FormatUserDateTime(Field.updated)
FormatUserTime(date: date) → string

The time of day in the time format chosen in your settings.

ParameterTypeDescription
datedateThe date and time to take the time from.

Returns: string

Examples
  • FormatUserTime(Field.started)
IsHoliday(date: date) → boolean

True when the date is not one of the working days chosen in your settings.

ParameterTypeDescription
datedateThe date to check.

Returns: boolean

Examples
  • IsHoliday(Field.date)
WorkingDays(from: date, to: date) → number

Number of your working days from one date to another, both included. Gives 0 when from is after to.

ParameterTypeDescription
fromdateThe first date.
todateThe last date.

Returns: number

Examples
  • WorkingDays(Today(), Field.duedate)

Time tracking

Hours(seconds: number, decimals?: number) → number

Seconds, such as time spent or an estimate, as hours.

ParameterTypeDescription
secondsnumberThe time in seconds.
decimalsnumberoptionalNumber of digits after the decimal point, from 0 to 6. Default 2.

Returns: number

Examples
  • Hours(5400) gives 1.5
  • Hours(Field.timeSpentSeconds, 1)
FormatDuration(seconds: number) → string

Seconds as hours and minutes.

ParameterTypeDescription
secondsnumberThe time in seconds.

Returns: string

Examples
  • FormatDuration(27000) gives 7:30