Functions

External Data for Jira Fields offers various functions you can use to transform values that you want to use in your Field Configurations.

DECODE_HTML

The DECODE_HTML function is used to decode HTML encoded strings for a given JSONPath.

Usable: Value Fields, Context Filter, Variables

Syntax: { DECODE_HTML((PARAM_1)) }

Value Field Example

For example, consider the following data source JSON:

{
  "value": "100 €"
}

Use the DECODE_HTML function to decode all HTML encoded elements

{ DECODE_HTML(($.value)) }

This will result in 100 €

FORMAT_DATE

The FORMAT_DATE function is used to format a date time value.

Usable: Value Fields, Variables

Syntax: { FORMAT_DATE(( PARAM_1 PARAM_2 PARAM_3 )) }

Value Field Example

For example, consider the following data source JSON:

{
  "value": "2020-09-01T22:05:45.488+02:00"
}

Use the FORMAT_DATE function to format the value to a date string

{ FORMAT_DATE(( $.value 'g' 'de-DE' )) }

This will result in 01.09.2020 20:05

Format and Culture Examples

GET_ACCOUNT_ID_BY_MAIL

The GET_ACCOUNT_ID_BY_MAIL function converts an email address extracted from a JSON data source into an Atlassian accountID. It uses a JSONPath expression to locate the email in your data, and then queries the Atlassian system to return the corresponding accountID.

Usable in: Value Fields, Variables

Syntax: { GET_ACCOUNT_ID_BY_MAIL(( PARAM_1 PARAM_2 )) }

Note: The “PARAM_2” parameter was introduced to address scenarios where multiple accounts may share the same email address. By default, the function returns the first account that matches the search criteria. In the event that several accounts exist, please enter PARAM_2 to ensure that the function selects the correct account type.

Value Field Example

Assume the following example JSON data source:

{
  "name": "Mario",
  "email": "test@test.com"
}

Basic Conversion:
Convert the email to an accountID without specifying an account type will return the first match:

{ GET_ACCOUNT_ID_BY_MAIL(( $.email )) }

Returns an accountID, for example, '12345678910'.

Filter for an Atlassian account:

Use the GET_ACCOUNT_ID_BY_MAIL in combination with the 'atlassian' filter to convert the email to an accountID with the account type being atlassian.

{ GET_ACCOUNT_ID_BY_MAIL(( $.email 'atlassian' )) }

Returns the accountID associated with the Atlassian account type, for example, '12345678910'.

User Picker Usage

The GET_ACCOUNT_ID_BY_MAIL function is commonly used in combination with a dependent field targeting a native Jira user picker field. In order to set the value of the user picker field, the accountID is required, which may not be readily available in your data source. This function helps you convert existing emails to the required accountID, making it easier to set the value of the user picker field.

JOIN

The JOIN function is used to concatenate multiple strings with a specified delimiter in between for a given JSONPath array.

Usable: Value Fields, Context Filter, Variables

Syntax: { JOIN((PARAM_1 PARAM_2)) }

Value Field Example

For example, consider the following data source JSON:

{
  "result": [
    {
      "name": "Mario",
    },
    {
      "name": "Luigi",
    }
  ]
}

Use the JOIN function to concatenate the JSONPath names with the & symbol

{ JOIN(($.result[*].name '&')) }

This will result in Mario & Luigi

Context Filter Example

Use the JOIN function to build part of a regular expression by concatenating the values with the pipe symbol

$.result[?(@.name=~/({ JOIN(( $.issue.fields.customfield_10XXX[*].value '|' )) })/i )]

If $.issue.fields.customfield__X contains a list of Mario and Luigi the expression will result in:

$.result[?(@.name=~/(Mario|Luigi)/i )]

OFFSET_FORMAT_DATE

The OFFSET_FORMAT_DATE function is used to set a timezone offset and then format a date time value.

Usable: Value Fields, Variables

Syntax: { OFFSET_FORMAT_DATE(( PARAM_1 PARAM_2 PARAM_3 PARAM_4 )) } }

Value Field Example

For example, consider the following data source JSON:

{
  "value": "2020-09-01T22:05:45.488+02:00"
}

To format the value to a date string with an offset of +8, use the OFFSET_FORMAT_DATE function to format the value to a date string

{ OFFSET_FORMAT_DATE(( $.time '+8' 'g' 'en-AU' )) }

