---
title: "Create a synchronization profile"
canonical: "https://support.appfire.com/space/TSH/1800799225/Create%20a%20synchronization%20profile"
format: markdown
---
<span style="color: #000000">Profiles allow you to </span><span style="color: #000000">**synchronize projects**</span><span style="color: #000000"> between Jira and Azure DevOps.</span>  
<span style="color: #000000">Each profile syncs </span><span style="color: #000000">**one **</span><span style="color: #000000">project to another in the opposite platform.</span>

<span style="color: #000000">Each profile can have specific </span><span style="color: #000000">**settings and filters**</span><span style="color: #000000"> allowing you to sync only particular items and fields on defined conditions.</span>

# <span style="color: #000000">Intro</span>

<span style="color: #000000">To create a profile, simply log in to your Synchronizer and click "</span><span style="color: #000000">**Create Synchronization Profile**</span><span style="color: #000000">" button.</span>


![image](media://9c827083-0164-498b-9ef9-fe661b235ba7)


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


![image](media://e3ef5d44-de40-4d79-b6c2-49502f6093a6)


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


![image](media://82b404c9-ddef-4642-8b95-cf8dfa34df0a)

# 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.

![image](media://77704102-d5e4-4e6d-9f1c-21e9d2f40534)


<span style="color: #000000">Next, please provide </span><span style="color: #000000">**Jira authorization credentials**</span><span style="color: #000000">.</span>


> ℹ️ <span style="color: #172b4d">Prevent 'synchronisation user' to become watcher for all created issues (especially if personal account is used instead of service account)</span>
> ℹ️ 
> ℹ️ <span style="color: #172b4d">From the top right of your screen, select Your profile and settings (</span>> Macro (inline-external-image)
> ℹ️ 
> ℹ️ <span style="color: #172b4d">) > Personal settings.</span>
> ℹ️ 
> ℹ️ **Watch your issues** – With this enabled, you become a *watcher* of any issue that you create or comment on. This means you'll get an email when someone updates or comments on the issue.

  
<span style="color: #000000">This account will be used to make all changes to Jira issues during synchronization process.</span>

<span style="color: #000000">For </span><span style="color: #000000">**Jira Cloud**</span><span style="color: #000000"> you will need </span><span style="color: #000000">**e-mail**</span><span style="color: #000000"> and </span><span style="color: #000000">**API token**</span><span style="color: #000000">.</span>  
<span style="color: #000000">To learn how to generate API token, please see: </span><span style="color: #000000">[API Token authentication in Jira Cloud](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800210416)</span>


![image](media://784c8315-18ee-432c-9804-e1f84cc9c2aa)


<span style="color: #000000">In case of </span><span style="color: #000000">**Jira Server**</span><span style="color: #000000"> you will need to provide </span><span style="color: #000000">**user name**</span><span style="color: #000000"> and </span><span style="color: #000000">**password**</span><span style="color: #000000"> to authenticate.</span>

# 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.


![image](media://813aa4f5-1343-4fc2-b0de-5042684e89de)


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.  
<span style="color: #000000">To learn how to generate API token, please see: </span><span style="color: #000000">[Personal Access Token authentication in Microsoft Azure DevOps (formerly VSTS)](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800275671)</span>


![image](media://d352c45d-3d67-4c70-94ac-947d28290e70)


<span style="color: #000000">For </span><span style="color: #000000">**server versions**</span><span style="color: #000000"> of Azure DevOps you will need to provide </span><span style="color: #000000">**user name**</span><span style="color: #000000"> and </span><span style="color: #000000">**password**</span><span style="color: #000000"> to authenticate.</span>


![image](media://b6fb3dce-4137-4b94-9ba4-871bbbd1a70e)


# 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.  
  


![image](media://39c92200-2c0a-44da-9541-1fc583aa0bf3)


# 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**.


![image](media://e2ec47da-b058-4bf3-b62a-5e7fe45bb55d)


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".

Please note that the custom fields **should not** be populated nor **edited manually** – they are to be used only by the Synchronizer.

## Creating custom field in Jira> Macro (anchor)



### Classic projects

1. Go to your Jira instance.
2. Follow the [instructions on how to create a custom field for classic projects](https://confluence.atlassian.com/adminjiracloud/create-a-custom-field-991923727.html#Createacustomfield-Createanewcustomfield) 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](https://support.atlassian.com/jira-software-cloud/docs/customize-an-issues-fields-in-next-gen-projects/#Customizeanissue%27sfieldsinnext-genprojects-Createcustomfields) 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> Macro (anchor)



### Azure DevOps Services – Cloud

1. Go to your Azue DevOps instance.
2. Follow the [instructions on how to create custom field](https://docs.microsoft.com/en-us/azure/devops/organizations/settings/work/add-custom-field?view=azure-devops) 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

![image](media://a8081ce4-c1c3-49fb-8726-437b990bcebf)


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

![image](media://a643ca4f-cd0f-4038-a3b5-58f05f190ecb)


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](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800766575)


![image](media://ef7cd762-0fee-4a8a-9f4b-e0a96a7704fc)


The same screen allows you to synchronize **subtasks**.

To learn more please see: [Synchronizing JIRA subtasks to TFS / VSTS links](https://appfire.atlassian.net/wiki/spaces/TSH/pages/1800308374)


![image](media://1b1f84de-706f-427a-88fc-bdf9992c3568)

# 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.

![image](media://7551dc1e-c7ab-4a2c-83b5-15dbccdf5971)

# Field Mapping

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

![image](media://39640ddf-37c3-4afc-915a-b5f33185418a)


Some filed types require additional configuration – **value mapping**.  
In the above example two pairs of fields need additional mapping:

- Assignee ↔ Assigned To
- Priority ↔ Severity

To define value mapping - please use the "**⋯**" button next to each pair (marked in red).


![image](media://a61634cd-5004-46e9-93c1-100b94de8636)

## Mapping mode

**Copy values** — When *Copy values* mode is selected the Synchronizer simply **copies a modified value** attempting to perform **type conversion** if needed – for example when a numerical field is mapped to string field. For some 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.

# User Mapping

If case both of the systems share **Active Directory** - **user accounts** will be automatically.  
Otherwise, you can manually map user accounts manually.


![image](media://00febad2-3558-44a9-8400-2a50ad28fd3d)

# Enabling the Profile

Before the synchronization takes place – the profile needs to be **enabled**. This will start synchronization of **new changes**.  
To perform synchronization of historic events – please run **initial synchronization** after saving the profile.


![image](media://458046b9-54d4-4b27-9b3d-24ed1e47a9da)


Well done! 🙂