Project Configurator for Jira Server and DC

Specific Information for Some Object Types

This page provides specifics for some of the object types supported by Project Configurator. Reviewing how Project Configurator handles each object will help ensure that your import and export tasks run smoothly.

Field Configuration Schemes

The default scheme System Default Field Configuration is not exported to XML, as it cannot be modified. Projects that use it will not have a fieldConfigurationScheme element in their XML description.

Custom Fields

  • Cascading select fields are supported.

  • Options in custom field configurations are never removed. If an option exists in the target Jira instance and the same custom field configuration in the XML file does not have that option, the app will disable the existing option instead of removing it. This is intended to minimize problems with issues which might include that option in a field value.

  • If a custom field configuration scheme is about to be removed and it has options with associated issues, the app will treat that as an error and abort the import.

  • If the context in a configuration of an exported custom field refers to any project different to the exported project, those other projects will not be exported to XML. When importing this configuration, you should make sure that projects with those keys exist in the target instance or will be created as part of the import. Project Configurator offers an option to automatically create these empty projects during the import.

    Locked custom fields are not exported. This means that, when the configuration is imported, these custom fields will not be created or modified by Project Configurator at the target instance. This is consistent with the expectation that these custom fields are created/configured only by the app or application that created them (for example Jira Agile/Software).

Priority Schemes

  • Jira 7.6.0 introduced priority schemes. They are supported, both for export and import, since version 2.2.4-J7 of Project Configurator.

  • An import may change the priority schemes of existing projects and, as a result, some of the issues in those projects might be left with priorities that are no longer allowed by the new scheme. If this will occur due to an import, the simulated configuration import will display warning messages similar to the following:

Some projects using this scheme have issues with priorities that are not included in the modified priority scheme. Affected issues by priority: {Major=18}
...
There are issues in the project with priorities that are not included in the new priority scheme. Affected issues by priority: {Critical=24}

The first message example is displayed when simulating a change to an existing priority scheme. It means that a total of 18 issues, possibly across several projects, have the Major priority that will be left out of the new scheme configuration. The second message is displayed when simulating the association of a new priority scheme to an existing project. Similarly, it means that 24 issues in that project have the Critical priority that does not exist in the new scheme.

If this import is then applied, those issues will be displayed with a Not available tag, next to their priority. You can then either bulk move them to another priority supported by the new scheme or leave them as they are.

Workflow Schemes and Workflows

Default Workflow and Scheme

The default workflow scheme and workflow cannot be modified in Jira. They are not exported to XML, as they are available any the same in any instance of Jira.

Workflow Scheme Drafts

  • When trying to import a configuration with a workflow scheme, if a scheme with the same name already exists in the destination and is active, the app will create a draft for it and configure this draft according to the information in the XML file. If the scheme already has a draft, the app treats this as an error and aborts the import. It is assumed that the scheme is being modified in the destination and importing another scheme from the XML file would overwrite those changes.

  • If the import option Publish Workflow Drafts is enabled, the import process will try to publish the scheme draft automatically, after configuring it:

If any of the projects using that workflow scheme have issues in a status which does not exist in the new workflow assigned to the issue by the draft scheme, this automatic migration will be impossible. In this case, you need to manually map statuses in the old workflows to statuses in the workflows in the draft scheme.

Workflow Drafts

  • When trying to import a configuration with a workflow, if a workflow with the same name already exists in the destination and is active, the app will create a draft for it and configure this draft according to the information in the XML file. If the workflow already has a draft, the app treats this as an error an aborts the import; the workflow is being modified in the destination and importing another workflow from the XML file would mean losing these changes.

  • If the import option Publish Workflow Drafts is enabled, the import process will try to publish the draft automatically, once it has been configured.

  • If the statuses and steps of the draft do not coincide with those of the original workflow, it is not possible to publish the draft (either automatically or manually). If this happens and the import option Publish Workflow Drafts is enabled, the import trace will display a warning including the error found in the draft.

Resolving this error involves editing the draft until it is compatible with its original, or discarding it.

