Importing data into an existing definition

It is possible to import a checklist definition with some or all of its checklists from the Server version of the add-on, or from another instance of the Cloud. For this operation you will need the data files generated with the Export feature of the Server or Cloud versions of the Okapya Checklist for Jira add-on.

Before you Begin

1. Update your server instance with the latest version of Checklist Server. That will ensure that you have the latest version for the exporter and that the import will go smoothly.
2. Export from the server, all the custom field contexts that you want to move to the cloud. Each exported context will create one or more files with the following name pattern customfield_<FIELD_ID>-<CONTEXT_ID>_<FILE NUMBER>. Group together the files where <FIELD_ID> and <CONTEXT_ID> are the same.
3. Is is very important you ONLY upload files belonging to the same context (same <FIELD_ID> and <CONTEXT_ID>). Doing otherwise will lead to undesired and unexpected results and will result in having to redo the import.
4. When uploading a custom field context from the server, the cloud will check the Global Items and Contexts match. In case of a mismatch the import will terminate with an error. So please make sure to read the matching requirements below, and make sure your target checklist definition matches the imported data before starting an import.
5. Some features from server are not exported:
   1. Assignee, priorities, due date, advanced markdown, access permissions are not exported.
      
   2. Cloud does not support headers section yet. So headers are exported as normal checklist items.
   3. Statuses are not on a per checklist definition like on the server. So all statuses are exported to the Status page and will be visible to all issues. It is therefore best to ensure that similar statuses are renamed exactly to identical names on the server before being exported.
   4. If you migrate in steps, make sure that you only select specific projects during the server export.
6. If, during the import, some projects are not found, all the checklists for these issues will be skipped.
7. The import can be a long process so please be patient. Each import is placed in a queue and we process one import at a time. So depending on the number of people trying to import and the size of the import, it can take hours to even days.

Matching data requirements

Global Items match

Importing data into an existing definition can only be done if one of the following conditions is true:

1. The source data has no global items.
2. The target checklist definition has no global items.
3. Both the source data and the target definition have the same number of global items with the same names and order.

Contexts match

Importing data into an existing definition can only be done when both contexts (Projects and Issue Types) satisfy one of the following conditions:

1. The target checklist definition context is set to "All"
   In this case the corresponding context will remain "All" no matter how the source data context is configured.
2. Both the source data and the target definition contexts are configured to limited sets of values.
   In this case the corresponding context will be set to the concatenation of both contexts.

There is a catch when importing data into a checklist definition with a limited context. If the source context includes a Project or an Issue Type which is not found in the destination Jira, the imported context will be reset to "All" for safety. However, this will bring you to importing an "All" context into a limited context, which is not allowed by the rules above, and will generate an error. So when importing data into a definition with a limited context, there are two ways to ensure the process succeeds:

1. Make sure the source context is limited (not "All"), and every Project and Issue Type of the source context exist in the destination Jira.
   OR:
2. Write down the destination checklist definition's context, and set it to "All" before importing new data. You can restore it to only include the needed Projects and Issue Types after the import is completed.

To import a definition

1. Navigate to Settings > Apps > Checklist Definitions, pick the needed definition, and click the 'Import' button:
   
   
   
2. A modal window appears. Please read it carefully before deciding whether to proceed:
   
   You will then see the files upload page.
   
   
3. Upload all data files, and then click the 'Start Import' button:
   
   
   The page will show the import progress:
   
   
   
4. It is recommended that you refresh the status page some time soon after the import starts. The Global Items and Context matching checks are conducted on the early stages, and in case of discrepancies you will see the corresponding errors.
   Global Items mismatch:
   
   Context Mismatch:
   
5. If the import process went to the "Jira Issue IDs" or the "Checklists" stage, it means that the merging checks were passed successfully, and you now only have to wait until the process ends.
   Depending on the number of imported checklists the operation may take from a few minutes up to a few hours. During the import process, on the issue view, you may see the corresponding definition's checklists currently not available:
   
   
   These are unavailable until the import process is completed in order to prevent data discrepancies.
   
   When the import is completed, review the errors and warnings (if any), and then click 'Finish the import and enable the definition'.

Warnings and Errors

Please note that for the import process to be successful, the destination and source Jira instances should have the same:

• Project keys
• Issue type names
• Issue keys

In case of discrepancies, you may encounter the following messages:

Missing Context (Error)

If some projects or issue types of the definition's context cannot be found in the destination Jira, the context will be reset to "All". In this case, depending on the target definition's context you will either see the following warning:

and the data will still be imported if the target definition's context were set to "All" before the import.

Or, if the target definition's context was limited, it will produce a context mismatch, and you will see the following error:

Missing Issues (Warning)

If some issue keys cannot be found in the destination Jira, the corresponding checklists will not be imported. In this case you will see the following warning:

Other checklists, for which the issue keys were found, will be imported as usual.

Other errors

If an error occurs during the import process, you will see this:

Such an error usually means that the import process was affected severely. Significant data loss is possible, or the process cannot continue at all. In such cases please contact us via our support portal.