Project Configurator for Jira Server and DC

How Project Configurator Works

This section explains the operating principles of Project Configurator.

Handling Complete Projects

In order to export or import complete projects (i.e., their configuration, issue data, and attachments), Project Configurator internally follows the same process of moving a project to another instance as in versions 1.X of Project Configurator, with one difference that improves its performance: the XML backup excludes data for projects that are not exported.

You can view the export and import of complete projects in version 2.X and later as a wrapper that automates the process for the user, providing a simpler, more convenient solution and saving a large amount of work. This has some implications, though:

  • Export and import of complete projects are always done in two steps: first configuration, then data and attachments. This will be more evident to the user if the configuration step fails for any reason; then the data step will not be performed. In the import, the user has the choice to make the app first run a simulated configuration import to assess the possible impact of the configuration changes on other projects in the target instance.

  • The app 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 app relies on the name of objects, with a few 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 another object. For example, options are identified by their name only among the options existing within a custom field configuration.

Minimum Changes

When loading a configuration, the app 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, suppose there is a user in the XML file with name "John" whose full name is "John Smith" and whose email address is "john@somethng.com". If 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 unchanged the user’s name and full name.

  • When an object has a set of dependent objects, the app will perform the minimum number of removals and additions in the dependents, so 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, the app exports the project configuration, including the configuration of 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 is self-sufficient, in the sense that it contains all necessary information to replicate the project in another instance of Jira.