Documentation

JQL Stabilizer user guide

How to use the app and understand its limits.

Product overview · Support

What the app does

JQL Stabilizer prepares supported custom field references for renaming on the same Jira Cloud site. It replaces an unambiguous field name with its numeric JQL reference, for example:

summary ~ "Story Points" AND "Story Points" > 3 ORDER BY "Story Points" DESC

becomes:

summary ~ "Story Points" AND cf[10010] > 3 ORDER BY cf[10010] DESC

This is an example; 10010 is not a field ID to reuse on your site. The quoted search value in summary stays unchanged. Supported field spans are replaced; values, function arguments, whitespace and surrounding syntax are preserved. The two visible field-catalog sources must agree on exactly one custom field ID.

Jira can list several autocomplete aliases even for a unique custom field. Recognized aliases do not make a plain name ambiguous; distinct custom field IDs do. System-name collisions still block that name. Explicit typed references such as "Story Points[Number]" remain unchanged and are reported as collapsed, even when the plain name is unique.

The app does not reconstruct an old name after a field has already been renamed or deleted. Review before a rename. A Safe proposal still needs Jira's separate equivalence check before any Apply. The app updates your own eligible filters after confirmation; Revert restores only your own last verified update for that filter in the open session.

Workflow

  1. Open JQL Stabilizer in Jira's Apps area. An active license is required; an inactive or missing license blocks scans. A free-tier or trial entitlement must be recognized as active by Atlassian, not by a local user counter.
  2. Load the visible field catalog for this session. Refresh fields reloads it after field changes; before Apply, a catalog older than ten minutes is refreshed. If the catalog fails to load, nothing is reported as fully analyzed.
  3. Select a workflow:
    • My filters: scan filters you own. Review each status, replacement count and finding, then open a row to see its original JQL and proposal. Jira parses original/proposal pairs with strict validation in your user context.
    • Field impact: choose a visible field and review accessible saved filters grouped as by name, by ID or collapsed. This is a read/copy workflow; private filters of other users are not visible to you.
    • Stabilize a query: paste JQL, inspect the supported proposal and Jira check, then copy it manually. This does not update the saved filter, Automation rule, board or dashboard you copied the text from.
  4. A run processes at most 500 filters. Continue scans the next portion in the same session; Cancel stops the run and leaves an explicit partial result. After a rate-limit pause or a failed scan, Resume continues from the last completed page or query check. Restart scan begins again. Temporary read failures are retried automatically. None of these results claims full coverage.
  5. Copy a proposal from its text area for manual review/use. Copying instructions appear only when a checked proposal is available. When updates are enabled, eligible filters also offer Apply.
  6. Use Filter order to sort the full scanned list by name, status or replacement count. Previous page and Next page show 20 results at a time.
  7. When Apply is enabled, it requires a Safe result and Jira-confirmed equivalence, your ownership, no other editors, a matching fresh preview and explicit confirmation for that one filter. Keep Previous query from the confirmation dialog.
  8. Apply rereads the filter, recomputes the proposal, checks it with Jira again, writes only the query alongside the current name/description required by Jira, and rereads the result. A stale preview stops without writing. The post-write check compares the name, description, owner, sharing and editor permissions, not just the new query.
  9. After a verified update, Revert can restore your own last verified update for that filter in this session. It requires the unchanged applied query and a successful recovery check. Keep Previous query before closing or reloading; this loses the app's undo history. For a blocked Revert, follow the recovery table below.

My filters and Field impact keep independent Continue/Resume/Cancel state while sharing the session's field catalog. Rate-limit waits happen before the next fresh filter read. A new deadline during an update aborts that attempt; the next explicit attempt repeats the checks. A failed success metric does not remove a verified update's Revert. A later failed scan-start check, disabled updates or an inactive license still blocks it.

For a shared filter, the warning Checked against the fields you can see matters: a viewer with another field catalog can interpret a name differently. Review the effect with that viewer before renaming or updating a shared filter.

