Compatibility of Atlassian's New Transition Experience with Jira Expressions

Atlassian's new transition experience in Jira is being permanently rolled out in April 2025. As a consequence, how your Jira expressions (conditions and validators) work will change.

When working with Jira Cloud, it's important to understand that there are two types of rich text fields:

  • Pre-defined Atlassian fields: These are built-in fields like description and environment. They are RichText type and have a built-in plainText property for easy access to their text content.
  • Custom fields: These are fields created by customers. They are stored as simple Map objects and require additional processing to access their text content.

Understanding this distinction is crucial for correctly handling rich text content in your Jira scripts and expressions. You can refer to Atlassian's documentation for more details on Jira expression types.

REST API

Atlassian's new issue transition experience means that workflow functions will always use REST API v3 with Atlassian Document Format (ADF), replacing REST v2 API with Plain String format. This change primarily affects workflow validators and post functions.

Atlassian Pre-defined Fields (RichText type)

These fields, such as description and environment, are of RichText type and have a built-in plainText property. 

For pre-defined fields, always use .plainText directly.

Complex operations like checking for specific formatting or extracting links may require more advanced ADF parsing techniques. Remember you should always test your Jira expressions in your Jira environment to make sure they function as expected.

Access plain text content

Before Atlassian's new transition experience:

issue.description != ""
issue.environment != ""

After Atlassian's new transition experience:

issue.description.plainText != ""
issue.environment.plainText != ""

Check for specific content

Before Atlassian's new transition experience:

issue.description.toLowerCase().contains("urgent")
issue.environment.toLowerCase().contains("production")

After Atlassian's new transition experience:

issue.description.plainText.toLowerCase().includes("urgent")
issue.environment.plainText.toLowerCase().includes("production")

Count words

Before Atlassian's new transition experience:

issue.description.split(/\s+/).length > 50
issue.environment.split(/\s+/).length > 20

After Atlassian's new transition experience:

issue.description.plainText.split(/\s+/).length > 50
issue.environment.plainText.split(/\s+/).length > 20

Check for empty fields

Before Atlassian's new transition experience:

issue.description == ""
issue.environment == ""

After Atlassian's new transition experience:

issue.description.plainText == ""
issue.environment.plainText == ""

Concatenate multiple rich text fields

Before Atlassian's new transition experience:

issue.description + " " + issue.environment

After Atlassian's new transition experience:

issue.description.plainText + " " + issue.environment.plainText

Custom Fields (Map type)

For custom fields, always use the plainTextValue() function to extract the text content.  Custom fields require a helper function to extract plain text content, as shown below:

let plainTextValue = value => {
    if (value && typeof value == 'object' && !Array.isArray(value)) {
        return new RichText(value).plainText;
    }
    return value;
};


Complex operations like checking for specific formatting or extracting links may require more advanced ADF parsing techniques. Remember you should always test your Jira expressions in your Jira environment to make sure they function as expected.

Access plain text content

Before Atlassian's new transition experience:

issue.customfield_10234 != ""

After Atlassian's new transition experience:

plainTextValue(issue.customfield_10234) != ""

Check for specific content

Before Atlassian's new transition experience:

issue.customfield_10234.toLowerCase().contains("urgent")

After Atlassian's new transition experience:

plainTextValue(issue.customfield_10234).toLowerCase().includes("urgent")

Count words

Before Atlassian's new transition experience:

issue.customfield_10234.split(/\s+/).length > 50

After Atlassian's new transition experience:

plainTextValue(issue.customfield_10234).split(/\s+/).length > 50

Check for empty fields

Before Atlassian's new transition experience:

issue.customfield_10234 == ""

After Atlassian's new transition experience:

plainTextValue(issue.customfield_10234) == ""

Concatenate custom fields with pre-defined fields

Before Atlassian's new transition experience:

issue.description + " " + issue.customfield_10234

After Atlassian's new transition experience:

issue.description.plainText + " " + plainTextValue(issue.customfield_10234)
On this page