Responsible change management

Owned by Rosen Marinkov
Last updated: May 21, 2024 by Stanley Neychev
4 min read

On this page:

Responsible change management

This use case depicts a process where a Jira System Administrator wants to promote configuration changes from a development instance to a production instance. The methods in this scenario can apply to any scenario where you want to apply only configuration changes. If you are considering how this use case represents your migration goals, it is assumed that you understand how Project Configurator handles project configurations and data. It is also assumed that you are a Jira System Administrator with good knowledge of the setup and state of your instances.

Scenario

Suppose you have a development instance (let’s call it DEV) where some changes have been made to the configuration of some projects. End users have seen and approved these changes, and you now want to transport these changes to your production instance (let’s call this one PROD).

Prerequisites

  • Verify that Project Configurator supports the objects that you would like to migrate. Supported objects are listed in our Supported object types and Support for third-party applications pages.

  • The same version of Project Configurator is installed on both instances. If not, then the version on your target instance should be more recent than your source. You must have a licensed version to complete an import on a production instance.

  • Any apps used to configure objects in the source instance must also be installed on the target, ensuring the versions are the same.

  • Your Jira locale and language are the same for both the source and target instances.

  • It is a suggested best practice that your Jira versions be the same for both the source and target instances.

Instance setup before an export

  • Run the object dependencies report on your source instance. This gives you visibility of where objects are used or referenced by other objects in your configuration. You can use this information to clean up your instance and to help you make the best choices for your export options.

  • Ensure that the naming schemes for user accounts are consistent between the source and target instances. You should not have the same user accounts with different user names, e.g., jsmith and jan.smith. If you are using an external user directory such as LDAP or Active Directory, ensure that these users exist in the target instance before the migration.

  • If you are cleaning your instance before export, you can use the Jira built-in XML backups to first back up your source instance.

Exporting

  1. Open your DEV Jira instance.

  2. Select Add-ons from the Jira Administration menu, then select Export Projects under Project Configurator in the left sidebar.

  3. Make your selection (select multiple projects using the Ctrl or Command keys) on the Export Projects page. To export all projects, select the Select All Projects checkbox.

  4. Choose Configuration Only from the Export Mode options.

  5. An export file name is created for you. You can change this to something more memorable if you wish.

  6. Select any required changes to the default export options. It is worth noting the default settings will work well for 90% of exports. You may also save your configuration options for future export tasks.

  7. Click Export Projects. The app downloads an XML file for the selected projects.

  8. Save the file in an easy-to-remember, easy-to-find location.

Instance setup before an import

  • Make a full backup of your target instance.

  • Perform the configuration promotion out of office hours. The larger the amount of data, the longer the process takes. This could mean running the process over multiple days and splitting your projects across multiple export/imports.

  • Disable Outgoing Mail to not spam users.

  • Run a simulated import and verify the import will make the changes you expect. This report helps you visualize which objects will be created, modified, or result in errors. You can then disable any actions you do not want to apply. You can also investigate any errors and make any necessary changes to the target instance. At this stage, you may discover that you need to resolve issues in the source instance and build a new export file. You can review our troubleshooting articles in the Project Configurator Knowledge Base to help you anticipate and resolve some common errors.

  • Perform the import on a test instance before moving your changes to a live environment.

Importing

  1. Open a Jira session in the PROD instance.

  2. Select Add-ons from the Jira Administration menu, then select Import Projects under Project Configurator in the left sidebar.

  3. Click Browse and locate the XML file you exported from DEV on the Imports Projects page.

  4. Click Import Options to refine what to import. See Import options for details on each option.

  5. Select the Run a Simulated Import option. This is highly recommended to allow you to test the import prior to committing the changes to your production instance.

  6. Click Import Projects. This launches a simulated configuration load. The results page shows a simulation of the operations that would be performed on the PROD instance when that configuration file is imported. As it is a simulation, none of those changes have actually been applied.

  7. Take some time to review this information and check if those changes are aligned with what you expect. If everything is fine and you do not find any unexpected changes, you can launch the actual import.

  8. Click Apply Configuration. Once the import has run, you will see the final import report. This has the same format as the simulated report, making it easy for you to understand what changes were implemented.