4 modes of initial synchronisation and how to use them.

Owned by Paweł Mazur
Last updated: Apr 07, 2022
2 min read

The purpose of this guide is to outline different way in which TFS4JIRA can migrate tickets from one system to another and when they should be used (or not used).

When entering the initial synchronization screen we are greeted with 4 different options:

Each one of them has distinct differences and usages.

I. Synchronize unpaired issues/work items only

The synchronizer will fetch all issues/workitems from one system and check if they have filled the custom field or if have a proper entry in their history. Issues/workitems with entries about the synchronized items will be skipped.

Use when:

  1. Testing sync process.

  2. Initial sync for empty instance.

Avoid for:

  1. When tickets were already migrated to e.g. Sandbox environment.

  2. Issues were deleted in the migrated system.

II. Synchronize both unpaired and already paired issues/work items (update counterparts)

Fetches all tickets and checks if they have filled the custom field or if have a proper entry in their history. If the ticket was not synchronized, proceeds as normal and creates a new counterpart. If the ticket was migrated, update it based on the current state.

Use when:

  1. You are not using live sync and would like to perform the sync only once a day/week/month

  2. You migrated only unpaired only and would like to make sure that they are up to date

Avoid for:

  1. Live running projects in the destination system, may overwrite changes.

 

This mode normally migrates unmigrated tickets (based on the content of the custom field or history entry) as the first mode. In case TFS4JIRA encounters already migrated tickets few things happen. Linking on both sides (ADO/TFS and Jira) is removed and a new ticket is created. The old ticket is not being removed.

In case TFS4JIRA cannot find paired ticket (say it was deleted, moved or permission changed), error is thrown and sync continues with entry in the logs.

 

Use when:

  1. Previous migration was a test migration.

  2. You change the system with which you would like to sync (like Jira Server → Jira Cloud).

Avoid for:

  1. First-time migration

  2. Targeting the same project over and over (you will get a lot of duplicates).

IV. Synchronize both unpaired and already paired issues/work items (remove existing and create new counterparts)

This mode normally migrates unmigrated tickets (based on the content of the custom field or history entry) as the first mode. In case TFS4JIRA encounters already migrated tickets few things happen. Linking on one side is removed, the original ticket is deleted and a new ticket is created.

In case the original ticket was already deleted, error is thrown.

Use when:

  1. The previous sync process was interrupted and data was incomplete.

Avoid for:

  1. Previously migrated tickets were deleted. We suggest option no. 3 here.

  2. There is a chance for tampering in custom fields (or history entries) on either side. You might accidentally delete wrongly linked tickets.