How it works

Following the acquisition of Awnaba Software by Adaptavist. All documentation for Project Configurator has moved to the Adaptavist Documentation Confluence Instance. Please be sure to update your bookmarks.

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 follows internally the process described in this page, 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 that process for the user, so that it provides a simpler, more convenient solution and saving a large amount of work.This has some implications:

Export and import of complete projects is always done in two steps: first configuration and 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 a choice to make the plugin run first a simulated configuration import, in order to assess possible impact of the configuration changes on other projects in the target instance.
The plugin uses internally functionality of the JIRA Project Import Tool, thus inheriting some of its limitations and strengths.

Object identification.

In order to identify corresponding objects across different instances of JIRA, the plugin 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 (aka "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 more information here.
Filters are identified by their owner name and the filter's name.
Dashboards are identified by their owner 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 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 plugin will apply the minimum set of changes that will make the configuration in JIRA equivalent to the configuration described in the XML file. This means that:

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, suppose there is a user in the XML file with name "john" whose full name is "John Smith" and whose email address is "john@something.com". If a user already exists in JIRA with name "john" and full name "John Smith" but with a different email address, the plugin 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 plugin 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, the plugin exports the project configuration, including the configuration of:

Other objects that are part of the project: versions, components and members of project roles.
Global objects that are 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 that 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 file projectConfig.xsd (this file is included in the plugin jar).
When an XML element has children with the same types (for example, <customField> elements under <customFields>) 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 such subelement. When children elements are ordered by their own value, in the table appears as order by "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> are 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	mamberGroup	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 represent 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
column (inside Agile boards)	status	own value

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