Import options
- Rosen Marinkov
- Stanley Neychev
Importing projects
When importing projects, default options are displayed according to the import project file type selected in the Import Projects screen. You can adjust these to suit your needs, keeping in mind that the default options suit the majority of migration tasks. If you define your own custom options, you can then save this configuration to use in subsequent import tasks. This means you only need to select the saved configuration name from the Configuration Options drop-down list and not manually define each option.
We recommend that you always run a simulated import before applying an import to your target instance. To select import options, first choose the import project file type as described in Selecting project file types. The Import Project Configuration screen for a configuration-only XML project file and the Import Complete Project screen for the complete project ZIP file are shown below.
 |  |
The table below outlines the options available for each import project file type, followed by additional notes on the use of specific options.
Option | Detail | Configuration Only | Complete Projects |
|---|---|---|---|
Run a Simulated Import | This option is highly recommended to allow you to visualize all the changes that will be applied to your target instance before running an actual import. See Import simulation to learn more. | ||
Create Additional Projects | Automatically create projects in the target instance when required by custom field configuration contexts. Projects are created with the specified key, a default name, and a description, and they are associated with default schemes. If a project is created because it is required by a custom field configuration context, a corresponding message is displayed in the import trace. | ||
Adapt Custom Field Context | Limit changes to custom field configuration contexts to only those projects being imported. | ||
Publish Workflow Drafts | Automatically publish workflow and workflow scheme drafts that are created during the import. More details about this option can be found in Specific information for some object types. | ||
Allow Data Input From Different Jira Versions | Enables the import of data from an earlier version of Jira. Be aware that the greater the difference in Jira versions between your source and target instances, the greater the likelihood of import inconsistencies and unexpected results. 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. | ||
Skip | This multi-select option allows you to list objects you wish to skip from the import. See Skip Loading of Some Object Types below for details of which object types can be skipped. |
Create additional projects
Custom field configuration schemes in Jira have an associated context. This is a set of projects that the configuration applies to, or it can be a global context where a configuration applies to any project not specified in another context. For more information, see Workflow and workflow schemes.
If you are trying to import 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. Use this option to avoid having to manually create these projects in your target instance. The projects will be created with the name and key you specify and then associate all the default Jira schemes to these projects.
Adapt custom field contexts
Using the Adapt Custom Field Context option, the imported configuration for custom fields will only affect the imported projects and not other projects that may exist in the target instance.
This ensures that for each custom field defined in the imported configuration:
The configuration of the custom field for other projects whose configuration is not defined in the imported file ("not imported projects") will not change
The configuration of the custom field for the projects whose configuration is defined in the imported file ("imported projects") will be as described in the XML file
All this will be achieved in accordance with Jira rules: no project will be in the context of more than one custom field configuration scheme (CFCS)
No two CFCS within the same field will have the same name
To achieve this, the import may:
Restrict some of the imported CFCS to apply only to the imported projects
Rename some of the existing CFCS to prevent them from being impacted by changes in the imported configuration
Restrict the context to some of the existing CFCS to apply only to projects not imported (as the configuration for imported projects will be defined by the imported file)
If you are importing a configuration using the Smart Custom Field Contexts option, it is best to use an XML configuration file that was created using the Filter Custom Fields option. Otherwise, you risk having some custom fields configured, especially for the projects in the XML file, even if they are not associated with those projects. See Export options for more information.
Skip configurations
The multi-select list Skip option allows you to select the object types that you want to be ignored during import. For example, if you select Groups, Project Configurator does not create or modify any group in the target instance, leaving them as they were before the import.
Projects (changes) refer to the project lead, category, and schemes associated with imported projects. When using this option, the import of object types that are part of projects, such as versions, components, and project role members, are also ignored. The creation of new projects cannot be skipped.
Projects included in the XML configuration file are always created with a default configuration, including default schemes. To remove a selected object type from the list, click the corresponding X.
Skipping objects can lead to import errors if the creation of an object that is required for another object’s configuration is skipped.
For example, let’s say a configuration file contains Screen A, which does not exist in the target instance, and it also contains Workflow B, which uses Screen A. If screens are skipped from the import, when the app tries to load Workflow B, it will fail because Screen A does not exist.
Object types that can be skipped:
Projects (changes)
Project scope objects:
Versions
Components
Role members
Service Management projects
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 |
Maintain settings between loads
The import screen is designed to keep your selections from one retry to the next, so you do not have to reselect your options every time you run the configuration import. The only exception is the name of the configuration file to load because, as a security measure, most browsers will not permit code in a web page to select a local file. The following settings are maintained between successive loading of an import file:
Real or simulated import
Automatic creation of extra projects
Adapt custom field contexts
Publish workflow drafts
Continue on errors found in dashboards and filters
Object types to be skipped during the import
For import settings to be maintained between load attempts, you must have a Javascript-enabled browser and remain in the same Jira session.
Save import options
To save a custom import configuration to use in subsequent import tasks, complete the following steps:
Before running the import, click Save Configuration.
In the corresponding pop-up window, enter a name for the import configuration that you can easily identify for future use, e.g., config-only-prod. Names must be unique.
To use the saved configuration, select it from the Configuration Options drop-down list that appears at the top of the Import Projects screen.
If you wish to delete a selected saved configuration, click the Trash icon next to the Configuration Options drop-down list.