Workflow Layouts

  • If you are moving configurations between different versions of Jira, not all major versions are mutually compatible. This is detailed in this table:

    info-types-07

    This happens with the default versions of the Jira Workflow Designer Plugin shipped with each version of Jira. It might be possible to fix these incompatibilities by upgrading one or both instances to the same version of the Jira Workflow Designer Plugin, but this has not been tested.

Conditions, Validators and Post-functions

The app supports conditions, validators and post-functions defined in standard Jira plus the following apps:

  • Jira Suite Utilities

  • Jira Misc Workflow Extension

  • Jira ServiceRocket Utilities

  • ScriptRunner for Jira (Behaviours included with this app, see Support for Third-Party Applications)

  • Jira Workflow Toolbox

Workflow extensions defined in other apps might not be imported correctly if their XML descriptor (as obtained with Jira export workflow to XML function) references internal IDs of entities like custom fields, groups, roles, etc. and those IDs are different in the source and target instances. The recommended workaround in these cases is either:

  • Manually edit the XML configuration file and replace the source instance IDs with the corresponding target instance IDs

  • Import the configuration and then edit the workflow in the target instance to fix conditions, validators, and post-functions that are not pointing to the right custom field, group, role, etc.

  • Developers can also create a custom PC extension that supports the affected workflow extensions; see Integration Toolkit for Developers

If you need Project Configurator to handle workflow extensions defined by an app, please raise an issue through our support portal.

Users

  • User passwords are not exported to or imported from XML. When a new user is created, the system generates a password for them. Project Configurator then requests that the system send an email notification (unless the user does not have an email address), with the new password so that the user can log in and change her/his password.

  • The app does not modify the assignment of users to roles in other projects, only in those projects for which configuration is being import.

  • User properties are supported if they are of type string. Properties set from the Jira user interface are prefixed internally by Jira with the string Jira.meta. This prefix appears in the XML file.

  • When the app creates new users, they are created in the first writable directory. This must be considered before importing to an instance with several user directories. By changing the relative order of directories before importing, it is possible to change which directory will host newly created users.

Groups

  • Groups are not automatically exported simply because a user which is a member of that group is exported. A more direct link with the project is required (for example, the group is referred by a permission in the project permission scheme).

  • Users or groups that are members of an exported group will have their configuration exported to the XML file.

  • Groups Jira-users and Jira-administrators have a specific system-wide meaning. Removing users from these groups may cause problems in Jira (for example, users unable to log in). To avoid these problems, the app does not remove users or child groups from these groups. Therefore, following an import, members of these groups can be a superset of the members defined in the XML configuration file. The same protection applies to the groups that control application access: Jira-core-users, Jira-software-users, and Jira-servicedesk-users. For the rest of the groups, following an import, the members are the same as those defined in the XML file.

  • Permission to anyone is represented in the XML file as <group>Anyone</group>. In order to avoid conflicts with this representation, a Jira Administrator should avoid creating a group called Anyone. Note that this is consistent with the Jira user interface, where such a group would also cause a conflict.

Issue Security Levels

  • If an issue security level has associated issues and it is about to be deleted through the import, the app will treat this as an error and abort the import.

Projects

  • When an existing project is assigned a new workflow scheme, the import process will try to migrate existing issues in those projects to the new workflows defined under the new scheme. If any of the existing issues has a status which does not exist in the new workflow, this automatic migration will be impossible. In this case, the import will continue and a warning will be displayed.

Project Components

  • Note that if a project component is deleted during the import, any associated issues will lose their relation to that component.

Versions

  • If the project which is being configured has versions in Jira which do not appear in the XML file, these versions are not removed but archived to prevent affecting issues which might point to those versions.

