Upcoming Changes: Issue ADF Field Transformations

[#1]

Hi everyone,

This post extends the issue transformations we announced for comments, attachments, linked issues, remote links and worklogs.

Extending on those issue list limits, we announced a site wide limit of 1 MB on the amount of rich text (ADF) content a single field can hold, which you can read about in CHANGE-2145. That limit is already enforced when content is created or updated.

The next phase will cover rich text fields on existing work items. Fields that still hold more than 1 MB of ADF content will be automatically transformed to bring them under the limit.

What is a transformation?

Transformations are a Jira-led process, and it only runs on fields that are over the limit. The oversized content is written to a text file, added to the work item as a ZIP attachment, and the field is replaced with a short message pointing at that attachment. Nothing leaves the work item, the content just moves from the field into an attachment on the same work item.

Which fields are affected?

The following fields containing an ADF value exceeding 1mb in total size will be transformed.

• Description
• Environment

• Custom text area (rich text) fields

• Comments

• Worklogs

When is this happening?

We will begin the rollout from 15 September onwards. Transformations will run progressively after that date, so you may not see them on your site immediately.

Description Transformations

Here is a short loom demo outlining description transformations in a standard environment.

Here is a short loom demo outlining description transformations in a JSM environment.

Environment Transformations

Here is a short loom demo outlining environment transformations in a standard environment.

Here is a short loom demo outlining environment transformations in a JSM environment.

CustomField Transformations

Here is a short loom demo outlining customfield transformations in a standard environment.

Here is a short loom demo outlining customfield transformations in a JSM environment.

Comment Transformations

Here is a short loom demo outlining worklog transformations in a standard and JSM environment.

Worklog Transformations

Here is a short loom demo outlining worklog transformations in a standard and JSM environment.

Comments and worklogs behave the same way in Jira and Jira Service Management, so there is a single demo for each of those.

Post Transformation Validation

What actually changes on the work item

When a field is over the limit, the rich text content is removed from the field and the field is replaced with a short message pointing at the archive. For a description, that message reads:

Description exceeded ADF size limits and was archived to attachment issue description exceeding max ADF limit.zip as issue-description-adf-export.txt.

The same message is used for the other field types, with the field name and file names swapped in. Nothing else on the work item is touched.

Before:

After:

Where does the original content go?

The original content is written to a plain text file, which is added to a ZIP attachment on the same work item. Both representations are transformed and both are kept in that text file: the ADF content and the wiki markup content, under an ADF Content heading and a Wiki Content heading. For comments and worklogs the file also records details such as the entity ID, created date and author.

Attachment:

Contents:

One text file per value, one ZIP per field type

Every individual ADF value that goes over the limit gets its own text file. Description and environment only ever have one value per work item, so they produce a single text file each.

Custom text area fields, comments and worklogs can have many values on a single work item. In those cases each value that exceeds the limit gets its own text file containing exactly the ADF and wiki content it previously held, and the file is named after the value it came from. Comments and worklogs use their unique ID, for example comment exceeding max ADF limit (id 10102).txt. Custom fields use the field name.

Each of the five field types produces its own separate ZIP attachment, so a work item that is over the limit in more than one area will receive more than one archive:

• issue description exceeding max ADF limit.zip

• issue environment exceeding max ADF limit.zip

• custom fields exceeding max ADF limit.zip

• comments exceeding max ADF limit (1).zip

• worklogs exceeding max ADF limit (1).zip

Comments and worklogs are archived in batches, so on work items with a lot of oversized content you may see several numbered ZIP files rather than one.

Differences in Jira Service Management

The transformation itself is the same, only the way the archive is attached differs. On a standard work item the ZIP is attached directly. On a JSM customer request the ZIP is added through a comment so that portal visibility is preserved. If the field was visible on the portal the comment is shared with the reporter, otherwise it is internal. Custom text area fields are split into a public archive and a private archive, each posted on its own comment with matching visibility.

Summary comments

Comments and worklogs are different from the other field types because the content lives on many separate entities rather than one field. When at least one comment or worklog is archived on a work item, we add a summary comment so the trail is easy to follow. The summary comment contains an intro line, the ZIP attachment or attachments, and a list of links back to each original comment or worklog that was archived. Each transformed comment or worklog also gets a link appended pointing to its summary comment.

Summary comments inherit the visibility of the entities they cover, so restricted content stays restricted, and on JSM customer requests they are always internal. If several different visibility levels are involved on the same work item, you will see one summary comment per visibility level.

Checking your site before rollout

To help you monitor and manage this data, we are releasing the Get Issue ADF Limit Report API. Admins can use it to get the list of work item IDs that are over the limit.

You can also narrow the report to a single field type with the fieldType query parameter, for example ?fieldType=worklog_adf. The supported values are:

• description_adf

• environment_adf

• customfield_adf

• comment_adf

• worklog_adf 

FAQs

Is this going to delete my work item?

No. ADF Transformations never delete a work item. They only act on one of the five field types listed above when it exceeds the 1 MB ADF limit, and the original content is kept as an attachment on the same work item.

Will transformations impact migrations?

Yes. Transformations will trigger as soon as a customer migrates to cloud.

We don't have anything over the limit. Will transformations impact us?

No. Transformations would trigger only for fields that are over the limit. You will be able to confirm this for your site using the ADF limit report mentioned above.

If you have any questions or concerns, leave a comment below and we will get back to you.

Thank you