Editing a synchronization profile

You can edit an already existing profile clicking cog icon and then Edit link on the Configuration view.

General settings

At the first step you provide some basic, general profile properties, such as: name, synchronization interval, TFS / Azure DevOps (formerly VSTS) and Jira servers locations and credentials.

Configuration fields

Most of the configuration fields are self-explanatory, but some might need a little explanation, which you will find below.

User credentials

User provided in Synchronization Profile needs to have correct permissions in given project. For example Jira user should have permissions like: Assign Issues, Create Issue, Edit Issue.

Jira Cloud

If  you are using a Jira Cloud instance, check this checkbox to allow the synchronizer to properly communicate with our Jira Cloud add-on.

Visual Studio Online

Use this option when you want to connect to Azure DevOps (formerly VSTS). Remember that Basic Authentication needs to be enabled. Please see Personal Access Token authentication in Microsoft Azure DevOps (formerly VSTS). 

Store Jira Issue Key in History

Instead of creating custom field in TFS / Azure DevOps (formerly VSTS) you can store Jira Issue Key in Work Item History. This option is useful when you don't want (or when you don't have enough privileges) to create new custom field in TFS / Azure DevOps (formerly VSTS).

TFS Custom Field Name

TFS4JIRA Synchronizer will use this field to store an id of a TFS / Azure DevOps (formerly VSTS) work item linked with a given Jira issue.  

You can define such a field from Jira server custom fields administration (Administration -> Fields -> Custom Fields) by following the steps below:

• Create a custom field of type Text Field (single line). Use any name of your choosing.
• Ensure that the field is applied to all the issue types, that you would like TFS4JIRA Synchronizer to handle (preferably select "Global" option).

• Associate the field with the screen that is configured to be used for Issue Create and Edit Issue operation in Screen Scheme that is defined for selected project; most commonly it's Default Screen. Please read this Jira documentation page for more details.

Jira Custom Field Name

TFS4JIRA Synchronizer will use this field to store a key of a Jira issue linked with a given TFS / Azure DevOps (formerly VSTS) work item. 

You can define such a field for a give work item type from Visual Studio by following the steps below:

• Open a selected work item definition (Tools -> Process Editor -> Work Item Types -> Open WIT From Server -> choose a collection and a project -> choose a work item type) - remember that Team Foundation Server Power Tools must be installed, without it this option is not available (remember also that it can't be installed on Visual Studio Express editions and currently custom fields cannot be added on Team Foundation Service).
• Create a new custom field of type String. Use any name of your choice. The reference name must not start with "System." or "Microsoft."
• Repeat the preceding steps for all the work item types, that you would like TFS4JIRA Synchronizer to handle.

Please remember that this id custom fields should be populated only by Synchronizer itself. User shouldn't write anything in them manually.

Map Jira Reporter To

This field has been removed from configuration in version 6.1. You can map Jira Reporter like any other field.

Connection testing

A Test Connection feature enables you to verify whether TFS4JIRA Synchronizer is able to connect to Jira and TFS / Azure DevOps (formerly VSTS) at specified URL using given credentials. Remember that this option tests only if the connection exists, it doesn't check if given user has correct permissions in project.

Field mappings

Jira issue and TFS / Azure DevOps (formerly VSTS) work item are quite a different items. Although both share some common properties and traits, they also differ in many aspects such as default fields sets, workflows and restrictions. TFS4JIRA Synchronizer allows you to configure which issue / work item fields values should be synchronized and how.

A newly created profile comes with an out-of-the box mapping configuration which is a good starting point for further customization.

Field Mappings view

Field Mappings view consists of two sections:

Basic Mappings

Here you will find links to Values Mapping views for some crucial fields/properties, such as: issue type / work item type, issue status / work item state, issue resolution / work item resolved reason. More info about values mapping configuration can be found in the following sections.

Other Mappings

Here you can define additional issue field / work item field pairs that are to be synchronized. In order to define a mapping select Jira field name in the left box and TFS / Azure DevOps (formerly VSTS) field name in the right box and click Map button. Previously created mappings can be removed. You can also configure values mappings for a given field mapping by clicking on Values link (see the section below for details).

Values Mapping view

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). On Values Mapping view you can configure how should the value be mapped.

The Values Mapping view consists of three sections

Mapping Between

This section contains information about each of the fields in the pair to be mapped, such as name and type.

Mapping mode

Copy values

When Copy values mode is selected, TFS4JIRA 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 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.

In order to define a mapping select Jira field value from the left box and TFS field value from the right box and click a Map button. A list of already defined mappings is displayed under the boxes. You can remove previously defined pairing by clicking Remove link.

Default value is a value to be set if unmapped value is encountered. 

Mapping direction

You can configure the pair for one-way synchronization (i.e. modifications will be propagated in one direction only) or two-way (modifications at both sides will be propagated).