If others can edit a filter you own, a Safe result with Jira-confirmed equivalence keeps its copy field and the notice Others can edit this filter, so concurrent changes cannot be detected. Copy only. If the query is not fully stabilized, no copy field is offered. The notice is Others can edit this filter. The query is not fully stabilized, so it is not offered for update. A filter with No change needed keeps that neutral status.

Query status reference

These labels describe the proposed replacements. Jira’s separate query check appears alongside them.

StatusMeaningAction
No change neededNo supported name-to-ID replacement is needed; includes empty queries, system-only queries and queries already using IDs. This is not a validity certificate.Review the Jira check if needed; there is no new proposal to Apply.
SafeAll supported field names can be replaced with stable IDs, and the proposed query passed the app’s checks.Review original/proposal. Apply also requires Jira-confirmed equivalence and all ownership/concurrency checks.
PartialSome references were converted but findings remain.Copy only after Jira confirms equivalent queries, except an owned filter with other editors, which has no copy field; no Apply.
Not stabilizableFindings exist and no safe replacement was made.Resolve the field/function ambiguity manually; no generated proposal.
UnparseableThe app cannot safely read the query because its syntax is incomplete or unsupported.Correct/review it in Jira; no generated proposal.
Self-check failedThe app could not verify its proposed changes. The proposal is withheld.Stop and use content-free diagnostics for support.
Not readableJira did not make this filter/query available to you.No title/query details are exposed; do not infer that the filter was deleted.
FindingMeaning
More than one field has this nameMore than one field may match the name. The app cannot choose a single field safely.
Field not found in your visible fieldsThe name is absent from the visible catalogs; it may have been renamed, deleted or hidden.
This reference intentionally includes multiple fieldsA name/type reference deliberately searches a group of fields; it stays unchanged.
This name also identifies a system fieldA custom field name collides with a system field name; it stays unchanged.
The two Jira field sources disagreeJira’s field lists disagree about which field the name identifies.
An app function may contain field referencesA third-party query function may contain other field references. Its arguments are left unchanged.
Jira checkMeaningAction
Jira-confirmed equivalenceJira's parsed structures match after supported field references are compared by identity.Necessary for Apply, but does not prove another viewer's interpretation or live result sets.
Jira did not confirm equivalent queriesJira's structures differ, or a field cannot be resolved to the same identity.No Apply.
Jira reports this query as invalidJira rejects the original query.No Apply; correct it in Jira.
Jira reports the proposed query as invalidJira rejects the proposed query.No Apply; keep the original and report diagnostics.

A pending, unavailable or failed Jira check does not confirm equivalent queries. The check compares query structures; it does not certify another viewer's interpretation or every dashboard that uses the filter.

Session and update status reference

LabelMeaning / next step
License activeYour entitlement permits the workflow, including a trial or free tier recognized as active by Atlassian.
License inactiveNo scans or updates. Ask your Jira admin to check the Marketplace entitlement.
ReadyNo scan has started.
Loading fieldsJira is returning the fields you can see.
ScanningThe app is reading saved filters.
ValidatingJira is checking the original and proposed queries.
Scan completeThis run finished; it covers only the filters visible to you.
Scan limit reachedThis run reached 500 filters. Continue to check the next portion.
Scan stoppedThe filter scan was cancelled. Results are incomplete.
Query check stoppedThe pasted query check was cancelled. Results are incomplete.
Scan pausedJira is limiting requests. Resume after the waiting period.
Scan failedThe check could not finish. Resume from the last completed page or query check, or restart to begin again.
Updating the filter…Apply is in progress. Wait for the result before taking another action.
Restoring the previous query…Revert is in progress. Wait for the result.
UpdatedA verified update is marked in the filter row until it is successfully reverted in this session. A My filters scan that finds the previous query after an unverified Revert returns the row to its current scan status; updates remain blocked. Other rows keep their scan status.
AppliedThe update and its verification succeeded. Revert is available while this page remains open and updates are enabled; otherwise copy the previous query for manual recovery.
RevertedThe previous query was restored and verified. The Apply button and its guidance return for eligible filters; another update still requires confirmation.
Wait for the current action to finish.Another check or update is running. Wait before applying this filter.
Not appliedA required check blocked the update; no write was sent. See the reason below.
Verification failedJira returned an unexpected result, or the write response was lost. Keep the previous query and inspect the filter and permissions in Jira. If the read-back confirmed the previous query and metadata were unchanged, scan My filters again and review the preview before another confirmed Apply. If the result is unknown, reload before trying again.
Verification unavailableThe update was sent but its result is unknown. Reload to check the filter before trying again.
Update failedJira did not complete the update. Inspect the filter before trying again.

