Specific information for some object types

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 and the same custom field configuration in the XML file does not have that option, the plugin will disable the existing option instead of removing it. This is intended to minimize problems with issues which might have 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 plugin will treat that as an error and abort the load.
• If the context in a configuration of an exported custom field refers to any project different to the exported project, the configuration of those other projects will not be exported to XML. When loading this configuration, it is the user responsibility to make sure that projects with those keys exist in the destination instance or will be created as part of the import. Project Configurator offers an option to automatically create these empty projects during the load.
  
  

Workflow schemes and workflows

Default workflow and scheme

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

Workflow scheme drafts

• When trying to load a configuration with a workflow scheme, if a scheme with the same name already exists in the destination and is active, the plugin 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 plugin treats this situation as an error and aborts the load. It is assumed that the scheme is being modified in the destination and loading another scheme from the XML file would overwrite those changes.
• If the import option "Try to publish 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 has 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 the user would have to map manually statuses in the old workflows to statuses in the workflows in the draft scheme. In this case, the import will continue and a warning will be shown in the load trace like this:

If a workflow scheme draft is left unpublished, either because the import option "Try to publish drafts" was not checked or because it requires status mapping by the user, a special reminder will be shown above the load trace. This reminder will tell the user that publishing the workflow scheme draft is a pending task. It wil include a link that opens (in a new browser window) the JIRA page where the user can map required statuses and click to finish publishing the scheme draft.

Workflow drafts

• When trying to load a configuration with a workflow, if a workflow with the same name already exists in the destination and is active, the plugin 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 plugin treats this situation as an error an aborts the load: the workflow is being modified in the destination and loading another workflow from the XML file would mean losing these changes.
• If the import option "Try to publish drafts" is enabled, the import process will try to publish the draft automatically, once it has been configured. This image shows these steps in the load trace:

If the import option "Try to publish drafts" is not selected, the draft will be left unpublished, but a reminder will be shown above the load trace telling that publishing the draft is a pending task. This reminder includes a link that will open (in a new browser window) the JIRA page where the user can publish the draft workflow manually.

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 "Try to publish drafts" is enabled, the load trace will display a warning like this, including the error found in the draft:

Fixing this problem implies editing the draft until it is compatible with its original, or discarding it.

Workflow layouts

Workflow layouts are supported, starting with version 1.9-X of the plugin. Please be aware of these limitations:

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

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 we have not tested that yet.

• We have detected that sometimes on JIRA 6.0.X, after an import that changes the layout for a previously existing workflow, the new layout is not visible if the administrator clicks on the "View" link at the workflow page (see below image). However, if using the "Edit" link the new layout will be correctly shown.

JIRA users that click on the "View workflow" link (see next image) will also correctly see the new layout:

Conditions, validators and post-functions

The plugin supports conditions, validators and post-functions defined in standard JIRA plus the following plugins:

• JIRA Suite Utilities
• JIRA Misc Workflow Extension
• Customware JIRA Utilities
• Script Runner (only for canned scripts included with this plugin, in its version 2.1.3)
• JIRA Workflow Toolbox (new since version 1.3.2)

Workflow extensions defined in other plugins may not load 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 origin and target instances. The recommended workaround in these cases is either:

• Edit manually the XML configuration file and replace the origin instance IDs with the corresponding target instance IDs
• Load 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

Users

• User passwords are not exported to or loaded from XML. When it creates a new user, the system will generate a new password for him. The plugin will request the system to send an email notification (unless the user does not have an email address), so that the new user can receive it, log in and eventually change her/his password.
• The plugin will not modify the assignment of users to roles in other projects, only in those projects whose configuration is being loaded.
• 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 will appear in the XML file.
• When the plugin creates new users, they are created in the first writable directory. This must be considered before loading 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

• A group will not be exported just 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).
• On the other hand, 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 special system-wide meaning. Removing users from these groups, may cause problems in JIRA (for example, users unable to login). In order to avoid these problems, the plugin will never remove users or child groups from these groups. This means that the members of these groups after the load can be a superset of the members defined in the XML configuration file. On the other hand, for the rest of groups the members after the load will always be 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 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, the plugin will treat this situation as an error and abort the load.

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. This fixes PCP-424. If any of the existing issues is in 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 shown in the load trace like this:
  

