9th of September, 2016

Structure 3.3 is a major release that adds support for structure migration between JIRA instances, extends S-JQL with ability to search for folders and other non-issue items, addresses compatibility issues with JIRA 7.2 and has other improvements and important fixes.

Important for Structure 2.x users! If you currently use Structure 2.11.2 or an earlier version, it is very important that you read Structure 3.0 Release Notes before upgrading.

Download the latest Structure and Extensions
Structure 3 Demo Server 
Structure 3 Quick Start Guide

1. Version Highlights

Structure 3.3 is a major update in the Structure 3 series. It contains several new features:

  • Migration of Structure data between JIRA instances (also allowing partial restore from backup)
  • S-JQL support for searching folders and other items
  • Special filter that removes duplicates added by a combination of inserters and extenders
  • Maintenance task that removes old structure change history (please check the defaults!)
  • Swapping panels in two-panel mode
  • JIRA 7.2 compatibility
  • Significant fixes and improvements related to performance and troubleshooting

Upgrade is recommended to all users.

2. Changes in Detail

2.1. Structure Data Migration

It's now possible to import one or more structures from a different JIRA instance after you have imported projects with the JIRA's Project Import operation. Also, you can partially restore deleted or broken structures from a backup without affecting other structures.

Documentation: Structure Backup, Restore and Migration

Migration used to be a Structure 2 feature, but it was disabled with the release of Structure 3, as we've moved the storage from a separate database to the JIRA main database. Now it is being reinstated.

2.2. Search for folders and other non-issue items with S-JQL

It is now possible to identify folders (whether specific folders by name or all folders) and other types of items in S-JQL expressions. This expands the power of S-JQL to all items – for example, it allows searching for a contents of a specific folder.

For example: descendant of folder("next release")

Documentation: Structured JQL

2.3. Special filter for removing duplicates from using Inserter and Extender

It is a typical setup when you use JQL Inserter to place all matching issues at some place in a structure, and then use an extender (for example, Links Extender) to build a hierarchy of relationships starting from the inserted issues. For example, to show all issues from a project with dependencies placed hierarchically, you'd add a JQL Inserter (project = ABC) and a Links Extender with (depends on) link type.

The problem with such setup is that an issue may get inserted once by the inserter, and then again added at a deeper hierarchy level by the extender.

To remove such duplicates, use a special "Remove Inserter/Extender Duplicates" filter.

Documentation: Inserter/Extender Duplicates Filter

2.4. Maintenance task to clear old change history

Daily maintenance now includes clearing up database space by removing old change history for structures. It is recommended to not disable this task to avoid database size buildup and reduction in activity streams querying performance.

Please check the default settings! By default, structure history that is both older than 30 days and less recent than 1,000 last changes (counted for each structure separately) will be removed daily. If you think that you need history of changes for a larger period, please review and make changes to the settings immediately after the upgrade!

Documentation: Automatic Structure Maintenance

2.5. Swapping panels in two-panel mode

When you have two structure panels open, you can now easily swap left and right panel by pressing Alt+\ keyboard shortcut.

2.6. JIRA 7.2 compatibility

Structure plugin and its extensions are now compatible with JIRA 7.2 and newer versions, including JIRA Data Center. The minimum supported version is JIRA 6.4.

2.7. Notable Fixes and Improvements

The following issues have been addressed in Structure 3.3:

  • Added: Performance-related metrics, displayed to the JIRA admin, which would help Tempo support diagnose performance-related issues faster.
  • Added: Workaround for JIRA Data Center issues regarding cluster-based caches (JIRA issues JRA-62034 and JRA-62071) that could cause JDC initialization failure.
  • Fixed: Page freezes when removing extender in a structure with a lot of items.
  • Fixed: Database troubleshooting page isn't accessible when database is locked.
  • Fixed: Impossible to open issue page via clicking on the issue key on issue details panel.
  • Fixed: Impossible to delete a structure that has slowly performing generators.
  • Fixed: Slow activity stream queries.

3. Supported Versions

Structure 3.3 and all extensions support JIRA versions from 6.4 to 7.2. Note that for Structure there are separate downloadable files for JIRA 6 and JIRA 7. All editions of JIRA (JIRA Core, JIRA Software, JIRA Service Desk) are supported. JIRA Data Center is supported.

Structure 3.3 is the last version of Structure to support JIRA 6. Structure 3.4 will most likely support JIRA versions starting from 7.0.

3.1. Structure.Pages Upgrade Required

 Please note that if you're using Structure.Pages, you will have to upgrade it to version 1.1.0.

3.2. Structure.Testy Upgrade Required

Please note that if you're using Structure.Testy, you will have to upgrade it to version 2.1.0.

4. Installation and Upgrade

4.1. Installing Structure

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

  1. Download and install Structure add-on, either from Atlassian Marketplace or from Download page. Pick the correct version based on your JIRA version!
  2. When Add-on Manager reports about 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 "Structure" top-level menu.
  3. Monitor catalina.out or jira-application.log for log messages from Structure.

4.2. Upgrading Structure

Upgrade procedure from versions 3.x.x 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 proper backup strategy in place, you may skip this step.)
  2. Install the new version of the plugin.

  3. Upgrade Structure.Testy and Structure.Pages add-ons if you're using them.
  4. Monitor catalina.out or jira-application.log for warnings or errors.