Project Configurator for Jira Server and DC

How Project Configurator Works

This section explains the operating principles of Project Configurator.

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 amount 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; then 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, the 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 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 which are different between the XML file and Jira will be changed. For example, where a user in the XML file with name "John" whose full name is "John Smith" and whose email address is "/john@something.com". and a user already exists in Jira with name "John" and full name "John Smith" but with a different email address, the app will only modify this 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 referred by the project configuration, either directly or indirectly; For example, if the 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.