Project Configurator for Jira Server and DC

Best Practices for Importing

There are several general rules to follow to have the best experience and overall general ease of importing projects using Project Configurator.

Safety Measures When Importing

Importing a configuration file or a set of projects with their data into Jira may change many things in the Jira configuration. It is likely to also change global objects (schemes, workflows, custom fields, etc.) that may be used by other projects. Given this potential impact on the target projects and other projects in Jira, it is highly recommended to follow safety measures.

Before loading a full project or configuration-only import into a production database, you should do the following:

  • Make a full backup of the database. If importing complete projects, consider backing up the attachments, too (as the import will add attachments for the new projects being imported).

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

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


After importing configurations, it is highly recommended to reindex your database. This is not needed if importing complete projects, as the data import stage will automatically launch a reindex.

Email Notifications

When the app creates new users that have an email address, it will request Jira send them a notification email. Take into account these notifications are requested when the users are created, even if later the import fails and everything is rolled back. If you do not want these emails sent at the moment of user creation, consider disabling the email queue before the import. You can do this by clicking the Outgoing Mail link on the system configuration page. You will arrive at a page with a Disable Outgoing Mail button in the top right corner.

Instance Locked During Migration (version 2.0 >)

If you import a complete project—​i.e., not only its configuration, but also issue data and attachments—​while data is being imported, your instance will be locked for a period of time. This period will last different amounts of time depending on the size of imported data. So, it makes sense to import projects out of office hours or, at least, warn users in advance that the system will not be available for some time.

Follow a Defined Process

Promoting 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 some best practices and avoid common pitfalls. We recommend reading the Migrating Data with Adaptavist page that we prepared in collaboration with Atlassian. It describes the recommended process for each of those three situations. We also recommend you refer to the Project Configurator Checklist as a quick reminder of all the import prerequisites and tasks 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, it is good practice to manually clear these files before generating another export file.