During another check or update, the detail asks you to wait. A successful Apply marks the filter row Updated. The detail keeps its scan explanation and shows "The filter was updated." once in the result message. If Revert fails, the row stays Updated and the detail explains the result.

After a successful Revert, eligible filters again show Apply with "Ready to apply after confirmation." This guidance accompanies the Apply button only when the result is known; it is hidden after a failed or unverified update. Follow the result message before trying again. If verification is unavailable, follow the reload guidance before trying again.

Recovering after an update

Previous query is the same saved text in the confirmation dialog and filter details. Copy it before closing or reloading the page. Always review the current query in Jira before restoring it. An unverified update never enables Revert. Apply and Revert are never retried automatically.

Revert requires the filter to still contain the applied query; stabilizing Previous query must reproduce it. Changes by someone else, unavailable updates or a failed recovery check block Revert.

MessageWhat it meansWhat to do
AppliedThe update and its checks succeeded.Revert is available only for your last verified update in this open session, while the filter is unchanged and updates are enabled.
RevertedThe previous query was restored and verified. The details show the restored query and its replacements instead of the earlier scan.Eligible filters offer Apply again; review and confirm any new update.
This filter changed after the preview. Refresh and review again.The query, owner or other editors changed. Apply is hidden until you scan My filters again.Scan My filters, then review the new preview. A completed scan replaces old query and access explanations only for the filters it checked.
The proposal changed. Refresh and review again.Changed fields prevent using the preview. A scan using the old field list does not clear this notice.Select Refresh fields, then scan My filters and review the results. Refreshing fields alone or scanning Field impact does not replace this preview.
Jira could not confirm equivalent queries. Nothing was changed.The query pair did not pass Jira's check; no write was sent.Scan My filters again and review the new preview.
Jira still shows the previous query.The immediate read-back confirmed that the previous query, name, description, owner, sharing and editor permissions were unchanged.A completed My filters scan showing the same query can offer Apply again without reloading. That matching scan removes the recovery field and advice because there is nothing to restore. Review and confirm the new preview.
Verification failed or Verification unavailable after ApplyJira may already have accepted the update, including when its response was lost. Apply is hidden.Scan My filters to inspect the current query. Keep Previous query for uncertain results, then reload before trying again. An unknown earlier result stays blocked even if a later scan shows the previous query.
Jira still shows the stabilized query. The revert was not saved.The immediate read-back confirmed that the stabilized query and metadata were unchanged.A completed My filters scan can offer Revert again only for your unchanged filter without other editors. Each click rereads the filter, checks the query pair, writes once and verifies the result. No Revert is retried automatically.
Verification failed or Verification unavailable after RevertJira may already have restored the previous query. An unverified Revert is disabled.Scan My filters and keep Previous query before closing or reloading. Uncertain results stay disabled; seeing the stabilized query in a later scan does not enable Revert.
The field list changed, so the previous query cannot be restored automatically.The recovery check failed. Refreshing fields or scanning again does not enable that Revert.Keep Previous query and review the current query in Jira before restoring it manually.
Only the owner can update this filter.You no longer own the filter.Send the previous query to the owner for review. A new My filters scan can offer Revert only when you own the unchanged filter and no one else can edit it.
Others can edit this filterOther editors prevent a safe Revert.Review the previous query in Jira. Their editing permissions must be removed before another My filters scan can offer Revert for your unchanged filter.
There is nothing to restore.A completed My filters or Field impact scan found the previous query in your own filter after a successful Apply or a Revert rejected because the query, owner or other editors changed.No restoration is needed. The Previous query field is hidden, even if others can edit the filter. Revert stays unavailable.
The query has since changed in Jira, after an update or revert was not savedThere is nothing to restore from that attempt. The previous query is shown for reference, with no restoration advice.Review the current query in Jira. Keep Previous query for reference; reload and scan My filters before another update.
The query has since changed in Jira, after a successful Apply or rejected RevertA changed query disables Revert. This also applies when a Revert is rejected because the query changed.Keep Previous query for reference and review the current query in Jira before restoring it. If Jira already shows the previous query, there is nothing to restore.
Verification failed or Verification unavailable, with a later scan showing the intended queryA write may have arrived late, even if an intervening scan showed a different query. The notice follows the current scan.Keep Previous query for recovery; updates remain blocked until you reload and scan My filters.
A scan shows the previous query after an unverified RevertThe row shows its current scan status instead of Updated. An outdated not-saved explanation is removed.Follow the current result message. An uncertain earlier result stays blocked; the scan does not offer another Revert.

