Project Configurator for Jira Server and DC

How Project Configurator Works

This section explains the operating principles of Project Configurator.

Handling Complete Projects (new since version 2.0)

In order to export or import complete projects (i.e., their configuration, issue data, and attachments), Project Configurator internally follows the 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 functionality of the Jira Project Import Tool, thus 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 (since version 1.0.8).

  • Custom field contexts, or custom field configuration schemes, are identified by their name, except when the Smart custom field contexts feature is enabled. In this case, they are identified by the set of projects where the context applies. See Smart Custom Field Contexts for more information.

  • 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

  • Agile 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 objective 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.

Order in the XML Configuration File

The exported XML file is always ordered following the same rules. The goal is to facilitate comparison of configuration files so they can be used as a tool for detecting changes to configurations in Jira.

Rules for Ordering

  • When an XML element has children of different types, their relative order is defined by the schema in the projectConfig.xsd file—​this file is included in the app jar.

  • When an XML element has children with the same types—​for example, <customField> elements under a <customFields> page—​the children are ordered by the value in one or more subelements, as explained in this table. If a child element does not have one of the subelements given in the table, it would be ordered later than another child that does have a specific subelement. In the table, when children elements are ordered by their own value, they appear in the Order By column as "own value."

Parent Element

Children Elements

Order By

projectRoleMembers

projectRoleMembership

name

versions

version

sequence

components

component

name

projectRoleMembership

memberUser

own value

projectRoleMembership

memberGroup

own value

users

user

username

groups

group

name

projectRoles

projectRole

name

issueTypes

issueType

name

customFields

customField

type, name

fieldConfigurations

fieldConfiguration

name

screens

screen

name

screenSchemes

screenScheme

name

priorityConfiguration

priority

sequence, name

resolutionConfiguration

resolution

sequence, name

statusConfiguration

status

name

issueLinkConfiguration

issueLink

name, style

eventTypes

eventType

name

workflowEntries

workflowEntry

name

permissionScheme

permissionHolder

permission, holder.assignee, holder.group, holder.groupField, holder.projectLead, holder.projectRole, holder.reporter, holder.user, holder.userField

issueSecurityScheme

issueSecurityLevel

name

issueSecurityScheme

permission

level, permittedTo.assignee, permittedTo.group, permittedTo.groupField, permittedTo.projectLead, permittedTo.projectRole, permittedTo.reporter, permittedTo.user, permittedTo.userField

notificationSchemeType

notificationReceiver

event, receiver.allWatchers, receiver.assignee, receiver.componentLead, receiver.currentUser, receiver.emailAddress, receiver.group, receiver.groupField, receiver.projectLead, receiver.projectRole, receiver.reporter, receiver.user, receiver.userField

projectRole

defaultUser

own value

projectRole

defaultGroup

own value

screen

screenTab

position

screenTab

fieldScreenLayoutItem

position

issueTypeScreenScheme

mappingScreenSchemesIssue

issueType

screenScheme

mappingOperationsScreens

operation

fieldConfigurationScheme

mappingFieldConfigIssueTypes

issueType

workflowScheme

mappingIssueTypes

issueType

fieldConfiguration

individualFieldConfig

fieldName

customField

customFieldConfigScheme

name

customFieldConfigScheme

context

projectContext, projectCategoryContext

customFieldConfigScheme

applicableIssueType

issueType

customFieldConfigScheme

config

name

config

option

parentOption, sequence

defaultValue

singularValue

EXCEPTION: <singularValue> is not guaranteed to be ordered; instead, they maintain the order they have in Jira, as it is relevant in some cases (for example in cascade select custom fields)

user

property

key

group

memberUser

own value

group

memberGroup

own value

issueTypeScheme

issueType

own value

filters

filter

author, name

filter

sharedWith

type, name

columns (inside a filter)

field

EXCEPTION: <field> elements maintain the order they have in Jira, as that order represents the order of columns shown when the filter results are displayed in the issue navigator

scrumKanbanBoards

scrumKanbanBoard

name, type, mainFilter

scrumKanbanBoard

administratorUser

own value

scrumKanbanBoard

administratorGroup

own value

workingDays

workingDay

Natural order of weekdays, starting at Monday

workingDays

nonWorkingDay

Increasing date order

All other children elements that are part of exported Agile boards (e.g., quick filters, columns, etc.) maintain the order they had in Jira, as that represents the order configured by the board administrator.