Table of Contents

What is it ?

Elements Connect system tab allows you to :

• Storage format migration: perform data migration from XML storage format of Elements Connect fields to JSON. As a reminder, with Elements Connect 6 the storage format for Elements Connect fields changed from XML (Elements Connect 5) to JSON. You can check the article about storage format in our documentation.
• Repair corrupted values: repair corrupted values due to a regression in the way connect field values are stored in the  Jira database introduced by Element Connect 6.1.2, for more details see CO-3677.

Storage Format Migration

Field values edited / created with Elements Connect 6 are stored in a JSON format, values edited with Elements Connect 5 are stored in an XML format.

Both formats are fully supported by Connect. However, you could be impacted if you have a script that reads the data stored by Elements Connect in Jira database.
You are not impacted if:

• you don't use field values stored in database from a script
• Elements Connect v5 has never been installed on this instance (all values are stored with the new format)

How to migrate ?

Firstly go to System page -> Storage format migration in Elements Connect administration. From this page, you can:

• launch an audit: know how many issues have field values stored with the XML format
• launch a migration: a background job that migrates stored values from XML to JSON format

Migration scope

If your Jira instance has a lot of issues we advise you to run your migration with project pools. You can select 0, one or several projects in the migration scope selector.

If you select:

• 0 project: the audit/migration will search for values stored with the XML format in all projects of your instance
• 1 or more projects: the audit/or migration will search for values stored with the XML format in the selected projects

Jira indexing

Before launching the audit and the migration a full re-indexing of Jira must be performed.
The goal of the re-index is to flag all issues that have an Elements Connect field stored with the XML format.

Migration can be launched on the entire instance or on a subset of projects.
If you want to migrate values / project you can only re-index the desired projects.

Audit

The audit doesn't modify any data, it just reads data to find if there are issues which possess Elements Connect fields with XML data.
This search is based on Lucene index to have better performance. This is why a re-index of Jira is required.

To launch an audit click on the button "Launch audit".
The process will be executed in a background job, it means that you can leave the page and come back later it will not alter the result nor stop the audit.

Audit results:

• You have no issue to migrate, this message will be displayed on your screen:

• You have some issues to migrate, you will have information about how many issues you need to migrate according to the selected scope:

Migrate issues

Migrate issues will modify your data, it will transform XML Elements Connect fields data to the newest JSON format.

The button "Launch Migration" will launch a background job to migrate field values from XML to JSON. You can use Jira when the job is running, but we recommend launching it when Jira is not under heavy use.
This job will be running in a background task, you can close Elements Connect admin while it is running.

The job can be stopped at any time, but issues are migrated by batch of 1000.
It means the job will be actually stopped when the current batch will be complete.

During migration, average time to migrate 1000 issues is displayed. 

When the job is done, those messages can be displayed:

• You had no issue to migrate:

• You had issues to migrate:

• If you cancel the migration you will see how many issues are already migrated:

• Sometimes data can be corrupted:

Corrupted data cannot be migrated, if you have difficulties with our migration tool, please contact our support. 

Repair Corrupted Values

Elements Connect 6.1.2 introduced a regression in the way Connect field values are stored in Jira database - see CO-3677.
This bug is fixed with Elements Connect 6.1.4 but you might be impacted and have invalid values might be stored in your Jira database.

How to repair?

Firstly go to System page -> Repair corrupted values in Elements Connect administration. From this page, you can:

• Launch an audit: know how many issues have corrupted values
• Repair corrupted values: a background job that will fix all corrupted values

Jira indexing

Before launching the audit and the reparation a full re-indexing of Jira must be performed. This step is required only once.
The goal of the re-index is to flag all issues that have an Elements Connect field stored with corrupted value.

Audit

The audit doesn't modify any data, it just reads data to find if there are issues which possess Elements Connect fields with corrupted data.
This search is based on Lucene index to have better performance. This is why a re-index of Jira is required.

To launch an audit click on the button "Launch audit".
The process will be executed in a background job, it means that you can leave the page and come back later it will not alter the result nor stop the audit.

Audit results:

• You have no issue to repair, this message will be displayed on your screen:

• You have some issues to repair, you will have information about how many issues you need to repair :

Repair issues

The button "Launch Reparation" will launch a background job to repair corrupted values. You can use Jira when the job is running, but we recommend launching it when Jira is not under heavy use.
This job will be running in a background task, you can close Elements Connect admin while it is running.

The job can be stopped at any time, but issues are repaired by batch of 1000.
It means the job will be actually stopped when the current batch will be complete.

During reparation, average time to repair 1000 issues is displayed.

When the job is done, those messages can be displayed:

• You had no issue to repair:

• You had issues to repair: