How to fix JQL resolution related errors
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Purpose
The purpose of this document is to provide instructions on resolving errors resulting from JQL resolution in any migration. Many entities like Filter, Board, etc. can have JQL queries referencing entity IDs. From JCMA version 1.12.12 to later, JCMA will automatically resolve the DC entity IDs and convert them to respective Cloud entity IDs. However, in certain cases, these JQL queries would only be partially resolved, resulting in some unresolved entities. These unresolved entities will finally be reported in the file Requires-attention_Post-migration with the category - JQL resolution.
To download the Post-migration report, please refer to the steps mentioned here.
Post-migration zip location
Sample Requires attention_Post-migration report
Only supported in JCMA version 1.12.12 and later.
IMPORTANT: Support, CMMs, and customers should be aware that the solution only partially sanitises the JQL string. Also not every thing we can’t resolve is getting reported, please refer to section - #What's not covered in reporting to get more details on what is not covered in report.
Related articles:
Summary
We have identified seven entities that can contain JQL strings that require resolution, namely Boards, Filters, AutomationRules, Queue, Report, TimeMetric, and CustomFilter.
Additionally, 14 entity types use entity IDs in a JQL string. You can reference these in JQL by using various fields and functions.
Entity Type | JQL Fields | JQL Functions |
|---|---|---|
Component | component | |
Custom Field | cf[*] | |
Filter | filter, request, savedfilter, searchrequest | |
Issue | issue, key, id, issuekey, parentepic, parent, linkedissue, issuelink | |
Issue Type | issuetype, type | |
Issue Security Level | level | |
Priority | priority | |
Project | project, parentproject | earliestunreleasedversion, latestreleasedversion, releasedversions, unreleasedversions |
Project Category | category | |
Project Version | affectedversion, fixversion | |
Resolution | resolution | |
Sprint | sprint | |
Status | status | |
User | assignee, approver, pendingby, reporter, creator, voter, watcher, worklogAuthor | projectsleadbyuser, componentsleadbyuser |
The identifier types that can’t be resolved are sent to the report.
Based on the Problem Description column in the Post-Migration report, we can define two categories of errors with their solution
Error Category | Solution |
|---|---|
Description ending with depends on the order of other entities being migrated. | This category refers to all errors that we intentionally don’t resolve due to the current order of entities migrated. To resolve manually update the identifier value with counterpart cloud IDs. Example If the description is - We couldn't fully resolve JQL for the entity since it references SPRINT 111, ISSUE 222 which depends on the order of other entities being migrated.
|
Description ending with missing from this migration. | This category refers to errors that are the result of missing entities in the migration plan. To resolve identify missing entities and add them to the existing migration plan. Example If the description is - We couldn't fully resolve JQL for this entity since it references SPRINT 101, ISSUE 202 missing from this migration.
|
When JQL resolution errors may not be reported
There are many scenarios where we may not see JQL resolution errors in the Requires Attention report:
When a migration is incomplete because of some failure in one of the intermittent stages - JQL resolution errors can’t be guaranteed to be present in the Requires-Attention report.
When you run a migration on JCMA version 1.12.12 or later and switch back to an older version to download the Requires-Attention report, you won't see JQL resolution errors.
When JQL entity ID references are completely resolved and there is no error to report.
What’s not covered in reporting
Anything not covered in above table isn’t included in the resolution or reporting. Below are some identified areas we haven’t covered in resolution/reporting
Search for custom fields from plans in JQL | Jira Cloud | Atlassian Support
JQL vulnerability search | Jira Cloud | Atlassian Support
JQL developer status | Jira Cloud | Atlassian Support
JQL design search | Jira Cloud | Atlassian Support