How Project Configurator Works

Owned by Rosen Marinkov
Last updated: May 08, 2024 by Stanley Neychev
3 min read

On this page:

Handling complete projects

When exporting or importing complete projects (i.e., their configuration, issue data, and attachments), the XML backup excludes data for projects that are not exported.

You can consider the export and import of complete projects as a wrapper that automates the process for the user, providing a simple, convenient solution that reduces a large number of manual tasks, but consider the following implications:

  • Export and import of complete projects are always done in two steps: first configuration, then data and attachments. This becomes more evident if the configuration step fails for any reason. In that case, the data step will not be performed. When performing an import, you should always select to option to run a simulated configuration import to assess the possible impact of the configuration changes on other projects in the target instance.

  • Project Configurator uses the Restore Project from XML Backup feature, therefore inheriting some of its limitations and strengths.

Object identification

To identify corresponding objects across different instances of Jira, Project Configurator relies on the name of the objects, with the following exceptions:

  • Projects are identified by their key;

  • Issue types are identified by their name and type (i.e., whether they are standard or sub-task);

  • Custom fields are identified by their type and name;

  • Filters are identified by their owner’s name and the filter’s name;

  • Dashboards are identified by their owner’s name and the dashboard’s name;

  • Boards are identified by their type (Scrum or Kanban), name, and main filter.

The object context is also considered for those objects that are part of (or are children of) other objects. For example, options are identified by their name only among the options existing within a custom field configuration.

Minimum changes on import

When importing a configuration, Project Configurator applies the minimum set of changes to make the configuration in Jira equivalent to the configuration described in the XML file. This means the following:

  • If the corresponding object already exists in Jira, it will be modified instead of creating a new one.

  • Only those properties of an object that are different between the XML file and Jira will be changed.

For example …

You have a user in the XML file with the name "John", whose full name is "John Smith", and whose email address is "john@something.com". However, you have a user that already exists in your Jira with the name "John" and full name "John Smith" but with a different email address. Project Configurator will only modify the difference in the email address, leaving the user name and full name unchanged.

  • When an object has a set of dependent objects, Project Configurator will perform the minimum number of removals and additions in the dependents so that the final set of dependent objects in Jira is equivalent to the set in the XML file.

Selection of objects to export

When exporting a project configuration to XML, Project Configurator exports the project configuration, including the following:

  • Other objects that are part of the project: versions, components, and members of project roles

  • Global objects referenced by the project configuration, either directly or indirectly. For example, if a project uses a workflow scheme, its configuration will be described in the XML file. The workflows used by the scheme will also be included, as well as statuses, event types, screens, or fields used by any of the workflows.

  • All priorities, resolutions, issue link types, and project roles are always exported, as they are used by projects throughout Jira without requiring an explicit relationship.

The goal is that the configuration file contains all of the necessary information to replicate the project in another instance of Jira.