Context: During a support engagement (MOVE-1847622) we investigated issues where
Jira Cloud displays literal HTML entities (e.g. `&`, ` `, `<`, `>`)
in issue descriptions and comments. The corruption was traced to HTML entities
being baked into the stored *ADF* (Atlassian Document Format) text nodes,
most likely introduced during a Server/DC → Cloud migration where already-escaped HTML was wrapped into ADF text values.

This document proposes improvements for the development team.

User Problems

1. Corrupted content is visible to end users.
  Entities baked into the ADF render verbatim in the Jira Cloud UI. Customers see
  `AT&T` instead of `AT&T`, ` ` instead of a space, `<`/`>` instead   of `<`/`>` — in descriptions and (mostly) comments.

2. No supported, discoverable way to detect the problem at scale.
  There is no built-in report/health-check that surfaces "issues whose ADF
  contains literal HTML entities." Support/customers must hand-roll detection
  (SQL against internal tables, or REST scraping) with no guidance.

 

Suggested Solutions

A. "Fix formatting" action on the issue view.
Add an in-line action (e.g. a button in the description/comment `···` menu, or a
lozenge shown when corruption is detected) labelled like **"Fix HTML entities" /
"Normalize formatting."** Clicking it decodes literal entities in that field/comment and re-saves it, so the UI immediately shows clean text. One click per object, no manual retyping.

B. Bulk "Fix HTML entities" in the issue-navigator bulk-change wizard.
Add a new operation to the existing Bulk Change UI (Tools → Bulk Change) so an admin can select issues from a filter/JQL result and run "Normalize/Fix HTML entities" across their descriptions and comments — reusing the bulk workflow users already know, with a confirmation/preview step.

 

Current Workarounds

Manual UI fallback (small scale / proof only):

Open the issue, make a cosmetic edit to the description/comment (add + remove a space) and Save to force re-serialization.

Caveats: only works if the editor decodes on load; does not scale; same comment-permission requirement; leaves an "edited" marker.

REST API fallback

1. Identify the real issues from the customer's browse URL/key

2. Detect corruption via REST (ground truth == what the UI renders):

• GET /rest/api/3/issue/{key}?expand=renderedFields&fields=description
• GET /rest/api/3/issue/{key}/comment?expand=renderedBody

3. Fix via the supported REST API (NOT direct DB SQL):

• GET the object's ADF → decode entities inside the JSON text nodes
   (JSON-safe; decode `&` last; leave numeric refs)
• PUT back:
   - Description: `PUT /rest/api/3/issue/{key}`
   - Comment: `PUT /rest/api/3/issue/{key}/comment/{id}`

The PUT triggers automatic re-render + re-index (no full reindex required).