Limitations of Project Configurator

Owned by Rosen Marinkov
Last updated: May 21, 2024 by Stanley Neychev
4 min read

On this page:

Handling project configurations

The following are not covered by Project Configurator:

  1. Duplicate Names: Since the name is used to identify objects across different instances of Jira in general, Project Configurator does not support objects with duplicate names within the same scope (for example, several components with the same name in the same project).

    1. Project Configurator can, however, export and import custom fields with duplicate field names as long as they have different types. The custom field type is identified by its key, including the app key, as in com.atlassian.Jira.plugin.system.customfieldtypes:datepicker. Therefore, multiple custom fields in the same instance with the same name and type will not be handled correctly. During export, they will be considered as if they were a single custom field. When importing, if the app finds more than one custom field in the target instance with the same name and type impacted by the new configuration, it won’t be able to resolve which of those custom fields must receive the new configuration. The import will stop and display a message similar to the following: Found more than one custom field with the same type and name: com.atlassian.jira.plugin.system.customfieldtypes:datepicker, Triage Date.

  2. Image Files: Image files (icons) are not exported to or imported from XML. The app will assign images to issue types, statuses, priorities, etc., with the same path they had in the original instance, but you must ensure that those images exist in the destination instance and are equivalent to the original images.

  3. Avatars: Project and User avatars cannot be exported or imported.

  4. Third-Party Apps: Project Configurator can export and import parts of the configuration that are specific to third-party applications or apps (this is especially relevant for custom field types defined by other apps) only for the following:

    • The extensions listed for some workflow conditions, validators, and post-functions defined in some apps;

    • The support of Jira Agile/Jira Software (this means Scrum or Kanban boards are migrated);

    • Jira Service Management (you can configure a Service Management project in one instance and move that configuration to another instance);

    • Default values for fields of type com.atlassian.Jira.toolkit:message as explained in PCDEV-180.

  5. Notification Templates: Notification templates are not exported to or imported from the configuration XML file. Users must ensure that any Notification template referred by an event type in the XML file exists in the destination instance, with the same name.

  6. Internationalization: Project Configurator is available only in English.

Items that must coincide in both Jira instances

  • Jira Language and Locale: The conversion of a custom field default value to a string and back depends, in some cases, on the language settings (locale). This may cause problems if a configuration with default values for custom fields is exported from a Jira instance and loaded into another instance with a different default language. Therefore, you should ensure that your source instance has the same default language as the destination.

  • Date and Time Formats: Issues may arise due to the formats used to convert dates and times to strings and back, therefore they must be the same in both the source and target instances. (See Configuring date and time formats).

  • Extensions Defined in an App: If the configuration refers to custom field types, searchers, workflow conditions, post-functions, or any other extension defined in an app, you must ensure that those apps are installed and enabled in the destination instance before importing the configuration.

  • Global Settings: Some settings impact the presence of system fields and whether some attributes of a project are mandatory or not. If they are different in the source and destination instances, the exported configuration may be invalid in the target instance. The following settings must be the same in both instances of Jira:

    • Time tracking

    • Allow unassigned issues

Importing complete projects

Import of complete projects (i.e., their configuration, issue data, and attachments) is subject to the restrictions described in Atlassian’s Restoring a project from backup page.

  • It is recommended that the Jira versions of the source and target instances be the same. Project Configurator allows you to import data from an earlier version of Jira. However, the greater the differences between versions, the greater the possibility of unexpected results or inconsistencies. If your versions are not the same, ensure that the target instance has the more recent Jira version, as differences between the two could cause the data import run by the built-in Jira data import functionality to fail.

  • Project Configurator relies on Jira's data transfer technology when importing project data. Before generating the source instance ZIP file, you should review the create transition of your workflows and, if required, disable any post-functions that may change custom or system field values. Similarly, if any existing validators fail on import, then the issue won’t be created. In this case, disable any validators that exist on the create transition.

  • If the source instance had any custom field apps installed when the backup file was created and the custom field was used in any of the exported projects, then the target instance of Jira must have the same version of the apps installed.

  • Your Jira instance will be locked out during the actual data import (not during the validations), so please ensure that your instance does not need to be accessible during this time.

  • The timezone of the source instance must be the same as the target instance. Otherwise, the import would be affected by JRA-26039, and the imported dates would not be correct.