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.
Apart from this web page, you can also use these summarized PDF guides that cover the basics of the two use cases explained below.
This PDF explains how to promote configuration changes from a staging/development environment to production:
And this one, explains how to migrate projects to a different instance:
Project Configurator can help you in two different use cases:
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!
Project Configurator limitations are detailed here.
We are going to explain how to use Project Configurator in its two main use cases.
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.
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:
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.
Congratulations! If you have followed the previous steps, you have just transferred successfully your first configuration across JIRA instances.
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.
If you want to know more about the functionality of Project Configurator, have a look at these links: