Index

This documentation relates to version 4.0 of the Structure Plugin for JIRA and subsequent patch releases. Documentation for previous versions is available via Documentation Index.

Skip to end of metadata
Go to start of metadata

5th of April, 2016

Structure 3.0 is the biggest, most extensive and most awaited update of the Structure add-on. It introduces a lot of amazing features that can help you bring your command of JIRA to the next level.

Important! Upgrade from Structure 2.x requires additional manual operations.

This version is a massive overhaul of Structure. If you're using Structure 2, please pay attention to these Release Notes, especially to Upgrade Instructions.

Download Structure 3.0 and Extensions
Structure 3.0 Demo Server 
Structure 3 Quick Start Guide

 

1. Structure 3 – a Different Experience

Structure 3.0 is very different from previous versions of Structure. While the main concept – "structure" as a hierarchical list of things – remains, many things changed and a lot of features were added. We have put a lot of thought into expanding the scope of the product and rebuilt Structure almost from ground up.

After upgrading and finding your way around new user interface, you should be able to work with Structure 3.0 in the same way you worked with Structure 2.x. However, to take advantage of the new features such as Automation, some learning will be required. When you have Structure 3 installed, check out menu Structure | Get Started for a crash course on most important features. The Structure 3 Quick Start Guide has more details and is a recommended reading.

2. Structure 3 Highlights

  • Multi-parent (same issue can be at multiple locations in any structure)

  • Folders (special non-JIRA folders for containing issues in structures)

  • Issue sorting and grouping

  • Structures within structures

  • Automation (automatic structure generation, an alternative to synchronizers)

  • Revamped user interface
  • JIRA Data Center compatible

Full description of all new features would be too much for this document. We invite you to take a look at the Structure 3 Quick Start Guide or explore the add-on yourself (make sure you stop by Structure | Get Started menu).

3. Notes on Structure 2 Features

Please read carefully: if you're relying on some of the changed features, you need to make sure that after upgrade everything works as expected.

3.1. Synchronizers

Synchronizers were remade. They generally do the same things as before, but we upgraded their logic so they can take advantage of the new architecture. For example, Links synchronizer can now place an issue in two or more places in the structure, so you will be able to visualize non-hierarchical links structure.

We kept most options, but introduced "Source of Truth", which helps bi-directional synchronizers resolve conflicts. If you're using synchronizers, please revisit all synchronization settings after upgrade.

Synchronizers and Generators

Please note that generators "see" the results of synchronizers' work, but not vice versa. if you'd like to take advantage of the new feature, Automation, and you're using synchronizers, we advise you to start off with a new structure to avoid confusion.

3.2. Other Changes

  • Now an issue may be in several places in a structure. If you're using columns that calculate totals, the columns now have "Exclude duplicates" option, which makes sure that each issue is counted only once.
  • Structure 3.0 does not have separate backup and restore, and there's no migration feature yet too. We'll reinstate these features in one of the upcoming versions.
  • We changed the way Structure treats issues from projects that are not enabled for Structure. Such issues still won't be shown as a part of search result, however, if such an issue happens to be in a structure, it won't be hidden.
  • If a user does not have access to issue A, but has access to its sub-issue B, the user will see "Unavailable item" instead of issue A. (In Structure 2, sub-issue B was elevated up one level to replace A in this case.)

4. Supported Versions

Structure 3.0 and all extensions support JIRA versions from 6.3 to 7.1. 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.

4.1. Browser Support

We now have only partial support for Internet Explorer 9 and 10. There are some known issues, but you may be able to use Structure. If you encounter a problem while using IE9 or IE10, please let us know and we'll advise if it's a known problem or something we can deal with.

If you're using Structure.Testy, you need to install Structure.Testy 2.0. Earlier versions of Testy are not supported.

5. Compatibility Issues

5.1. Other JIRA Plugins

If you’re using a plugin that integrates with Structure 2.x, most likely it will not work with Structure 3.0. Here’s the suggested course of action:

  • Structure.Testy – we are releasing Structure.Testy 2.0, which is compatible with Structure 3.0. If you’re using Testy, please upgrade Testy to the new version as well.
  • scheduled-sync, status-bar-column or other complimentary plugins by ALM Works, published as a part of Structure 2.x documentation – these plugins will not work with Structure 3.0. We will release updated versions later, along with the Structure 3.0 final release. If you need one of those plugins urgently to try out Structure 3, please contact us.
  • Custom plugins that integrate with Structure, whether developed by ALM Works or an independent vendor – these plugins will most likely not work with Structure 3.0 and will require additional work to be made compatible. For plugins made by ALM Works, please contact us with an upgrade request. If you have your own integrations or a plugin made by an independent contractor, you’ll need information about the new APIs. Feel free to contact support@almworks.com for this.
  • Gantt-Chart for JIRA – if you’re using this plugin and use its integration with Structure, you might want to hold off the upgrade until a compatible version is available.

