Workflow Validators and Conditions might break soon if you use custom Jira Expressions

[#1]

Sorry for the alarmist Article, but this feels kind of urgent.

Your Workflow Validators and Conditions might break if you use custom Jira Expressions to evaluate rich text fields.

Huge thanks for the heads-up from our friends at Adaptavist, who mailed their ScriptRunner for Jira Cloud customers about a potentially breaking change: Compatibility of Atlassian's New Transition Experience with Jira Expressions

So... in their rollout of the new Issue Transitions Experience, Atlassian has apparently decided that it wasn't enough to making people angry about changing the default for Comment Visibility and not supporting Assets. 

They also made a change that may break Workflow Validators and Conditions.

Per Adaptavist, this change will be permanently rolled out in April 2025. (Documented by Atlassian exactly nowhere I can find. :-{)

How this affects Workflow Validators and Conditions

• Have you have created any Validators or Conditions using custom Jira Expressions with any of these tools: Jira Workflow Toolbox, Jira Miscellaneous Workflow Extensions, Power Scripts, ScriptRunner, Cloud Workflows?

• Are any of your custom Jira Expressions checking for specific text (or whether there is no text) in multi-line (paragraph) fields like Description or other custom fields? Examples:

  • "Is the Description field empty?"

  • "Does the Description field include the word 'urgent' or 'production'?"

  • "Does the custom field "Justification" have at least 20 words?

• IF SO, when this change is permanently rolled out, your workflow validators or conditions WILL BREAK.

Basically Atlassian decided to change the APIs that workflow functions use, and you'll need to edit your workflows to fix this.

Adaptavist's article has tons of excellent examples, but just to give you an idea of what you'll need to change, here's a few of their examples:

Check if Description is empty:

Before Atlassian's new transition experience:

issue.description != ""

After Atlassian's new transition experience:

issue.description.plainText != ""

Check if Description has the word urgent:

Before Atlassian's new transition experience:

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

After Atlassian's new transition experience:

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

Count words in a Custom Field (multi-line):

Before Atlassian's new transition experience:

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

After Atlassian's new transition experience:

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

So... you may be asking yourself: "Hrm, this seems vaguely familiar, but the last time I set these workflows up was years ago. How in the world am I supposed to know which of my workflows contains these expressions that I need to fix?"

Welp. I can help you with that. Back in January @Kawan Diogo wrote a Python script to export all of your workflows as XML. I had to fix the indenting and change one URL to work with Jira Cloud, but it worked great. Thanks Kawan!

import requests
from requests.auth import HTTPBasicAuth

# Jira credentials and base URL
jira_url = "https://YOURSITE.atlassian.net"
username = "YOUREMAIL"
api_token = "YOURAPITOKEN"

# Get all workflows
workflows_endpoint = f"{jira_url}/rest/api/2/workflow"
response = requests.get(workflows_endpoint, auth=HTTPBasicAuth(username, api_token))

if response.status_code == 200:
    workflows = response.json()
    for workflow in workflows:
        workflow_name = workflow['name']
        print(f"Exporting workflow: {workflow_name}")

# Export workflow XML
        export_url = f"{jira_url}/secure/admin/workflows/ViewWorkflowXml.jspa?workflowMode=live&workflowName={workflow_name}"
        export_response = requests.get(export_url, auth=HTTPBasicAuth(username, api_token))

        if export_response.status_code == 200:
            with open(f"{workflow_name}.xml", "w") as file:
                file.write(export_response.text)
        else:
            print(f"Failed to export workflow: {workflow_name} - {export_response.status_code}")
else:
    print(f"Failed to fetch workflows: {response.status_code}")

So this script will dump all of your workflows into the directory where it ran, each one named something like "Workflow for Project BUG.xml"

Now you have to look through them for Jira Expressions that contain any of the above patterns. The old Unix tool grep (built into Macs) is useful for this.

This returns all of the validators or conditions that contain any Jira Expression:

% grep 'expression'

If you're looking for validators or conditions that contain a Jira Expression about a description, you could try:

% grep 'expression' * | grep 'description'

So using that same command you could grep for Jira Expressions that use the word contains, length, or even "", although you'll need to do grep '\\"\\"' (XML requires you escape double-quotes with a backslash, and then the shell also requires it)

grep should return the name of the file (which has your workflow's name) where it found a match.

Now you just have to go to those workflows and fix them. Adaptavist's article should help with that.

[Darryl Lee]

As I posted over here:

Now, to be fair, @Arbaaz Gowher does include a very short note about this in the original post:

• Workflow validators and post functions: The new issue transition experience uses REST v3 API with ADF format instead of REST v2 API with Plain String format. This change primarily affects workflow validators and post functions. Read more about the impact of these changes and how to work around them.

However, based on 0 comments on the article Changes affecting workflow validators and post functions on the new issue transition experience, I am not sure anybody understood the implications.

(Also those examples are odd. They detail a Jira Expression doing a replace, which sure, you CAN do, but I'm having a hard time thinking of a use case for it.)

[Thorsten Letschert [Decadis AG]]

@Darryl Lee Great summary.

[Todd Thomas]

Excellent research and help, Darryl! This is the kind of content that makes being a part of the community so valuable.

I hope Atlassian will respond soon to add some clarity around the current status of things and address questions and concerns here.

[John Price]

This is super helpful. Thank you!

[Dave Liao]

Thanks for putting this together @Darryl Lee !

You should contract with Atlassian's documentation team... 💜

[Matt Doar _Adaptavist_]

Glad the article/doc was useful! I've passed this on to the relevant team at Adaptavist

[Gwendylene Enow-Tanyi]

Thank goodness you put this together. Extremely useful.

[Suzie Ahlers]

Here is a March 27th article if you'd like to comment directly to an Atlassian Team member about this.

[Kawan Diogo]

Very helpful this article and I am very happy to know that the script could be useful to support you in this case. :)