Additionally, a special reminder will be shown above the load trace, telling the user that assigning manually the new workflow scheme to the project is a pending task. This reminder includes a link that will open (in a new browser window) the JIRA page where the user can map required statuses and click to finish assigning the new scheme.

Project Components

• Take into account that if a project component is deleted during the load, any associated issue will lose its 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, in order to prevent affecting issues which might point to those versions.

Filters

• Filters can be exported and imported since version 1.4 of the plugin, 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).
• As a default, filters are not exported. The user must navigate to the advanced export page and select an option that enables export of all filters or only some of them, based on how they are shared with other users. If filters are present in a XML configuration file they will  be imported with that configuration, unless the user selects to ignore them.
• Filters without owner are not supported. If a filter in the imported XML file has no owner defined, the plugin will treat it "as if" it belonged 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 exist previously in the destination instance or be created as part of the import. 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, custom fields, etc. This is supported by Project Configurator since version 1.4.1. More precisely, the plugin supports:
  • The use of IDs to identify custom fields, either in the "where" clause or in the "ORDER BY" part of the query.
  • All the uses of IDs in filter queries described in this Atlassian documentation 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 plugin covers also the use of IDs in predicates about the issue history for all fields with the only exceptions just described, in queries like:

• When the plugin 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, as it seems logical. If you want to remove IDs in filter queries in the original database, follow the procedure described here.
• Filters are identifed across instances by their name and the username of their owner. See the following table as an example of different situations when importing a filter:

Dashboards

• Dashboards are identifed across instances by their name and the username of their owner, the same as filters. See the above table for a few examples.
• Dashboards can be exported and imported since version 1.5 of the plugin.
• As a default, dashboards are not exported. The user must navigate to the advanced export page and select an option that enables export of all dashboards or only some of them, based on how they are shared with other users. If dashboards are present in a XML configuration file they will  be imported with that configuration, unless the user selects to ignore them.
• If a gadget requires a specific plugin to be installed, it is the user responsibility to have this plugin installed in the instance where the dashboard will be imported. Otherwise the import finishes successfully, but if the user tries to open the dashboard, JIRA will show an error for that gadget.
• All gadgets listed in this page are supported.
• Any other gadget is supported also (meaning it will be exported and imported successfully into another instance) as long as it meets these two conditions:
  1. Its user preferences (configuration) do not refer to other objects by their IDs, or the user can make the referenced objects have the same ID in both instances (for example, because one instance was cloned from the other when those objects already existed)
  2. The referenced objects are within the list of supported object types by Project Configurator and they are transferred during the same import, or the user can ensure that those objects exist too in the target instance.

Missing references during export

The usual strategy of halting the export with an error message if a missing reference is found, is not always convenient with gadgets in dashboards. Many dashboards have been created by normal JIRA users and it would be too much of a burden on the JIRA admin having to fix references in all of these before being able to export dashboards successfully (see discussion starting at this comment). The solution since v1.5.1 is the following:

• 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. The plugin when exporting will do the same: just 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". This way, after the dashboard is imported into a new instance and when a user tries to view that dashboard, JIRA will show that gadget in "edit" mode, and the user will have a chance to fix the missing reference.

Agile boards

• Agile boards (Scrum and Kanban) can be exported and imported since versions 2.1.0-JX of Project Configurator.
• Both export and import require that the JIRA instance has the plugin JIRA Agile (on JIRA 6) or the application JIRA Software (on JIRA 7) enabled.
• Agile boards are identified across instances by their type (Scrum or Kanban), name and main filter. Please note that it is possible to have in JIRA several boards 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, that needs to set some criteria to decide 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. 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. Both for export and export, one could say that "the first one wins".
• As of version 2.1.0, the earliest supported version of JIRA Agile plugin is 6.7.7 on JIRA 6.3.

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