5.2. REST API

REST APIs also have changed in Structure 3.0. If you have any reporting scripts that connect to Structure via REST, they most likely will stop working. At this moment, the new API is not published — please contact us at support@almworks.com and we’ll be happy to help you upgrade your scripts.

5.3.  Remote Gadget Not Available

If you're using Structure dashboard gadget in Confluence, it is currently known to have issues. We'll be reviewing this functionality and possibly providing alternatives after Structure 3.0 release. 

6. Changes in API

In Structure 3.0 we have made massive changes in the architecture of the product to accommodate the new features and lay groundwork for future expansion of the platform. Unfortunately, that means a lot of incompatible changes in the API. Most integrations with Structure 2.x will not work with Structure 3.0.

The new Java and REST API will be published later, closer to Structure 3.1 release. The reason for that is that we’ll need to spend additional time after Structure 3.0 release to stabilize and clean the new APIs and provide sufficient documentation.

Until the new stable API is released, we can provide information about the new API on individual basis. Please feel free to contact us at support@almworks.com if you’d like to integrate with Structure 3.0.

7. Installation and Upgrade

Important: The data from Structure 2.x is not automatically transferred when you upgrade, so you'll need to manually migrate it after installation.

7.1. Installing Structure for the first time

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

  1. Download and install Structure 3.0 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 Startedto 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.

7.2. Upgrading from Structure 2.9–2.11

If you have Structure version older than 2.9, please upgrade to Structure 2.11.2 version first.

  1. Create backup of current Structure data. You can either use Administration | Structure | Structure Backup menu or do a cold backup by copying the whole structure/ sub-directory under JIRA home while Structure plugin is disabled.
  2. Download and install Structure 3.0 add-on, either from Atlassian Marketplace or from Download page. Pick the correct version based on your JIRA version!
  3. 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.
  4. To transfer the data, open Administration | Structure | Export Structure 2.x Data page. It allows you to create a backup zip with all Structure 2.x data, and then opens Restore Structure page, allowing you to immediately import the backup into Structure 3.x database.

    Important: after you press Create Backup, wait for the backup to finish – it might take a while! Do not try to go back and repeat the backup. To see if the backup is still going on, access JIRA home directory, export/ folder, and see if the backup file is growing in size.

    1. Alternatively, you can use Administration | Structure | Restore Structure menu and use any Structure 2.x backup made earlier.
  5. If you have Structure.Testy installed, upgrade to Structure.Testy version 2.0 or later.

  6. Monitor catalina.out or jira-application.log for log messages from Structure.

Unlike previous versions, Structure 3.0 uses the main JIRA database to store its data. After upgrade, your Structure 3.0 database will be empty. Don't panic – all data is intact, but it must be transferred from Structure 2.x database. See the instructions above.

7.3. Upgrading from preview versions of Structure 3.0

If you have installed Structure 3 beta or release candidate, you need to uninstall it first.

  1. Download and install Structure 3.0 add-on, either from Atlassian Marketplace or from Download page. Pick the correct version based on your JIRA version! All data will be safe.
  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. If you have Structure.Testy installed, upgrade to Structure.Testy version 2.0 or later.
  4. If you have a preview of Structure.Pages installed, please contact support@almworks.com for a link to Structure.Pages beta3 version. Earlier versions will not work.
  5. Monitor catalina.out or jira-application.log for log messages from Structure.

7.4. Upgrading "Global Structure"

If you're using "Global Structure" structure, which was created by default in Structure 2.x, you need to make sure that there's an "owner" of that structure. Otherwise, Automation feature will not work there.

  1. Open Structure | Manage Structure.
  2. Find Global Structure and check if it has non-empty Owner.
  3. If it doesn't have an owner, click Configure, and set yourself as the owner.

7.5. Downgrading

If you decide to downgrade to Structure 2.11, you can do so, but any changes made in Structure 3.0 will not be transferred to the previous version.

8. Feedback Is Welcome!

Please let us know what you think about the new Structure! We have grandiose plans for next versions, which now will be coming out frequently, and your feedback is instrumental for aligning our plans with what the users need.

Please write to support@almworks.com or almworks twitter if you have any comments, questions, suggestions or feelings to share!