Correct IDX rule to detect and fix IDX values

[#1]

• Overview
• Why IDX values are used and sometimes need correction
• Executing the correct IDX rule

Overview

The attached rule was updated in October 2025 to include IdentityIQ 8.5. As a best practice, always use the latest rule as indicated for the version of IdentityIQ.

The latest update and recommended version of the "Correct IDX" rule is found in this article and will be periodically updated as needed.  It is supported by all IIQ releases, currently versions up to 8.5. This rule should not be part of a maintenance routine, but as a one-time fix when recommended by SailPoint Support.

The attached "Correct IDX" rule resolves issues with IdentityIQ including NullPointerException error, related to null indexes. Exceptions and errors are visible in IdentityIQ logs, and can occur at various execution points including identity refresh, aggregation, perform maintenance task execution, or during other process execution. Review the full stack trace of the exception to ensure that this rule will provide benefit to correcting the issue. If you are unsure about executing this rule, please reach out to Support by opening a ticket and include the logs containing the error stack trace, along with a description of when you are seeing the NullPointerException.

This rule should not be confused with the IIQ Integrity Scanner (IdentityIQ IDX Integrity Scanner), which should be considered only for IdentityIQ versions prior to 7.3 only. The approach described in the IdentityIQ IDX Integrity Scanner document has been superseded via the plugin, Support Data Collector Plugin.

Why IDX values are used and sometimes need correction

IDX values are created and updated by Hibernate, a framework leveraged by IdentityIQ.  IDX values are used in part to iterate over a list of objects more quickly, in an operation such as such as finding all work items in a certification, aggregation of accounts on identities, refreshing links on identities, etc. The IDX value is a hibernate data-persistence layer pointer that provides the application with the location of the object within a list.

The most common cause for incorrect IDX values or NullPointerException errors is usually incorrect updates using custom code, for example, failing to lock during an update to an object, or when objects are deleted from IdentityIQ without taking proper steps to remove related linked objects. Other causes are one-offs, for example caused by network re-transmissions of packets or data due to collisions, packets arriving out of order, temporary loss of communication within a network, the database cache temporarily not accepting updates, a driver issue at the data layer, or for other reasons.

Executing the correct IDX rule

Always test this rule in a lower environment prior to using in production and ensure that you have appropriate backups in place to handle any recovery in the occurrence of any data issues. Keep in mind this rule is provided as a tool to assist customers, but you are responsible for maintaining the rule and ensuring its proper use. Please follow the directions below to perform this work:

1. Download the file at the bottom of this article: Rule - IDXCheckAll.xml.zip
2. Unzip above and it contains Rule - IDXCheckAll.xml
3. Go to Global Settings, Import from File
4. Under "Import Objects", select the Browse button and find the unzipped file Rule - IDXCheckAll.xml
5. Click the Import button, and the following files are imported.

Rule:SupportRuleIDXCK

TaskDefinition:Support IDXCK Rule

TaskDefinition:Support Task for Hibernate IDX

6. The task will show up as "Support Task for Hibernate IDX" in the Setup->Tasks on the Task tab.
7. The first execution should only require the options "process all DB tables" and "scan tables for null-valued key-column composited with non-null 'idx' key-column" options. This executes the rule in "read mode” and does not update the database.
8. If the task execution finds NULL IDX issues, it will fail with the pertinent errors highlighted in red, and warnings in yellow on the task result. If there are no related NULL IDX issues, then it will simply return a Processing Summary such as below:

<server name> processed nn out of nn mysql table(s) for v.r release

9. If the task returns errors, then you would want to execute the task again with the options above, plus "update DB table rows to resequence 'idx' key-column" selected. This will update the database to re-sequence the affected database rows. The summary should include the updates performed. It is good to execute the task a 2nd time, to ensure that the updates have been done, and you return successful task results (no red items noted).

Please note that this task will only repair NULL IDX issues and cannot fix issues such as null parent foreign key issues, or similar items that may show up as warnings. These types of issues are not as critical as correcting the NULL IDX issues.

If you have any questions or comments regarding this rule, please open a ticket with SailPoint Support.