This documentation has moved. For the most recent documentation, check out Please update your bookmarks and links.

Skip to end of metadata
Go to start of metadata

Import Options for Configuration Only

After clicking on the link named "Import project configuration" the following page will appear.

Clicking on the button to the right of the text field, allows you to select the XML file you want to load with the project configuration.

Once you have selected the file and chosen whether the load will be simulated or real, click on the "Import project configuration" button to launch the load.

Large XML files

Jira limits the size of uploaded files by default to 10 MB. If your configuration file is bigger than that, you have to increase this limit. Otherwise, the file upload aborts and it is "as if" the whole request had not taken place. You will click the upload button and "nothing" happens!

See Atlassian's Configuring File Attachments for more information on increasing this limit in Jira. 

Import Options for Complete Projects

This menu is same to the import of Project Configuration but with a couple of exceptions:

Just below the project file name, there is another text box called "Attachments path". If you selected to migrate your attachments automatically when you exported the projects in the ZIP file specified for this import, you should leave this field empty; otherwise, you will need to move the attachments manually to this instance and specify their path in this field.

Moreover, there is "Allow data import from different Jira versions" checkbox (since version 2.4.3-J7) which if checked will allow you to import a complete project exported from a different version of Jira.  Please note, that importing data from different Jira versions might eventually lead to not all information being imported or other import problems. This risk would be greater as the difference between the source and target version becomes larger. If this option is enabled, the app will display a warning about this risk.

Import Options

If the "Apply changes?" tick is not selected, the import process will be simulated. This means that no changes will be actually made in Jira, but you will be able to see in the result page a simulation of all the changes that the app will make in Jira when importing that configuration file. Note that this tick is not selected initially, as a safety measure.

Custom field configuration schemes in Jira have an associated context. This is a set of projects that configuration applies to, or it can be a global context, meaning a configuration that applies to any project not specified in other context. You can find more information here.

If you are trying to load a custom field with a context that refers to another project(s), those projects must exist before the app can build the configuration as it is described in the XML file.

If the option "Create extra projects" is ticked, during the real load if a project used in a custom field context does not exist, Project Configurator will create it automatically. The project will be created with the specified key, and a default name and description and it will be associated to default schemes.

If that option is ticked, and a project is created because it is needed in a custom field configuration context, a message like this will appear in the load trace.

The "Smart custom field contexts" option permits that the imported configuration for custom fields will only affect the imported projects, and not other projects that may exist in the destination instance. 

When smart custom field contexts are enabled, the app will perform these steps for every custom field in the XML file:

  1. It will consider only those contexts which affect any of the projects being imported. The rest of contexts will be ignored, "as if" they were not in the configuration file. If there are contexts for several projects and some of them are being imported and others are not, the app will treat these contexts "as if" they applied only to the imported projects.
  2. For the contexts in the actual custom field, if any of them applies both to imported projects and other projects, it will be changed, so that it applies only to projects that are not being imported.
  3. The app will match contexts in the XML file to existing contexts in the actual custom field, based on the projects to which the contexts apply. The matched contexts will receive the configuration that was defined for them in the XML file.
  4. The global context, i.e. the one that applies to "the rest of projects not referenced in other contexts" has a special treatment, as any change to this context is likely to affect potentially many projects whose configuration is not being imported. If the configuration in the XML file implies that the global context is used by any of the imported projects and importing it would change the existing global context, the app instead will create a new context for the imported projects that require it, leaving the existing global context untouched.

Highly recommended...

If you are going to import a configuration with "smart custom field contexts" it is a very good idea that the XML configuration file was created with the option to filter custom fields not used by the exported projects. If you do not do it this way, you risk getting some custom fields configured especially for the projects in the XML file, even if they do not have anything to do with those projects.

If this option is checked, the app will publish workflow drafts and workflow scheme drafts created during the import.

More details about this option can be found in the specific documentation for workflow scheme drafts and workflow drafts.

The multi select list labelled "Skip:" lets you select object types that will be ignored during the load. This means that, for example if you select "Groups", the app will not create or modify any group, leaving them as they were before the load.

"Projects (changes)" refers to the project lead (only in versions for Jira 7), category and schemes associated to imported projects. When it is selected, import of object types which are part of projects, like versions, components and project role members, is also ignored. Creation of new projects cannot be skipped. Projects included in the XML configuration file are always created with a default configuration, including default schemes.

You can select more than one object type to ignore, clicking on any of them while the keys "Ctrl" or "Shift" are pressed. To deselect an already selected object type, click on it while pressing the "Ctrl" key.


This option can lead to load errors, if creation of an object that is necessary for another object's configuration is skipped. For example, suppose the configuration file contains screen "A" which does not exist in the target, and it also contains workflow "B" which uses screen "A". If load of screens is skipped, when the app tries to load workflow "B" it will fail as screen "A" does not exist.

So, use this option with care!

The list of object types that can be skipped is:

  • Projects (changes)

Project scope objects:

  • Versions
  • Components
  • Role members
  • Service Desks

Global objects:

  • Users
  • Groups
  • Project roles
  • Priorities
  • Resolutions
  • Statuses
  • Event types
  • Categories
  • Issue types
  • Issue type schemes
  • Custom fields
  • Field configurations
  • Field configuration schemes
  • Screens
  • Screen schemes
  • Issue type screen schemes
  • Workflows
  • Workflow layouts
  • Workflow schemes
  • Permission schemes
  • Notification schemes
  • Issue security schemes
  • Filters
  • System dashboard
  • All dashboards
  • Scrum and Kanban boards

This web page is designed to keep your selections from one retry to the next, so you do not have to select everything every time you run the configuration load. The only exception is the name of the configuration file to load because, as a security measure, most browsers will not let code in a web page select a local file. So these settings will persist between successive loads:

  • Real or simulated load
  • Automatic creation of extra projects
  • Smart custom field contexts

  • Try to publish drafts
  • Continue on errors found in dashboards and filters
  • Object types to be ignored during the load

The only requirement for this persistence of settings is a browser that has Javascript enabled and staying in the same JIRA session.

Dashboards and filters are created by Jira end users without the supervision of a Jira administrator. It is easy that a large instance of Jira contains hundreds or thousands of filters and dashboards. The combination of both circumstances can make life quite difficult for a Jira admin that tries to transfer all those objects to another instance of Jira (for example, as she would do when trying to merge two instances).

In order to minimize this problem, Project Configurator includes a feature that lets the import continue when an error is found during the import of a dashboard or filter. This feature is enabled when this option is selected in the import page.

See the page about viewing import results for a description of how recovery from a filter/dashboard error is handled and displayed in the load trace.

This option does not apply to Scrum and Kanban boards

Please note this option does not apply currently to errors occurred during import of Scrum or Kanban boards. These errors will halt the import, even if their ultimate cause is an issue with a filter or JQL query referenced from the board.

  • No labels