My filters and Field impact display the latest completed scan or verified restore. Scanning Field impact does not refresh the My filters preview. Field impact does not check editor permissions or authorize an update. When the owner and query are unchanged, a Field impact scan retains the editor permissions read by My filters. It does not enable a blocked Revert.

Field impact keeps its copying instructions visible after an update result and while another action runs. Each instruction appears once. Copying a stabilized query is suggested only when its copy field is present; without that field, notices about other editors or unavailable updates omit Copy only.

Temporary field-list, read and pair-check failures allow an explicit retry. An unchanged read-back must be confirmed by a completed My filters scan before Apply or Revert can be offered again. Field impact, refreshing fields alone and failed scans cannot enable it. A new attempt always repeats the checks before writing.

Update checks follow this order: update availability, license, fresh read, owner, preview conflict, other editors, field catalog, safe replacements, matching proposal and Jira's pair check. Temporary read and pair-check failures show how long to wait before an explicit retry. They keep the filter row visible and do not send an update.

MessageMeaning / next step
Copy only. Applying updates is unavailable in this session.Updates are unavailable; copy a checked proposal for manual review. Reload before trying again.
Your JQL Stabilizer license is not active. Ask your Jira admin to renew it.No active entitlement; ask your Jira admin, then reload after it is renewed.
Jira could not read the filter right now. Nothing was changed.No write was sent. Retry after the indicated waiting period.
Not available to you.The filter cannot be reread; no details or update are offered.
Only the owner can update this filter. Copy the stabilized query and send it to the owner.Contact the owner through your own process.
This filter changed after the preview. Refresh and review again.Nothing was changed.
Others can edit this filter, so concurrent changes cannot be detected. Copy only.A Safe, Jira-confirmed proposal can be copied. Otherwise no copy field is offered.
Jira did not return the field list. Nothing was analyzed.Retry, or select Refresh fields and scan My filters.
This query is not fully stabilized. Copy only.Some references could not be replaced safely. If Apply detected this after a field-list change, select Refresh fields, then scan My filters and review the results.
The proposal changed. Refresh and review again.The recomputed query differs from the preview. Select Refresh fields, then scan My filters and review the results; nothing was changed.
Jira could not check the query pair right now. Nothing was changed.No write was sent. Retry after the indicated waiting period.
Jira could not confirm equivalent queries. Nothing was changed.The query check failed; no write was sent. Scan My filters again and review the results before applying.

