Setup

Applies to: Jira Cloud (Forge app)

After installing and enabling the Forge-powered Sort by any Field app, make sure the following prerequisites are in place:

Atlassian is rolling out the terminology change from projects → spaces and issues → work items. This guide uses the new terms and highlights the few Jira screens (like permission names) that still show legacy wording.

Confirm the board’s filter query ends with ORDER BY Rank ASC:

The app relies on Jira’s native ranking. The board filter must finish with ORDER BY Rank ASC so that the Forge sorter can adjust the existing rank in the background queue.
- How to check your board’s filter query:
  1. Open the target Jira board.
  2. Choose Board → Configure.
  3. In General and filter, review the Filter Query field.
  4. Verify that the query ends with `ORDER BY Rank ASC`. If the clause is missing, append it to your current query (for example, project = FOO ORDER BY Rank ASC—JQL still expects the legacy project keyword until Atlassian rolls out the space alias).
- Why this matters: Without the rank ordering, the sorter cannot reliably promote work items, and the background job may appear to finish without applying the expected order.
Grant users the “Schedule Issues” permission: (Jira still surfaces this legacy label in the permission scheme.)

Sorting is executed by re-ranking work items. Users must be allowed to rank work items on the board.
- How to grant the permission:
  1. Navigate to Space settings → Permissions.
  2. Edit the space’s permission scheme.
  3. Grant the 'Schedule Issues' permission Add the Schedule Issues permission to the groups or roles who will trigger sorts.
Verify the installation is licensed:

The Forge UI now surfaces a warning banner when the app is unlicensed. If that message appears, work with your Jira administrator to activate the license before attempting a sort.

Once these prerequisites are met, open the Sort Board / Sort Backlog / Sort Sprint action, configure (or reuse migrated) “Order by” clauses, and run the sort. Jobs now execute asynchronously; the modal will display status updates until completion.