This will result in 2/9/2020 4:05 am

Format and Culture Examples

QUOTED_JOIN

The QUOTED_JOIN function is used to concatenate multiple strings with a specified delimiter in between for a given JSONPath array. In addition all strings are surrounded by single quotes.

Usable: Value Fields, Context Filter, Variables

Syntax: { QUOTED_JOIN((PARAM_1 PARAM_2 PARAM_3)) }

Value Field Example

For example, consider the following data source JSON:

{
  "result": [
    {
      "name": "Mario",
    },
    {
      "name": "Luigi",
    }
  ]
}

Use the QUOTED_JOIN function to concatenate the JSONPath names with the & symbol

{ QUOTED_JOIN(($.result[*].name '&')) }

This will result in 'Mario' & 'Luigi'

Context Filter Example

Use the QUOTED_JOIN function to build part of a regular expression by concatenating the values with the pipe symbol

$.result[?(@.name=~/({ QUOTED_JOIN(( $.issue.fields.customfield_10XXX[*].value '|' )) })/i )]

If $.issue.fields.customfield__X contains a list of Mario and Luigi the expression will result in:

$.result[?(@.name=~/('Mario'|'Luigi')/i )]

REGEX_IN_ARRAY

The REGEX_IN_ARRAY function is used to build a regular expression pattern from an array of values to perform a context filter operation. The resulting regex pattern is in the form /(VALUE1|VALUE2|...)/i.

Usable: Context Filter, Variables

Syntax: { REGEX_IN_ARRAY(( PARAM_1 PARAM_2)) }

Matching Modes

The PARAM_2 values in the REGEX_IN_ARRAY function changes how the values in the array are matched and what options are added to the regular expression.

Context Filter Example

For example, consider the following data source JSON:

