Future proofing Jira Expressions following the release of the new workflow transition experience

[#1]

Hi everyone,

We recently released the new transition experience which changed the formatting used by rich text fields when run against Jira Expression conditions, validators, and pointer functions. We have since received several queries asking for clarity on how to work with these changes.

When working with Jira expressions, fields can be formatted using either Atlassian Document Format (ADF) or Wiki markup. Marketplace apps that extend workflow functions build on top of these expressions, so understanding how to work with both formats is essential because of:

• Format Variability: Jira's rich text fields appear in different formats depending on the context or integration. Supporting both formats ensures your workflows remain robust and functional.

• Future-Proofing: As Jira continues to evolve, maintaining compatibility with both ADF and Wiki format protects your workflows against potential changes in text formatting standards.

How to Implement Dual Format Support in Jira Expressions:

1. Identify the Field Type: Determine if the field you're working with uses rich text formatting.

2. Write Flexible Expressions: Write expressions that can interpret and process both ADF and Wiki formats for these fields by including functions that convert rich text values to plain text for easier comparison. As an example:
   

   // Function to convert a rich text value to plain text 
   let toPlainText = value => typeof value == 'Map' ? new RichText(value).plainText 
   : typeof value == 'RichText' ? value.plainText : value; 
   
   // Example usage with a custom field and a system field (e.g., "description") 
   toPlainText(issue.customfield_10000) == "Some text" || toPlainText(issue.description) == "Some text";

3. Test Thoroughly: Validate your expressions with sample data in both formats. To test that it works, configure a transition screen on a transition, and then switch between the old and new issue transition experience while performing these transitions. You can do this by toggling the New issue transition experience, found under Settings > Personal Jira Settings.

We hope this guide helps you manage working with rich text fields effectively in your Jira workflows. However, the best solutions often come from community collaboration. We encourage you to share your own examples and strategies for handling dual format support. Whether it's a unique expression you've crafted or another approach you've found effective, your contributions can greatly benefit fellow users.

Thanks, Marcel, Atlassian team.