When updates are unavailable, only checked proposals can be copied. Jira exposes no atomic filter version/ETag check. The same owner saving in another tab can still race with Apply; fresh reads reduce that window but do not make an absolute concurrent-edit guarantee.

Empty and error results

  • No owned filters: You don't own any saved filters yet. Use Field impact or Stabilize a query instead.
  • No replacements: no supported conversion is needed. Empty or unsupported queries are not thereby proven valid.
  • Field catalog blocked (for example, by an app-access policy) or unavailable: Jira did not return the field list. Nothing was analyzed. Retry; do not treat this as an empty catalog or a completed scan.
  • Unreadable filter: Not available to you. No filter title or query is shown.
  • Invalid original: Jira reports it as invalid; it is not changed.
  • Preview conflict: refresh and review again; nothing is written.
  • Other editors or foreign owner: Apply stays blocked. Copy requires Jira-confirmed equivalence; an owned filter with other editors also requires Safe. In My filters, Field impact and Stabilize a query, a notice offers copying only when a copy field is present.
  • Unexpected read-back: the previous JQL is shown for manual recovery; verify the actual filter and permissions in Jira.
  • Scan errors explain whether Jira could not return fields, read filters, validate query pairs or return the expected data. Partial results remain incomplete. Resume keeps completed pages and query checks; Restart scan begins again. Refresh fields reloads the catalog and clears earlier results.

Scope, privacy and lifecycle

  • Fields and filters must be visible to the signed-in user. Private filters of other users are not visible, including to an administrator using this app. The app does not use administrator overrides.
  • Apply changes only a filter you own, without other editors, after per-filter confirmation. No mass updates, sharing/editor changes, deletion of filters, or modification of other people's filters is offered.
  • There is no dashboard, gadget, board quick-filter or Automation inventory. Pasted text can be reviewed without discovering or updating the source. Versions, components and statuses are not converted to IDs.
  • cf[ID] is site-local, not a portable field identifier. Another site, sandbox or migration destination can use the same number for a different field. Review its catalog before transferring any query; no cross-site mapping is provided.
  • No query, catalog, result or undo history is persisted in app storage. Browser session memory is lost on reload/close. Applying a proposal deliberately persists the changed filter in Jira; the app's session-only query history does not delete it.
  • No external data egress, vendor backend or external AI is used. Only event codes/counts may enter app logs, never query text, field/filter names or account IDs; Atlassian platform metadata and retention are separate.
  • Uninstalling or losing a license does not restore or remove updated Jira filters. They remain normal Jira JQL; the app has no retained content to export or purge. Keep your original query outside the app if you need later recovery.

See the privacy policy and app data handling.

Support

Use Copy diagnostics for the intended support bundle: diagnostic codes and numeric counts only. Review it before sending. Do not send query text, field/filter names, account IDs, or screenshots containing them. Describe the steps, workflow and status in your own words. The diagnostics control supplies a read-only text area to select and copy; do not replace it with raw query text, a console dump or a network trace.

Ask your Jira administrator for the approved support channel.

Only aggregate monthly usage totals and a short coordination record are saved in site-scoped Forge storage. They contain no account IDs, issue IDs, titles, query text or results. Monthly totals are replaced when work starts in a new UTC month. Uninstalling follows Atlassian’s 28-day hosted-storage retention policy.

Monthly usage allowance

Each site shares 56 service requests per calendar month (UTC). Opening the app, starting or resuming an analysis, refreshing fields, and confirming a completed update each use a request. An unavailable usage check or an exhausted allowance stops new analysis; results and previous query text already in the tab remain readable. Confirmed Jira changes remain in Jira.

The allowance also covers up to 120 KB of reads and 60 KB of writes for usage totals. During a temporary service pause, new analysis and filter updates are unavailable. Keep the previous query text if you need to restore a filter directly in Jira. Closing or reloading discards the session.