Guide to importing

Safety measures

Importing either a configuration file or a set of projects and their data could change several things in your target Jira configuration, including global objects such as schemes, workflows, or custom fields that may be used by other projects. We recommend that you follow the safety measures below.

Before importing complete projects or a configuration-only file into a production instance:

  • Make a full backup of the database. If importing complete projects, also consider backing up the attachments since the import will add attachments for any new projects being imported. You can make a backup using Jira’s built-in XML importer located under System Settings on your Jira Administration page.

  • Note any Project Configurator limitations that apply to your configuration changes or project data migrations.

  • Run an import simulation against the intended import file, then verify that the import will do what you expect.

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


After importing configuration changes (the XML file), it is highly recommended that you reindex your database. This is not required if importing complete projects since the data import stage automatically launches a reindex.

Email notifications

When Project Configurator creates new users that have an email address, it requests that Jira send them an email notification. Note that these notifications are requested when the users are created even if the import fails and everything is rolled back. If you do not want these emails sent, disable the email queue in Jira before the import.

Instance locked during migration

If you import complete projects, your instance will be locked for a period of time, depending on the size of the import. The larger the amount of data, the longer the process takes. Limit disruption to your users by performing the migration outside of office hours when possible and announce the planned downtime in advance.

Follow a defined process

Deploying configuration changes, importing projects from another instance, or merging instances of Jira may, in some cases, be complex tasks. Your chances of success will be much higher if you follow a defined and tested process. We also recommend that you refer to the Project Configurator checklist as a quick reminder of our prerequisites and best practices before proceeding with any migration process.

Clear temporary files on failed imports

On successful loading of an import file, Project Configurator clears the temporary export files saved in the temp directory, <JiraInstallDirectory>/temp. If the import process fails, to save space on your local disk, manually clear these files before generating another export file.

See Project Configurator’s import options to learn how you can safely customize the import settings.