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 that 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 from 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.

Priority schemes

• Jira 7.6.0 introduced priority schemes. They are supported, both for export and import, since version 2.2.4 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 occurs due to an import, the simulated configuration import will display the following warning message:

^{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 in any Jira instance.

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 that does not exist in the new workflow assigned to the issue by the draft scheme, this automatic migration is not possible. 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 and aborts the import.

• 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 with 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.

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 (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 to choose one of these options:

• 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 PCJ extension that supports the affected workflow extensions; see our integration toolkit page.

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 with the new password (unless the user does not have an email address). Users can then login and change their password.

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

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

• Users will only be exported if they are referenced by project configuration objects or issue data.

Groups

• Groups are not automatically exported simply because a user who is a member of that group is exported. A more direct link with the project is required (for example, the group is referenced by one or more permissions 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.

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 have a status that 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 that is being configured has versions in Jira that do not appear in the XML file, these versions are not removed but archived to prevent issues that 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 that are shared with one or all the roles of any of the exported projects are exported. You can 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 to 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 are described in Atlassian’s Advanced searching page, with the following exceptions:

    • IDs that identify users (Reporter, Assignee, etc.)

    • Use of IDs in the 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 “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 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:
  
  

  Open

  

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 choose 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 integration toolkit page.

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 the 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 Jira Software to be enabled for the Jira instance.

• 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 the main filter will be chosen as the target for the new configuration.

Issue links

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.