6th of February 2019

Structure 5.2.1 fixes a critical indexing problem that may affect users.

Download from Archive 
Structure on the Atlassian Marketplace

1. Patch Release

This is a patch release based on Structure 5.2.0. It fixes a critical problem that could cause a full re-index to fail because of interference from Structure-related background activity.

Upgrade is recommended for all customers using Structure 5.2.0.

2. Installation

If your Jira server does not have Structure yet, the installation is simple:

  1. Download and install the Structure add-on, either from Atlassian Marketplace or from our Download page. Pick the correct version based on your Jira version!
  2. When the Add-on Manager reports a successful installation, click Get Started to visit a page with important guidance for the Jira administrator. You may also want to check out the user's Get Started page, available under the "Structure" top-level menu.
  3. Monitor catalina.out or jira-application.log for log messages from Structure.

3. Upgrade

If you're upgrading from version 2.11.2 or earlier, please read Structure 3.0.0 Release Notes.

The upgrade procedure for versions 3.x to 5.2 is simple:

  1. Consider backing up Jira data. Use Administration | System | Backup System. Starting from version 3.0.0, Structure data can be backed up together with Jira data. (If you have a large instance and have a proper backup strategy in place, you may skip this step.)
  2. Install the new version of the plugin.

  3. Monitor catalina.out or jira-application.log for warnings or errors.

4. Enterprise Deployment Notes

The main platform change in Structure 5.2 was the introduction of index consistency checking. To summarize, Jira 8.0 includes a newer version of Lucene, so it will delete your existing index after the upgrade and start re-indexing in the new format. Since Structure relies heavily on the Lucene index, we want to pause its operation until the re-index completes and the index becomes consistent with the database again.

To do that, Structure periodically checks the Lucene index consistency by calling a method provided by the Jira API, which performs a few database queries and index accesses. We have discussed our implementation with the Jira development team, who assured us that these periodic checks wouldn't negatively affect the performance of the Jira instance.

During a full re-index, the Lucene index is normally expected to be inconsistent, and the consistency checks should be suspended. However, due to a problem with the Jira API not reporting correctly that the index is being rebuilt, Structure was still performing these checks in the background once about every 5 seconds. In a few support cases, we have observed a strong correlation between this background activity and the re-index failing due to missing index files.

We are communicating with Jira developers to uncover the actual cause of the issue. In the meantime, to work around the problem, Structure 5.2.1 uses a different method to detect that a full re-index is in progress. Also, we have made it possible to disable index consistency checking altogether by setting a dark feature.

We advise that you try running a full re-index on a staging Jira instance before upgrading from Structure 5.1 or earlier. The usual load and stress testing can also be performed.

Need help or have questions? Contact Tempo Support.