Document toolboxDocument toolbox

This article is for Data Center. Visit Cloud

Upgrading and Downgrading

Owned by Jaramy Conners
May 16, 2024
3 min read

Upgrading

To upgrade Structure 3.0 or later:

  1. 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.)
  2. Back up Structure data. Use Administration | Structure | Backup Structure. See Backing Up Structure for details. If you have a lot of structures and a large Jira, consider turning off the "Backup History" option to avoid a long backup process.

  3. Install the new version of the plugin.

  4. Check Structure extensions. If you are using Structure.Testy, Structure.Pages, Structure.Gantt or other extensions, they may become disabled. In this case, you need to either upgrade them too (it might be a compatibility requirement) or enable them manually in the Add-on Manager. If they fail to enable, reinstall them (uninstall and install again).
  5. Check plugins that integrate with Structure. As with extensions, make sure they are enabled and upgrade/reinstall as necessary.
  6. 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.

For more specific instructions, please check the Release Notes for the version to which you wish to upgrade. 

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

Downgrading

Reverting Structure to an older version is not always possible, because newer versions can modify the database, making it incompatible with older versions.

Simplified Downgrade

A simple downgrade is possible if the database schema hasn't changed. Check the Release Notes for the version you are downgrading from and look for a downgrade advisory. Proceed only if you have indications that it is safe to downgrade to the specific version you have in mind.

  1. Uninstall Structure. This step is required, because Add-on Manager will not install an earlier version over a later version.
  2. Install the version that you need.
  3. Check Structure extensions and integrating add-ons. See the steps in the Upgrading section above.
  4. Monitor catalina.out or jira-application.log for warnings or errors. This is especially important with this kind of downgrade, because some errors may be subtle and not visible to users!

Reliable Downgrade

Reliable downgrade requires a Structure backup file and manual access to the database.

  1. Create a Structure backup using Administration | Structure | Backup Structure. 
    1. Backup files are backward / forward compatible along Structure 5.x series. To downgrade to an earlier version, see Downgrading to Structure 3.0 - 4.6. Note: it is not possible to downgrade to Structure 2.x using a 3.0 or later backup file.
    2. You can also use a previously created backup file. Note that all data will be rolled back to the state when the backup file was created.
  2. Uninstall Structure.
  3. Double-check you have the backup! You are about to delete all Structure data.
  4. Manually access your database using database tools. Drop all tables that start with AO_8BAD1B_. If after that you have other objects starting with that prefix, drop them too.
  5. Install the previous version of Structure.
  6. Use Administration | Structure | Restore Structure to populate the data from the backup file.
  7. Check Structure extensions and integrating add-ons. See the steps in the Upgrading section above.
  8. Monitor catalina.out or jira-application.log for warnings or errors.

Creating a backup and restoring from backup may require considerable time. If you want to speed up the process and you don't need the history of structure changes, turn off the option "Include History" when creating a backup.

Downgrading to Structure 3.0 - 4.6

If you are using Structure 3.x or 4.x: follow the upgrade instructions above.

If you are using Structure 5.0 or later: 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.

To downgrade to an earlier version, 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.