{
  "result": [
    {
      "id": 1,
      "group": "administrators",
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    .... more items here ....
  ]
}

To filter results based on whether the current user’s groups matches one of the values in the JSON array, use the following expression:

$.result[?(@.group=~{ REGEX_IN_ARRAY(( $.user.groups.items[*].name )) })]

If $.user.groups.items[*].name contains administrators and jira-core-users the expression will resolve to the regular expression

$.result[?(@.group=~/(administrators|jira-core-users)/i)]

 Same but with an array of groups in your data source

{
  "result": [
    {
      "id": 1,
      "groups": ["administrators","jira-servicedesk-users"],
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    .... more items here ....
  ]
}

$.result[?(@.group[?(@=~{ REGEX_IN_ARRAY(( $.user.groups.items[*].name )) })])]

If $.user.groups.items[*].name contains administrators and jira-core-users the expression will resolve to the regular expression

$.result[?(@.group[?(@=~/(administrators|jira-core-users)/i)])]

Mode Differences

Compare the resolved regular expression from the example above with all different modes and resolved anchors.

Default

$.result[?(@.group=~{ REGEX_IN_ARRAY(( $.user.groups.items[*].name )) })]

$.result[?(@.group=~/(administrators|jira-core-users)/i)]

FullMatch

$.result[?(@.group=~{ REGEX_IN_ARRAY(( $.user.groups.items[*].name 'fullMatch')) })]

$.result[?(@.group=~/^(administrators|jira-core-users)$/i)]

Exact

$.result[?(@.group=~{ REGEX_IN_ARRAY(( $.user.groups.items[*].name 'exact')) })]

$.result[?(@.group=~/^(administrators|jira-core-users)$/)]

Anchor Effects

Construct Regex with JOIN function

We use the method documented here to resolve the regex expression, but only support the options i, m, s, and x.

If the REGEX_IN_ARRAY function is constructing the expression in a way that is not feasible for your use case, you can use the JOIN function to construct an expression ‘manually’.

Instead of using $.result[?(@.group[?(@=~{ REGEX_IN_ARRAY(( $.user.groups.items[*].name )) })])] you can also use $.result[?(@.group[?(@=~/({ JOIN(( $.user.groups.items[*].name '|')) })/i)])]. This way, you are more flexible how to anchor or combine your expression.

REGEX_MATCH

The REGEX_MATCH function is used to match a regular expression pattern against a string content.

We use the method documented here to resolve the regex expression, but only support the options i, m, s, and x.

Usable: Value Fields, Context Filter, Variables

Syntax: { REGEX_MATCH((PARAM_1 PARAM_2)) }

Value Field Example

Extract all text up to the first whitespace:

{ REGEX_MATCH(($.value '^([^\s]*)')) }

If $.value contains '12345 (branch/name)' the result will be 12345.

Context Filter Example

For example, consider the following data source JSON:

{
  "result": [
    {
      "id": 1,
      "group": "administrators",
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    .... more items here ....
  ]
}

To filter results in which the id equals the custom field value of the issue until the first whitespace:

$.result[?(@.id=={ REGEX_MATCH(($.issue.fields.customfield_X '^([^\s]*)')) } )]

If the $.issue.fields.customfield__X field contains '1 (branch/name)' the resolved expression will be:

$.result[?(@.id==1)]

REGEX_GROUP_MATCH

The REGEX_GROUP_MATCH function is used to match a regular expression pattern against a string content and retrieve a specific declared group.

We use the method documented here to resolve the regex expression, but only support the options i, m, s, and x.

Usable: Value Fields, Context Filter, Variables

Syntax: { REGEX_GROUP_MATCH((PARAM_1 PARAM_2 PARAM_3)) }

Value Field Example

Get the value of the second group match

{ REGEX_GROUP_MATCH(($.value '^([^\s]*)' '2')) }

If $.value contains 'the name (7) (test)' the result will be test.

Context Filter Example

To filter results where the “id” equals the custom field value of the issue at the first quotes:

{ REGEX_GROUP_MATCH(($.issue.fields.customfield_X '\((\S*)\)' '1')) }

If the $.issue.fields.customfield__X field contains 'the name (7) (test)' the expression will resolve to:

$.result[?(@.id=='7')]

REGEX_REPLACE

The REGEX_REPLACE function is used to match a regular expression pattern against a string content and replace all matches with a given string.

We use the method documented here to resolve the regex expression, but only support the options i, m, s, and x.

Usable: Value Fields, Context Filter, Variables

Syntax: { REGEX_REPLACE((PARAM_1 PARAM_2 PARAM_3)) }

Value Field Example

Extract all text up to the first whitespace:

{ REGEX_REPLACE(($.value '[^a-zA-Z0-1 ]' '')) }

If $.value contains '[remove] all // unwanted {}'&^!@^&($ characters' the result will be remove all unwanted characters.

Context Filter Example

For example, consider the following data source JSON:

{
  "result": [
    {
      "id": 1,
      "group": "administrators",
      "name": "Mario Speedwagon",
      "username": "mario"
    },
    .... more items here ....
  ]
}

To filter results in which the id equals the custom field value of the issue until the first whitespace:

$.result[?(@.id=={ REGEX_REPLACE(($.issue.fields.customfield_X '[^0-1 ]' '')) } )]

If the $.issue.fields.customfield__X field contains '1 (branch/name)' the resolved expression will be:

$.result[?(@.id==1)]

because only numbers are allowed and other characters are removed

REPLACE

The REPLACE function is used to replace all occurrences of a specified string with another string in a given JSONPath value.

Usable: Value Fields, Context Filter, Variables

Syntax: { REPLACE((PARAM_1 PARAM_2 PARAM_3)) }

Value Field Example

Use the REPLACE function to replace all spaces in the JSONPath value with the pipe symbol

{ REPLACE(($.value ' ' '|')) }

If $.value contains 'This is a string' the result will be This|is|a|string.

Context Filter Example

Use the REPLACE function to replace all spaces in the JSONPath value with the pipe symbol

$.result[?(@.value=~/({ REPLACE(( $.issue.fields.customfield_10XXX ' ' '|' )) })/i )]

If $.issue.fields.customfield__X contains 'This is a string' the expression will be:

$.result[?(@.value=~/(This|is|a|string)/i )]

STRIP_HTML

The STRIP_HTML function is used to remove all HTML for a given JSONPath value.

Usable: Value Fields, Context Filter, Variables

Syntax: { STRIP_HTML((PARAM_1)) }

Value Field Example

For example, consider the following data source JSON:

{
  "value": "<p><b>title</b><br/>subtitle</p>"
}

Use the STRIP_HTML function remove all HTML elements and convert <br> tags into line breaks

{ STRIP_HTML(($.value)) }

This will result in title\nsubtitle.