New admin interface for enabling/disabling Structure dark features
Inactive users are now flagged when grouping by Assignee
Several performance improvements and fixes
Data Center customers: Due to a problem in the Atlassian Universal Plugin Manager, the previous Data Center approved version of Structure, Structure 5.0.1, was reported as incompatible. This problem does not occur with Structure 5.1.
Group, project and role lookup is now available when editing structure permissions
The #distinct modifier has been added to the JOIN function in formulas, to prevent values from being added multiple times
Shared perspectives can be viewed with anonymous access - issues that require specific permissions will not be shown in the structure
When adding generators, the "allow changes" option can be unchecked by default
Fixed: Exporting to Excel issue when exporting a perspective created by Structure 4.x
Fixed: Unable to move issues under a folder when using Rank sort generator
Fixed: Clicking column header does not sort structure when user has view permission
Fixed: Reordering sub-tasks on the issue page does not reorder issues in the structure
Several additional fixes and performance improvements
Supported Versions
Structure 5.1 and all extensions support Jira versions from 7.2 or later. All editions of Jira (Jira Core, Jira Software, Jira Service Desk) are supported. Jira Data Center is supported.
With respect to other add-ons and custom integrations, this release is backwards-compatible with Structure 3.4–5.0. Structure.Testy extension, Colors , Structure.Pages, Structure.Gantt and integrations with third-party apps should continue working normally.
Structure 5.1 will be the last version to support Jira 7.2-7.5. Structure 5.2 will support Jira 7.6+.
Installation and Upgrade
Installing Structure
If your Jira server does not have Structure yet, the installation is simple:
Download and install Structure app, either from the Atlassian Marketplace or our Download page.
When Add-on Manager reports the successful installation, click Get Started to visit a page with important guidance for the Jira administrator. You may want to also check out the user's Get Started page, available under the "Structure" top-level menu.
If you have Structure.Pages installed, make sure you've upgraded to version 1.3 or later, both on Jira and on the Confluence side. If your Confluence version is not compatible with Structure Helper 1.3, you should stay with version 1.2 for Structure.Pages and Structure Helper apps, but please note that there are limitations to its compatibility with Structure 4.2 and higher, so a Confluence upgrade to version 6.1 or later is recommended.
Monitor catalina.out or jira-application.log for log messages from Structure.
The upgrade procedure from versions 3.x–5.0 is simple:
Consider backing up Jira data. Use Administration | System | Backup System. (If you have a large instance and a proper backup strategy in place, you may skip this step.)
Back up Structure data. Use Administration | Structure | Backup Structure menu item. If you have a lot of structures and a large Jira, consider turning off the "Backup History" option to avoid a long backup process.
Install the new version of the plugin.
Monitor catalina.out or jira-application.log for warnings or errors.
We strongly recommend that you back up your data before upgrading. The introduction of manual adjustments required changes to our backup file format, which makes previous versions of Structure unable to restore data from backup files created by Structure 5.0 and later. For more information, see Backup Format Version Change.
Enterprise Deployment Notes
Structure 5.1 has a number of changes that are important for large-scale Jira Server and Jira Data Center instances.
Structure Index Monitor Field DATA CENTER
"Structure Index Monitor" is a system custom field that is automatically installed on Jira Data Center instances since Structure 4.6. It helps Structure capture events related to Lucene-based index subsystem. This is what it looks like on the Jira administrator's Custom Fields page:
This custom field does not store any data in the index, so it does not have a performance impact. Structure Index Monitor field cannot be removed, but it will disappear if Structure is uninstalled and will not affect Jira at all.
One application of this field is ensuring correct cache operation in Structure. When an issue is updated on one node, the indexes on all nodes must be updated to make sure JQL queries return the correct result everywhere. Structure caches also need to be checked on all nodes, and potentially a JQL query should be re-run to make sure that generated content is up to date. The cache update should not happen earlier than the index update, otherwise a JQL query would return an outdated result.
With Structure 5.1, we use the Structure Index Monitor field to help with the timing of cross-node updates. It eliminates a chance of a race condition that would cause Structure to show outdated content on a particular node for a long time after a relevant update has happened.
To test the rollout of this change, you can observe the behavior of the system under a constant stream of issue updates (one change per second, for example), happening on one node, while a user observes a structure with JQL-based automation on another node. At some point the stream of changes should stop, and a few seconds later the user should see the most up-to-date information in Structure.
This feature has been experimental for a while, and we're enabling it now as the default. It is still possible to turn it off and go back to the way events were propagated between nodes in Structure 5.0 and earlier, by using the dark features interface and setting structure.delegatingItemTracker.enableReindexMonitor to false.
Offloading Change Stream Writing to a Background Thread DATA CENTEREXPERIMENTAL
In the Data Center environment, Structure running on one node needs to let Structure running on other nodes know when an item (an issue or some other object) changes. This "change stream" is communicated to other nodes via the database, asynchronous caches and occasional use of a global, one-per-cluster lock.
Normally, each change is written into the database immediately when it happens – in the "event listener". That code runs in the same execution thread as the change itself, typically as a response to a user's action. We recently worked on an incident where the Jira global locking subsystem failed and there were certain issues with the database. That made writing of the change stream "hang", which, in turn, made user request threads hang, which led to Jira being unresponsive.
In Structure 5.1, we're introducing an alternative implementation of this subsystem, which would never block a user request thread. All global lock operations and writing to the database will happen in a separate, dedicated thread of execution.
This feature is currently not enabled by default. For now we recommend to turn it on if a similar problem has happened in the past, or if there's a problem with Jira hanging and you suspect it might be this case.
To enable this feature, set the structure.delegatingItemTracker.enableAsyncEventsQueue property to true in the dark features interface. For more information, see Advanced Configuration.
To test the change, use the same method as described in the previous section.
Lucene and Jira Search Integration
In preparations for the upcoming Jira 8 release, we have adjusted how Structure works with Lucene index and Jira search. This change should not affect performance or the users in any way. To test that everything is okay, one could run a JQL query from Structure | Query board.
Bulk Loading Rows from the Database
One of the database tables that Structure most frequently uses is AO_8BAD1B_ROW. Structures contain rows, and this table stores the mapping between unique numeric "row IDs" and arbitrary "item IDs" of the objects that structures contain. This table is used very often when a structure is displayed.
With Structure 5.1, we implemented a bulk operation that lets Structure get multiple row information with one database request. That greatly speeds up loading structures that have lots of manually added issues and reduces the database load.
To test this improvement, you can try creating a temporary structure, adding several thousands of issues there (manually, copying them from a search result), and then opening that structure after an upgrade or after Structure is disabled and enabled.
Testing on Staging Environment
Apart from the specific suggestions given above, you can run the generic load and stress testing on a staging environment as advised in the previous release notes.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
