Managing LexoRank

LexoRank is a ranking system that enbles the ranking of issues on Jira Software instances.

To work with LexoRank:

  1. In the upper-right corner of the screen, select Administration  > System.

  2. Under the Advanced section (in the left-side menu), select LexoRank management. You'll find the options for balancing the ranking of issues for running integrity checks.  


Each issue has a unique rank relative to the issues around it. This rank is stored as a string. As the number of issues grows and you perform more ranking operations (for example, changing the order of issues in the Agile backlog), the length of these strings increases. 

In the Rank value distribution column, you’ll see the details of how issues in each bucket are distributed and whether the balancing is in progress or disabled. 

Balancing fields will distribute rank values evenly across specific buckets. This will fix the problem specific to the ranking. 

The Rank Status column on the grid provides details about the status of ranked issues.  

Depending on the number of characters in the rank’s string, Jira will schedule the rebalancing or start it immediately:

  • If the rank’s length reaches the first threshold of 128 characters, the rebalancing is scheduled for the next 12 hours. It’ll evenly distribute the ranked issues and significantly reduce the rank length. During the rebalancing, all ranking operations execute as usual. 
  • If the length reaches the second threshold of 160 characters within 12 hours, the immediate rebalancing is started. 
  • If the length reaches or exceeds 254 characters, Jira will only stop the ranking operations that yield values having the length of 254 characters or more. But other operations that don’t meet this criterion won’t be affected. 

The Rank Status has the following properties:

PropertyPossible values
  • OK - the rank length is in a healthy state.
  • Warning - a rebalance has been scheduled.
  • Critical - an immediate rebalance has started, you are approaching a state where rank operations will be disabled.

<current length> / <maximum length>

Maximum length indicates when rank operations will be disabled.

Next rebalance
  • Scheduled—once the threshold of 128 characters is reached, the rebalancing will be scheduled. 
  • Immediate—once the threshold of 160 characters is reached, the rebalancing will start immediately. 

In addition to the preceding properties, the Rank Status field indicates which project has the issues with the longest rank. This is useful to diagnose the cause of a rapid increase in the rank’s length.

If you're encountering some problems or are unsure whether or not to balance, review the integrity checks first and contact Atlassian Support if needed.

Here are the possible breakdowns of the service status that you may face. 

Balancing disabled

If this is true, then Jira Software has disabled balancing internally. Here’s what may cause the issue and how you can try to solve it:

  • A foreground reindex may be running. This may disable the balancing.
  • Jira Software may have just been installed or upgraded and requires a reindex.
  • Check the logs for any exceptions and see if there are any knowledge base articles for these errors.
  • See if there is anything failing in the integrity checks.
Balancing suspended

This should be false unless the balancing has been explicitly suspended by Atlassian Support or your Jira admin.

Balance handler running

This should be false unless the balancing is currently in progress. To verify the progress of the balance, select the Refresh button.

On a Jira Data Center cluster, this will be true on the node that is running the balancing and false on the other nodes.

Balancing in progress on a node of the cluster

It indicates that the balance cluster lock has been taken.

This will be true when the balancing is running.

Integrity checks

Integrity checks allow you to run a series of tests against the LexoRank data and return a true or false result based on the test. In the following table, you can see what checks are available and how you can fix the detected failures.  

CheckHow to fix failures
Marker rows present in the table for the rank field

If this fails, the minimum or maximum marker rows are missing. If marker rows aren’t present in the table, contact Atlassian Support. 

Marker rows correctness check

If this fails, the minimum or maximum marker rows exist, however they have an incorrect rank.

This can be fixed by updating the rank on the row returned in the check to the expected value.

Marker rows in valid bucket check

When the balancing is in progress, the marker rows are moved to another bucket to indicate where the new rank values should be.

The only time they should be in different buckets is if the balancing is in progress.

Here are the valid states for the marker rows: 

  • The minimum is the same as the maximum.
  • The minimum is 0, and the max is 1.
  • The minimum is 1, and the max is 2.
  • The minimum is 0, and the max is 2.

This test fails if the marker rows aren't in those buckets. This failure is likely caused by exceptions thrown during the rank creation or balancing operation. Check the logs and verify them against known problems.

Rank out of bounds checkTo fix the failure, refer to the article How to Fix Rank Out Bound Error. 
Duplicate ranks checkTo fix the failure, refer to the article How To Fix Duplicate Rank Values For a Rank Field. 
Issue ranks different from marker ranks check

The following SQ identifies records that have the same ranking values as the minimum marker rows. 

SELECT * FROM "AO_60DB71_LEXORANK" WHERE ("RANK" LIKE '%|zzzzzz:' OR "RANK" LIKE '%|000000:') AND "TYPE" not in (0,2);
Deleting these records will fix this problem but will result in a loss of ranking data for those issues only. 

This may require changing depending upon the DBMS used.

Issue rows in valid bucket checkIf the balancing can't fix this failure, contact Atlassian Support. 
Balance status check

Run the balancing and check the logs to see if there are any exceptions.  

The balancing may fail due to an exception in the logs or a failure in one of the other checks. 

If you're unsure how to proceed, contact Atlassian Support for further assistance.

Last modified on Jul 7, 2022

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.