Structure 5.0 Release Notes

1. Version Highlights

• Manual adjustments to auto-generated content
• Horizontal scrolling
• Work Logged can now be based on user, group or role
• Flexible maintenance scheduling with crontab
• Support for “hidden” issue links
• User interface changes to match Jira 7.10

2. Changes in Detail

2.1. Manual Adjustments

Manual Adjustments allow you to move dynamic content within a structure, regardless of the Automation used to create the structure.

When you use generators to build structures, you’re restricted in how you can move items within your structure, based on the generator rules. When Manual Adjustments are enabled, you can move items or create new items within your structure regardless of the generators used to create it.

Manual Adjustments are not reflected in Jira and may be affected by changes to your generators or Jira items.

Documentation: Manual Adjustments

Implementing Manual Adjustments required us to make changes to our backup file format. As such, previous versions of Structure will not be able to restore data from backup files created by Structure 5.0 and later. We strongly recommend that you back up your data before upgrading. For more information, see Backup Format Version Change.

2.2. Horizontal Scrolling

To make it easier to work with multiple columns and/or larger column widths, you can now enable horizontal scrolling within your structure. When Horizontal Scrolling is enabled, you can add columns beyond the width of your viewing pane and navigate between columns using a convenient horizontal scrollbar.

Documentation: Horizontal Scrolling

2.3. Work Logged by User, Group or Role

The Work Logged column has been updated so time spent on an issue can now be calculated for a specific user, group, or project role.

Documentation: Work Logged Column

2.4. Automatic Maintenance Scheduling with Crontab

Automatic Structure Maintenance now supports flexible scheduling with crontab.

Using standard crontab formatting, you can customize your maintenance schedule to request that tasks run only on certain days or during certain times, process multiple backups each day, specify exact times down to the minute and more.

Documentation: Automatic Structure Maintenance

2.5. Other Changes

Other changes include:

• Structure now supports hidden issue links
• Several user interface changes were made to match Jira 7.10 graphical changes and improve accessibility

3. Supported Versions

Structure 5.0 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–4.6. Structure.Testy extension, Colors, Structure.Pages, Structure.Gantt and integrations with third-party apps should continue working normally.

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 app, either from Atlassian Marketplace or from Download page.
2. 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 "Structure" top-level menu.
3. If you have Structure.Pages installed, make sure you've upgraded to version 1.3 or later, both on Jira and on 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 Confluence upgrade to version 6.1 or better is recommended.
4. Monitor catalina.out or jira-application.log for log messages from Structure.

4.2. Upgrading Structure

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

Upgrade procedure from versions 3.x–4.6 is simple:

1. Consider backing up Jira data. Use Administration | System | Backup System. (If you have a large instance and have proper backup strategy in place, you may skip this step.)
2. 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 "Backup History" option to avoid long backup process.

3. Install the new version of the plugin.

4. 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.

5. Enterprise Deployment Notes

Structure 5.0 introduces the ability to manually adjust generated content and improves the performance of the Sub-Task extender. The changes in the Automation sub-system can be particularly important for larger installations and Jira Data Center instances.

5.1. Controlling Manual Adjustments

Manual adjustments are disabled by default for new and existing structures, so they shouldn't immediately affect Structure's behavior and performance.

Structure's permission system is used to control who has access to manual adjustments:

• Enabling manual adjustments for a structure requires Control permission for that structure.
• Any user with the permission to create structures can create a new one and enable manual adjustments for it.
• Edit permission is required to add and modify manual adjustments if they are enabled.
• Control permission is required to remove all manual adjustments for a structure.

Documentation: Structure Permissions, Changing Permission to Create New Structures.

In addition to permissions, there are configurable limits on the number of manual adjustments:

• 200 adjustments per user action, controlled by the system property structure.gfs.manualAdjustments.maxAdjustmentsPerAction
• 2000 adjustments per structure, controlled by the system property structure.gfs.manualAdjustments.maxAdjustmentsPerStructure

Finally, manual adjustments can be disabled for the entire Jira instance by setting the structure.gfs.manualAdjustments.enable system property to false.

Documentation: Advanced Configuration with System Properties

5.2. New Database Table for Manual Adjustments

We have added a new table named AO_8BAD1B_MANUAL_ADJUSTMENTS to the database schema. This table stores primary data (not stored anywhere else in Jira).

The table contains one row for each structure with manual adjustments. The total amount of data stored depends on the number of adjustments and the complexity of the structure, however, a rough estimate would be on the order of 100 characters per adjustment.

The data from this table is exported along with other Structure data when you do Structure Backup in a human- and machine-readable form. The table is also exported along with all Structure data during Jira backup.

5.3. Backup Format Version Change

In Structure 5.0 we had to change the backup file format version due to the backwards-incompatible changes required by the introduction of manual adjustments. This means that previous versions of Structure will not be able to restore data from backup files created by Structure 5.0 and later. Because of this, we strongly recommend that you back up your data before upgrading.

However, if you want to downgrade to an earlier version, you can use the procedure outlined below to restore Structure data from a 5.0 backup file:

• Unpack the XML backup file from the ZIP archive created by Structure.
• Change the version attribute in the <structure-backup> element from "5.0" to "3.3".
• Delete all <manualAdjustments> elements from the XML.

Then you can restore directly from the modified XML file; you do not have to pack it into a ZIP archive.

5.4. Sub-Task Extender Performance Improvement

The Sub-Task extender has to check whether each issue in its scope is a sub-task or a regular issue. Previous versions of Structure relied on JQL to perform issue type checks, and on large Jira instances with hundreds of issue types these JQL queries caused significant performance impact. In Structure 5.0 we have changed the Sub-Task extender to read issue types from the Lucene index directly, instead of using JQL. We have also improved caching, so sub-task extenders are now better able to reuse the results of issue type checks done by other sub-task extenders.

5.5. Testing on Staging Environment

The introduction of manual adjustments required extensive changes throughout the Automation sub-system, so we advise you to perform load and stress testing in a staging environment before you upgrade. You can try the following scenarios:

• If you have large structures (10,000 issues or more) built by generators, especially sub-task extenders, try opening those from a number of client computers using different user accounts.
• Make some changes to Jira issues that would cause these structures to regenerate – change field values, add or remove links, change sub-task parents.
• Make changes in the structures that would be processed by generators – move issues to different groups, move linked issues and sub-tasks to different parent issues.
• Create a new structure and add manual adjustments to it. For example, you can rearrange a flat list of issues added by a JQL inserter into a hierarchy, or move the issues into several manually added folders.

Watch the log files for errors and warnings while running these experiments.

Need help or have questions? Contact Tempo Support.