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.
See also...
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.