Filters

  • Filters can be exported and imported including the columns (fields) selected to show in the issue navigator, if the filter has such a column layout selected, and whom the filter is shared with (everybody, a group, all roles in a project, or a specific role in a project).

  • By default, filters are not exported. You must use the export option that enables the export of all filters or only some of them, based on how they are shared with other users. If filters are present in an XML configuration file they will be imported with that configuration, unless you select the export option to ignore them. See Export Options to learn more.

  • Filters without an owner are not supported. If a filter in the imported XML file has no owner defined, the app will treat it as belonging to the user who is launching the import.

  • If a filter is defined in the XML file as being shared with a project (either with all roles or a specific role), that project must either already exist in the target instance or be created as part of the import. The Create Additional Projects import option allows you to automatically create these additional projects. The same applies for the project role if it is shared with members of a specific role in a project.

  • JQL permits the use of IDs instead of names to identify some objects such as versions, components, priorities, resolutions, or custom fields. More precisely, the app supports:

    • The use of IDs to identify custom fields, either in the where clause or the ORDER BY part of the query.

    • All the uses of IDs in filter queries described in Atlassian’s Advanced Searching page, with the following exceptions:

      • IDs that identify users (reporters, assignee, etc.)

      • Use of IDs in field Epic Link

      • Use of IDs in field Sprint

    • The app also supports the use of IDs in predicates about the issue history for all fields with the exceptions just described, in queries like the following:

resolution changed from 3 to 5
  • When the app detects the use of an ID in the query of a filter it is exporting, it replaces the ID with the corresponding name in the exported query. This means, that the original database is not changed by an export operation. If you want to remove IDs in filter queries in the original database, follow the procedure described in our Knowledge Base article, Replacing IDs in Filter Queries in the Same Instance.

  • Filters are identified across instances by their name and the user name of their owner. See the following table for an example of situations when importing a filter:
    info-types-12

Dashboards & Gadgets

  • Dashboards are identified across instances by their name and the username of their owner, the same as filters. See the above table for a few examples.

  • By default, dashboards are not exported. You can use Project Configurator’s export options to enable the export of all dashboards or only some of them, based on how they are shared with other users. If dashboards are present in an XML configuration file they will be imported with that configuration, unless you chose to ignore them using the import option.

  • If a gadget requires a specific app to be installed, you must have the same app and version installed in the target instance. If not, the import will load successfully, but if your user tries to open the dashboard, Jira will show an error for that gadget.

  • All gadgets listed in the Gadgets for Jira Applications are supported. Any other gadget is supported (meaning it will be exported and imported successfully into another instance) as long as it meets either of these conditions:

    1. Its user preferences (configuration) do not refer to other objects by their IDs and the referred objects exist in both instances.

    2. An extension for Project Configurator is available to handle that gadget type. More information on creating extensions for Project Configurator can be found in our Project Configurator Integration Toolkit.

Missing References During Export

The usual strategy of halting an export if a missing reference is found is not always suitable with gadgets in dashboards. Many dashboards are created by normal Jira users and it would be too time consuming for a Jira admin to fix the references in these dashboards before being able to export successfully. This can be resolved by either of these solutions:

  • If the missing reference is a custom field selected as one of the fields to display in a query (for example, in the Watched issues gadget), Jira safely ignores it and the gadget can be displayed and edited without any warning or error. When exporting, the app will do the same: simply ignore this missing custom field and export the rest of columns configured for the gadget.

  • If the missing reference is required for the gadget configuration to be complete, that user preference will be exported empty and the gadget will be marked as not configured. Once the dashboard is imported into a new instance, when a user tries to view that dashboard, that gadget will be displayed in edit mode, and they can fix the missing reference.

Software Boards

  • Both exporting and importing require that the Jira instance has Jira Software enabled.

  • Software boards are identified across instances by their type (Scrum or Kanban), name and main filter. Please note that it is possible to have several boards in Jira with the same type, name, and main filter, even when they have been created by the same user. This situation is not supported by Project Configurator for Jira. This requires some criteria to determine when two objects in different instances represent the same thing. If there are several boards with the same type, name, and main filter, when exporting, only one of them would be exported. In this case, a warning message is displayed. When importing, the first board found at the new instance with the required type, name, and main filter will be chosen as the target for the new configuration.

If importing complete projects (i.e.their configuration, issue data, and attachments) links between issues that existed in the source instance will be recreated in the target instance, as long as projects for both linked issues are imported. If only one of the projects is imported into the target, the issue link will not be created. However, if the other project is imported later, then the issue link will be created at the moment of this second import.