Round tripping ADF documents

[Tim Penhey]

I'm wanting to programmatically update a Jira ticket's description.

The description is formatted using ADF, and I'm wanting to be able to scan the contents of the document for particular sub-elements.

The jsonschema for ADF references "localId", but this isn't really referenced in the ADF documentation (https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/). Can I rely on this value being saved and echoed back? Is this use an expected and supported use of the `localId`?

[Peter_DevSamurai]

Hi @Tim Penhey , 

I hope everything works out well for you! Though I'm not able to help you out with this but based on what our team encountered, you can rely on localId being saved and echoed back in ADF documents for Jira Cloud (at least with the Standard plan). 

When you GET an issue's description via the REST API, the ADF includes any existing localIds. On PUT updates (/rest/api/3/issue/{issueIdOrKey}), if you include the original localId in your ADF payload, it's preserved by the system—no recreation or loss unless you explicitly omit/override it.

A little tip for you is that to use the GET the current ADF first, modify selectively, then PUT -> avoids overwriting concurrent changes. 

Hope everything works out well for you and find the relevant links below:

• ADF Structure document
• Update issue API

Best regards, 

Peter