Profiles allow you to synchronize projects between Jira and Azure DevOps.
Each profile syncs one project to another in the opposite platform.

Each profile can have specific settings and filters allowing you to sync only particular items and fields on defined conditions.

Intro

To create a profile, simply log in to you Synchronizer and click "Create Synchronization Profile" button.

You can either create profile manually or start a wizard. Each method has the same options and capabilities.

Make sure to give your profile a descriptive name, so that it's later easy to deduct its purpose.

Connecting to Jira

Start with pasting the link to your Jira.
Make sure you're providing root path to your instance – not to particular project.

Next, please provide Jira authorization credentials.
This account will be used to make all changes to Jira issues during synchronization process.

For Jira Cloud you will need e-mail and API token.
To learn how to generate API token, please see: API Token authentication in Jira Cloud

In case of Jira Server you will need to provide user name and password to authenticate.

Connecting to Azure DevOps

Similarly, you'll need to connect to your Azure DevOps / TFS.
Again, make sure you're providing root path to your instance – not to particular project.

For Azure DevOps Services (in cloud), you will need an e-mail and Personal Access Token of a user account that will perform all synchronization changes.
To learn how to generate API token, please see: Personal Access Token authentication in Microsoft Azure DevOps (formerly VSTS)

For server versions of Azure DevOps you will need to provide user name and password to authenticate.

Synchronization Settings

At this step you'll be able to:

• select direction of synchronization and
• particular projects to be synchronized (one for each platform)

You will be able to separately choose sync direction for comments, attachments and links.
Please note that selecting "Not synchronized" will effectively disable synchronization of given elements.

Custom Fields

The Synchronizer uses custom fields in both Jira and Azure DevOps to store info on the linked item/issue ID on the the other platform.

You need to create custom fields in both Jira and Azure DevOps yourself, before selecting them in the Synchronizer.

They should be simple, text fields. Their names do not really matter, yet we suggest that they are descriptive, e.g. "AzureDevOpsItemID"/"JiraIssueID".

Creating custom field in Jira

Classic projects

1. Go to your Jira instance.
2. Follow the instructions on how to create a custom field for classic projects from the Jira documentation.
   
   1. Make it a "text field (single line)" type.
   2. Associate the newly created field to all screens that you would like to synchronize (preferably including "Default Screen").

Next-gen projects

1. Go to your Jira instance.
2. Follow the instructions on how to create a custom field for next-get projects from the Jira documentation.
   1. Make it a "short text" type.
   2. You will only be able to add it to the "Context fields" section.
3. Once you do created a custom field, make sure you also add it all other issue types that you would like to synchronize.
   1. Select each issue type one-by-one from the menu and add the previously-created field to them.

Creating custom field in Azure DevOps

Azure DevOps Services – Cloud

1. Go to your Azue DevOps instance.
2. Follow the instructions on how to create custom field from Microsoft documentation.
   1. Make it a "Text (single line)" type
3. Once you do created a custom field, make sure you also add it all other item types that you would like to synchronize.
   1. Repeat the process for each item type, but instead of creating a new field each time, select "Use an existing field" option

Alternatively, instead of using custom fields in Azure DevOps, the Synchronizer can utilize work item history to store the Jira issue IDs.
This option can be useful when creating custom fields is not feasible due to lack of privileges.

Type Mapping

This screen allows you to select which Jira issue type should be mapped to which Azure DevOps work item type and vice versa.

All unmapped types will default to values selected at the bottom of the screen (Map anything else...).
If you choose "Do nothing" option only items of mapped types will be fetched. This can significantly improve synchronization performance.

State Mapping

You can also map Jira statuses to Azure DevOps states.
Workflows in Jira and Azure DevOps should be as similar as possible, otherwise synchronization could end up in an error.

Hierarchy and Subtasks Mapping

The Synchronizer allows you to map Azure DevOps hierarchy in Jira.
This is done by using specific Jira link types.

To learn more please see: Hierarchy Synchronization

The same screen allows you to synchronize subtasks.

To learn more please see: Synchronizing JIRA subtasks to TFS / VSTS links

Links Mapping

You can map links in a similar fashion.
Please note that in case you already mapped the hierarchy at previous step – the used link type will not be available for mapping.

Field Mapping

Field Mapping screen allows you to select which fields should be synchronized between Jira and Azure DevOps.

To configure synchronization options for particular field pair, click ellipsis button – this will take you to the next step.

Value Mapping

After TFS4JIRA Synchronizer detects modification in one of the mapped fields, it copies the changed value to linked peer item (be it issue or work item). This screen is a place where you can instruct TFS4JIRA Synchronizer how exactly should the value be transferred.

Mapping mode

Copy values

When Copy values mode is selected, TFS4JIRA Synchronizer simply copies a modified value attempting to perform type convertion if needed (for example when a numerical field is mapped to string field). For many field types Copy values is the only available mode.

Map values

This mode is applicable to dictionary-type fields only. When Map values mode is selected, the values pairing panel appears.

Mapping direction

You can override profile-wide synchronization direction setting and decide that this particular fields pair is to be synchronized in one direction only.

Values mapping

If Map values mode is enabled, you can explicitly defined mapping between allowed fields values on both sides.

Well Done!

Well done! If you're at this step it means that you've successfully created a new synchronization profile. You can now leave the profile disabled or enable it immediately.

Check out tfs4jira - tfs Jira migration product page.