Getting started guide

Following the acquisition of Awnaba Software by Adaptavist. All documentation for Project Configurator has moved to the Adaptavist Documentation Confluence Instance. Please be sure to update your bookmarks.

Is this your first contact with Project Configurator? Then, you have come to the right place. This page will show you the basics of this plugin and how to start using it.


Project Configurator can help you in two different use cases:

  1. You want to move some projects from on JIRA instance to another.
  2. You have configured new projects or made changes to the configurations of existing projects in a development instance, and want to transfer those changes automatically to the production environment (needless to say, the issue data in production must be kept as it is!)

Depending on which one of these use cases you need to cover, the plugin can export and import users, groups, roles, custom fields and its configuration schemes, workflows and workflow schemes, permission, notification and issue security schemes, filters, dashboards, Scrum and Kanban boards, issue data, attachments, etc. You can see the full list of supported object types here.

If you need more details about use cases where Project Configurator can be used, have a look at our "cookbook".  Actually, most of those use cases were proposed by users of Project Configurator, so if you have another idea, please leave a comment or send us a line by email!

What it does not do

Project Configurator limitations are detailed here.

Step by step

We are going to explain how to use Project Configurator in its two main use cases.

Starting point

You must have JIRA system administrator permission in all instances where you are going to use Project Configurator.

It must be installed on both instances. If it is the first time you install a plugin, follow the instructions in this page. Project Configurator is a standard "Plugin 2" type add-on, and "Paid-via-Atlassian", so the installation and licensing process is the same one used by most plugins in the Atlassian Marketplace.

Carrying configuration changes from development to production

Suppose you have a development instance (let us call it DEV) where some changes have been made to the configuration of some projects. End users have seen and approved these changes and now you want to to transport these changes to your production instance (which we will call PROD).


Open a session at DEV instance.

Go to the add-on administration page. In the menu on the left, in the section for "PROJECT CONFIGURATOR" there is an entry labeled "Export selected projects".

Click on it and you will be taken to a page where you can select the projects you want to export. Click on the required projects (on Windows use Ctrl key to select more than one, or Command key on a Mac). Select "Configuration only" below the project list and click "Next".

In the next page click the button "Export project configuration" and the plugin will download a XML file with the configuration for the selected projects. Store the downloaded XML file at a known location.


Now, open a JIRA session in PROD. Go to the add-on administration page. In the menu on the left, in the section for "PROJECT CONFIGURATOR" there is an entry labeled "Import project configuration". Cilck on this entry and you will navigate to a page where you can specify which configuration file you want to load:

This page shows a form with several elements:

  • A notice about warnings before importing configurations (only if you have never launched an import before). If it is your first time, take a minute and have a look at this advice.
  • A button that lets you select the XML file that will be imported
  • Several other options. Now, we are going to ignore most of them, just follow the next steps.

Using the button with the "Project Configuration File" label, browse your file system and select the XML file you exported from DEV. Make sure the "Apply changes?" radio button is not clicked. Then. press the button at the bottom of the form, with the text "Import project configuration". This will launch a simulated configuration load. You will get a result page like this:

This page shows a simulation of the operations that would be performed on instance PROD when that configuration file is imported. As it is a simulation, none of those changes have actually been applied. Now, take a minute 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 change, then you can launch the actual import. Go back to the "Import project configuration" page, select the XML file and enable the radio button "Apply changes?". Finally, click the button at the bottom of the form and you will see how the configuration is imported into PROD.

That's it!

Congratulations! If you have followed the previous steps, you have just transferred successfully your first configuration across JIRA instances.

Moving a project to another JIRA instance

Suppose you have a group of projects in a JIRA instance called SOURCE. You want to move this group of projects to a different instance, which we will call DEST, where none of those projects exist. The original projects in instance SOURCE will be abandoned (for example, because after they are moved to DEST, instance SOURCE will be shutdown as in the case of merging JIRA instance SOURCE into DEST).

Read this first!

Import of complete projects is subject to these limitations. Read them before starting this task.


Just follow the same steps explained for the previous use case, but after selecting the projects you want to move, select the radio button "Configuration and data". Click "Next" and in the next page click on "Export complete project".

After some time, that depends on number, complexity and size of the selected projects, you will get to a new page that displays a summary of the export and tells you the location in the SOURCE server where the exported file has been placed.

Note down that location and the filename, you will use them for the next step.


First of all, create a folder called projectconfigurator under the JIRA_HOME/import in the DEST JIRA installation. Then copy the zip file created in the export step to that folder.

Now open a JIRA session as a system administrator on the DEST instance, go to the add-on page and click on "Import complete project", which is on the left menu.

In the next page, enter into the text box "Project File" the name of the exported file (include the ".zip" extension). Select the option "Run first a simulated configuration import". Click the button "Import complete project" at the bottom.

Next you will see a page showing the configuration changes that will be applied to DEST instance, in order to bring these projects into it. The content of this page will be very similar to the simulated import shown above. The only relevant difference in this case is a message that requests you to verify the proposed changes and a "Next" button:

Review those proposed changes and, if you are happy with them, click on "Next" button. Wait some time and...


When the process is finished all that group of projects is in instance DEST, including their configuration, issues and attachments.

See also

If you want to know more about the functionality of Project Configurator, have a look at these links:

How to use it

How it works

Skipping import of some object types

Smart custom field contexts

Did something go wrong?

Just file a ticket at our Customer Portal, or send us an email to our support account at