Troubleshooting
Problem
A failure to run the repairUnreferencedVersions before performing a reindex can result in unexpected behavior in the user interface for IBM DOORS Next Generation (DNG), including any reports generated from the DNG data.
Additionally, the size of the DOORS Next Generation index cannot be reduced to an optimal level until any reported issue are corrected.
Note: It is important to note that this technical document contains information updates and revised steps for running the repairUnreferencedVersions command. The explicit need to run a repotools-rm -reindex after the repair command has been removed.
If you have already run the repair and ran repotools -reindex after this operation, then your index will already be pruned and optimal in size. The next time CleanUpUnusedVersionsTask runs, there will not be a large backlog to process.
Symptom
There are a number of different symptoms that are associated with this issue:
1) In the RM Logs you see an error similar to the following:
1) In the RM Logs you see an error similar to the following:
2019-01-01 00:03:00,123 [rm: AsynchronousTaskRunner-2 @@ 00:00] [ERROR] .service.internal.CleanUpUnusedIndexesVersionsTask - CleanUpUnusedIndexesVersionsTask: Found 242 version(s) incorrectly Unreferenced. Please run the -repairUnreferencedVersions repotools command
2) Unexpected behavior in the GUI with versionable artifacts such as links, comments, tags, artifacts, types, etc.
If a repotools -reindex all has been run prior to fixing these incorrectly unreferenced versions, then unexpected issues can occur in the GUI. It is difficult to be specific on the symptoms as nearly all data that is shown in the GUI references the index. If the correct version is not there, then the GUI will not be able to display the data correctly.
Even if there are references to correct, you may not see all of these symptoms.
Cause
DNG uses an index (Jena) to store data about requirements that it then leverages in the GUI. This index data is a subset of the data that is in the relational database.
Items that are no longer needed become unreferenced versions. Once an artifact is unreferenced, it is no longer required in the index and can be removed.
DOORS Next Generation 6.0.6 resolves several issues with unreferenced versions and is also how repotools - reindex all re-populates the index. These fixes allow the CleanUpUnusedVersionsTask to perform index pruning, reducing the size of the overall indices and the resources that are required to optimally process them, but also for reindex not to repopulate the index with this unnecessary data.
Clients upgrading to DOORS Next Generation (DNG) 6.0.6 should append the command that is listed within the Resolving The Problem section of this document to their post-upgrade steps ensure that their database contains no historic issues relating to population of their index.
If you have already upgraded, then you should check your RM logs, as described in the Diagnosing The Problem section of this document. This is especially important if you have run the repotools-rm -reindex all command. Until a repair command is run, the index integrity is not ensured and data population within the GUI may not be complete.
At the time of writing, one remaining defect, 470074: unreferenced versions are not reindexed on changeset delivery , remains which can cause incorrectly unreferenced versions to occur. Therefore, you should monitor whether the CleanUpUnusedVersions task stops running on a regular basis.
Note:
- No data is lost.
- The Upgrade Guide will include an explicit step on running the command repotools-rm -repairUnreferencedVersions if errors are reported when running repotools-rm -verify as part of a typical upgrade sequence.
- Update Advanced Property noted in the following "Resolving the Problem" section.
See Documentation: Interactive Upgrade Guide: RDNG corrections (repairUnreferencedVersions/Reindexall (474466)
Diagnosing The Problem
Review the RM logs for any messages similar to the following:
a)
2019-01-01 00:03:00,123 [rm: AsynchronousTaskRunner-2 @@ 00:00] [ERROR] .service.internal.CleanUpUnusedIndexesVersionsTask - CleanUpUnusedIndexesVersionsTask: Found 242 version(s) incorrectly Unreferenced. Please run the -repairUnreferencedVersions repotools command
This indicates the repair tool MUST be run.
b)
2019-01-01 00:17:24,123 [ rm.jfs.indexer.text.history] INFO com.ibm.team.jfs - Unused indexes cleanup task started
This message indicates that there are no issues within the database.
This task will not start if there are any issues within the database. As it ran then there are no further actions required.
Note:
If you cannot find either message in the RM logs, check the Advanced Properties within rm/admin to see when this task is expected to run:
Search for com.ibm.team.jfs.indexing.service.internal.CleanUpUnusedIndexesVersionsTask
Note the day and time when this task is scheduled to run and ensure that the logs capture corresponding entries for this period. Alternatively, you must wait until the next scheduled run.
Soon after the task has run check the log for the messages described above.
Resolving The Problem
To repair this problem, the advice for upgrading to 6.0.6 is to run repotools-rm -repairUnreferencedVersions as part of the upgrade steps and before you reindex DNG.
If there are any issues, they will be corrected as part of the repair command. No additional commands need to be run.
If no issues are reported. No more actions are required in terms of repair.
When you have any of the symptoms that are described above, then you must do the following:
- Schedule an outage for DNG
- Under Admin->Advanced Properties, change the "Indexes cleanup transaction size" property from the default of 20000 to 1000
- Shut down the DNG application and take a backup of the database (as per standard backup procedure)
- Run the repotools-rm -repairUnreferencedVersions
- Check the repotools log to ensure that the repair completed successfully
- Restart the DNG application if there are no error
Note: The length of time it takes to perform these steps will depend on the size of the data and in some circumstances can take a considerable time.
Note: It is not necessary to run the repotools -reindex all command. The repotools -repairUnreferencedVersions command repairs the affected indices as part of the repair process.
Related Information
[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSUVLZ","label":"IBM Engineering Requirements Management DOORS Next"},"Component":"","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"6.0.6","Edition":"","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]
Product Synonym
Rational DOORS Next Generation
Was this topic helpful?
Document Information
Modified date:
21 February 2019
UID
ibm10795874