Import Configuration

Selection of what to import

To import a configuration using catworkx Configuration Importer for Jira, do the following as system administrator:

1. From the Administration menu, select Apps.
2. From the sidebar on the left, select Configuration Importer for Jira in the "catworkx" section.
   The "Configuration Importer for Jira" dialog is displayed.
3. You may check out the "Help" tab giving you a "tiny" amount of info about this app, the "Build" tab displaying very detailed information about the build statistics, sometimes requested by the support.
4. You can view the "Dependencies Graph" in order to get an overview respectively idea how complex a dependency tracking is.
5. As a first of the two import options you have the "Simple" option to step by step import the configuration items required for most use cases.
   
6. As a first of the two import options you also have the "Advanced" option to choose any actually supported configuration element, like e.g. workflows, screens, permission schemes and alike.
   

7. By choosing what to import in the beginning the catworkx Configuration Importer for Jira decides what other dependent configuration elements have to be imported, or at least checked, first before your requested import can take place. The names reflect the Jira's internally used labels from the data-model.

   Configuration Importer for Jira only imports dependent elements. Therefore it can be necessary to import some elements separately (e.g., status, resolution) if there are currently no dependencies but if they should be available in the future.
   This is usually the case when you are planning to import the project's data later on using the standard Jira Project Data Importer, since the issues to be imported may require e.g. a resolution that is not related to any workflow, filter or whatever element you import.

   After having chosen a more complex item the catworkx Configuration Importer for Jira will at least try to map all required elements and create all the missing ones before creating the final elements. For example choosing a workflow scheme, the catworkx Configuration Importer for Jira will also check any workflows being referenced as well as users, custom fields, status and resolutions those are checked as well. The largest possible item that can be imported is a "Complete Project" as this will trigger all other importers as well.

   Filter and Dashboards are not strictly configuration-"entities" but are often created by a project lead for the future project participants and it is more than helpful to be able to transfer any of them from staging- to production-systems anyway. catworkx Configuration Importer for Jira can even pick the single portlets from a dashboard for an import.

   When importing workflows the layout created by the workflow designer is reapplied after the import.

Choose what file to import

Then click START.
The "Upload File" dialog appears.

To select your exported configuration file, there are two options:

1. Click Browse and navigate to it. You can import either the ZIP file or the file entities.xml that is included in the ZIP file.
   • Please not there is a upload file size limit – same as the attachment limit
2. From the selection box, select an zip or xml file with your exported configuration that is stored in the <Jira-Directory>/import/ directory.
   • You may choose any regular backup zip file or configuration export zip
   • You may choose any entities.xml file you may have unpacked from a zip file
   • An activeobject.xml file generated by the standard backup procedure cannot be imported and will always be ignored, even if included in a zip backup archive.
   • The zip archives generated by the Teamworkx Configuration Exporter for Jira may contain additional export files generated by apps registered with the catworkx Configuration Import Export Helper for Jira framework, like the two made by catworkx:
     • catworkx Agile config exporter for Jira
     • catworkx JSM config exporter for Jira
   • Other export data may be generated by other apps.

Then click UPLOAD.

Choose what elements to actually import

The select configuration dialog has multiple options

1. Select Configuration: Select the configuration elements you actually want to import.
   You may search for anything using the "Filter" input boxes above the left or the right selection lists.
   Anything in the right selection list will be considered for importing. Those will also be the ones that directly trigger the dependency detection.
   Simply clicking on any element in the lists moves them either to the right or to the left.
   You also have the '>>' or the '<<' buttons on the top to move everything that is shown currently in either list to the other one. Thus you can easily filter something and from there simply click the '>>' to add everything that match your filter to the selection.
2. Mapping Mode Setting: Determines if mapping is done manually and which configurations will be shown on mapping screens:
   1. Automatic: Entities with the same name are mapped. Entities that do not have an related entity with the same name on the target system are created.
   2. required only: Only required entities are provided to map manually. Retain from using this unless told so.
   3. all available: All entities are provided to map manually. Retain from using this unless you really want to spend a possible extremely long interactive time in front of your browser.
3. Options to choose from: Determines if special actions take place, like skipping configuration items. The options provided depend on the configuration type you want to import.
   • You may always click on the blue button that ticks the most useful check boxes below
   • The amount of options differs from what element type you actually chose to import
   • All options have a meaningful description
4. Prefix for configuration: Some configurations might have clashing configuration names but still need to be imported, albeit with a new name
   • This (suggested) prefix will be applied to any filter or dashboard name in case such an element actually exists in the target system
   • This (suggested) prefix will also be applied in case the catworkx Configuration Importer for Jira detects custom fields and thus custom fields context to be in the focus of the import sometimes it is required to keep an existing "Default field configuration for field xyz" and create a new one during the import with the prefix applied in order to correctly import the configuration without breaking the existing one.
5. Directory and Password to use: Determines the directory to create new users and groups in and the default password for new users.
   • Also specify whether to skip the creation of:
     • users, groups and memberships
     • groups and memberships
     • memberships only
   • In case you have "duplicate" user names in your source system, i.e. entities.xml, you may get "duplicate user" errors; enabling this will simply skip failing on this error
6. Fallback email adress and user name: Define a fallback email and user for the e.g. the project lead to use in case the one in the import file is missing or deactivated; also will be applied to users that need to be created and are missing an email address
7. Dry Run Mode: Check this to only make a Dry Run. Nothing will be imported, only a Dry Run takes place for you to check for matches or conflicts.
   • Keep on going: instead of immediately failing the importer during a dry run, simple collect all the errors and show them collected on the final page for you to check the messages.
8. The last three options are merely used in case you are importing really large datasets and experience e.g. timeouts or out of memory errors:
   • Do not show the final report: When you are importing e.g. Complete Projects the report on the final page may become really huge and thus you may either experience a very long load time or even a timeout. Checking this box suppresses the HTML report and only offers you the ability to download the report in Excel format.
   • Do not show the objects dependencies in the final report: Sometimes the additional dependency listed in the last column of the report table, i.e. "Required by" may become too large and either make the table unreadable or even the page itself too long to load. Checking this box suppresses displaying that last column. Downloading an Excel report will contain that data nevertheless
   • Do not track any dependencies at all: In case of really complex dependencies in combination of huge configuration sets to be imported and the system may not be properly scaled you can see out of memory or similar errors. Checking this box might mitigate this since this suppresses the tracking in Java at all.

Helper Apps

During the Import

After selecting the configuration you want to import, click SELECT.
The import starts.

Report – after the Import

After a successful import, you will get an an report showing you what item was mapped to an existing one and what had to be created, including the new database.

To see how an element is mapped, open the corresponding configuration type item in the list.

If you want to export the report to Excel, click DOWNLOAD AS EXCEL.
When done, click FINISH.