How to split an import in separate stages
Sometimes it is convenient to split the import of a configuration into two or more separate stages. Some of the reasons for doing so might be:
- The configuration is very large and its full import takes too long. Splitting it into several shorter stages may be more practical.
- Some users have found errors where an object that has been previously created in the import is still not visible for other objects that may require it later. Version 1.8 includes a change that would fix this problem. However, those using earlier versions of the plugin can use this workaround: splitting the import into two steps, the first one creates the first object, and the next stages create other objects that may require it.
The import is split by selecting each time different object types to be ignored or skipped. The selection of object types to skip in each stage must take into account the dependencies that may exist between different object types. For example, workflow schemes link issue types with workflows, so it does not make sense to import workflow schemes if issue types and workflows have not been imported first.
Dependencies
Have a look at the following table:
| Object type | Requires... |
|---|---|
Projects (changes) | Categories Issue type schemes Field configuration schemes Workflow schemes Permission schemes Notification schemes Issue security schemes Issue type screen schemes |
| Versions | |
| Components | |
| Role members | Users Groups |
| Users | |
| Groups | Users |
| Project roles | Users Groups |
| Priorities | |
| Resolutions | |
| Issue link types | |
| Statuses | |
| Event types | |
| Categories | |
| Issue types | |
| Issue type schemes | Issue types |
| Custom fields | Issue types Projects |
| Field configurations | Custom fields |
| Field configuration schemes | Field configurations |
| Screens | Custom fields |
| Screen schemes | Screens |
| Issue type screen schemes | Issue types Screen schemes |
| Workflows | Statuses Screens Event types Issue link types (1) Issue types (1) Custom fields (1) Project roles (1) Priorities (1) Resolutions (1) |
| Workflow schemes | Issue types Workflows |
| Permission schemes | Users Groups Project roles Custom fields |
| Notification schemes | Users Groups Project roles Custom fields |
| Issue security schemes | Users Groups Project roles Custom fields |
| Filters | Groups Project roles Projects |
| Dashboards | Groups Project roles Projects Filters Custom fields |
(1) Depending on workflow conditions, validators and post-functions used, including those defined in supported workflow plugins.
This table means that, for a given configuration, you cannot import one of the object types on the first column, if the object types on the right column have not been imported before. Consider also that the requirement is for the referenced object to exist in the destination instance. It is not necessary that it has the exact configuration as defined in the XML file.
Take into account that there are additional dependencies, but they happen very seldom, so this table is useful for most practical purposes. Consider also, that projects included in the XML configuration file are always created with a default configuration, including default schemes. In other words, you cannot skip creation of new projects.
If you want to split import of a large configuration file
Decide which object types will be imported first
- For your first stage, start by selecting to skip "Projects (changes)".
- Select which other object types you want to skip. It is a good idea to start with those included in the cell to the right of "Projects (changes)"
- Once you decide to skip an object type, you can decide to ignore other object types which the first depends on. Check that they are not needed somewhere else.
Decide if more partial imports will be needed
After running a first partial import, you may decide to run other partial imports. As the project configuration upload page keeps your previous selection of object types to be skipped, you only have to deselect some of those object types, to have them imported in a new stage. Start by deselecting those object types with all their dependencies previously loaded.
It does not matter if you ask the plugin to re-import object types that had been loaded in the previous stage. The pugin will detect that configuration items loaded in previous import stages are already configured in the destination target and will do nothing to them, performing only operations on the remaining object types.
Run the last import stage
For the last import stage, simply select a full import (i.e. skipping no object type).