Contents        

You can create a new profile by clicking Create Synchronization Profile button on the Configuration view.


New synchronization profile creation is divided into several steps which are described below.  

Step 1: Hello

This is just a welcome screen. You can proceed with wizard-assisted profile creation or go to advanced mode and create profile manually.


Step 2: Profile name

This screen is quite self-explanatory.


Step 3: Jira Settings

This screen is to gather all basic information about your Jira instance (location, credentials). This is Jira Cloud option must be checked for Jira Cloud instances (*.atlassian.net).

You can click Test connection at any time to make sure your URL and credentials are OK.


Step 4: TFS / VisualStudio Team Services Settings

This screen collects all basic TFS / Azure DevOps (formerly VSTS)  server data (location, credentials).

Use URL to root path of your TFS / Azure DevOps (formerly VSTS) instance (without project collection or project name) for example: https://yourname.visualstudio.com/

Use This is visualstudio.com instance option when you want to connect to Azure DevOps (formerly VSTS). Note that Basic Authentication needs to be enabled. Please see Configuring user credentials for Azure DevOps (formerly VSTS)

Just like on Jira Settings screen you can validate your credentials by clicking Test connection button.


Step 5: Synchronization Settings

This screen contains general synchronization settings, such as:

Synchronization directions

You can choose whether Synchronizer should reflect Jira changes to TFS / Azure DevOps (formerly VSTS), the other way around or both. Apart from general synchronization direction you can also independently set direction for comments and attachments synchronization (including Not Synchronized option which effectively disables respective synchronization type). Comments synchronization is supported from Jira 6.2.

Jira and TFS / VSTS projects

Note that single synchronization profile is configured for a specific Jira to TFS / Azure DevOps (formerly VSTS)  project pair.


Step 6: Custom Fields

This step allows you to configure how Synchronizer should store information about which TFS / Azure DevOps (formerly VSTS)  work item is linked to given Jira issue and vice versa. 

Custom field in Jira

Select a custom Jira field that TFS4JIRA Synchronizer will use to store paired TFS / Azure DevOps (formerly VSTS)  work item id in.

You can define such a field from Jira 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 operation in Screen Scheme that is defined for selected project; most commonly it's DefaultScreen. Please read this this documentation page for more details.

Custom field in TFS

Select a custom TFS / Azure DevOps (formerly VSTS)  field that TFS4JIRA Synchronizer will use to store paired Jira issue key in.

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 keep in mind that this id custom fields should be populated only by TFS4JIRA Synchronizer itself. User shouldn't write anything in them manually.


Use TFS / Azure DevOps (formerly VSTS)  history instead of custom field

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


Step 7: Type Mapping

This screen allows you to select which Jira issue type should be mapped to which TFS / Azure DevOps (formerly VSTS)  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 Action "Do nothing" in these select lists, only items of mapped types will be fetched, which can significantly improve synchronization performance.

Step 8: State Mapping

This step is similar to the previous one with one difference that it relates to Jira status to TFS / Azure DevOps (formerly VSTS)  state mapping. Workflows in Jira and TFS / Azure DevOps (formerly VSTS)  should be as similar as possible, otherwise synchronization could end up in an error.


Step 9: Links Mapping

This step is related to links synchronization feature, please refer to the documentation at this page for details.

Step 10: Subtask Mapping

This step related to subtasks synchronization feature. See this documentation page for information on how subtasks synchronization works.


Step 11: Field Mapping

Field Mapping screen allows you to select which fields should be synchronized between Jira and TFS / Azure DevOps (formerly VSTS). 

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


 Only modifications made to mapped fields will trigger synchronization and only these values will be synchronized. TFS4JIRA Synchronizer ignores modifications made to unmapped fields.

Step 11a: 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.


Step 12: 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.


  • No labels

This page has no comments.