1. Andrzej Pasterczyk
  2. UseTFS

Wiki

Clone wiki

UseTFS / WorkSynchronizers

Work Synchronizers

Setting up work synchronizers allows to perform two way synchronization between JIRA Issue and TFS Work Item fields. Currently it is limited to following fields.

The idea is that for JIRA Issue a single TFS Work Item is created with mapped values from selected fields and vice versa for TFS Work Item single JIRA Issue. These are connected both ways via reference in custom fields:

  • TFS.ID field in JIRA
  • Jira.IssueKey in TFS

It is recommended to use some kind of test environment to prepare and tune work synchronizer configuration. We're also happy to help if you need assistance - feel free to contact us.

Prerequisites

Custom fields need to be added both to TFS and JIRA. Custom field in JIRA will be automatically created if no field named TFS.ID exists prior to installation. If TFS.ID field is already created in JIRA please make sure that it is not set as mandatory.

In TFS you must add the following field definition to every Work Item Type that you want to have synchronized with JIRA Issue

<FIELD refname="Jira.IssueKey" name="Jira Issue Key" type="String"/>

You can do that by editing Work Item Template (e.g. from Visual Studio 2010 go to Tools -> Process Editor -> Work Item Types - this option is available when using Microsoft Team Foundation Server Power Tools)
TFS 2012 on Azure - as for now it's not possible to alter the work item template on Azure installations but the code has a workaround and it should still work properly even without the Jira.IssueKey field in TFS, however it's recommended to add that field whenever it is possible to lower risk of failures.

This guide assumes that you have successfully installed and configured UseTFS JIRA plugin as well as UseTFS client. Also you have added a repository.

Configuration

Important
Please note that we tried to not to limit configuration possibilities - this means you can create duplicate or empty mappings, etc. There are scenarios that it might be what you're actually after but it may also be a mistake.
Please take time to review your configuration before saving into JIRA.

  1. Right click on UseTFS tray icon icon.png
  2. Select Administration -> Repositories configuration WorkSynchronizers.png
  3. Choose your repository in Repository dropdown
    Note: To add and configure repository settings you need to go to JIRA. See Adding repository
  4. From here you can
    1. create new work synchronizer from scratch
    2. load work synchronizer from XML template
    3. update existing work synchronizer

Creating Work Synchronizer

Single TFS repository set in JIRA can hold multiple Work Synchronizers configured depending on your needs for example having different field mappings based on issue/work item type. You can control for which issues/work items the configuration applies using WIQL/JQL queries. Note that if issue/work item matches several work synchronizers only the first one will be applied.

  • Click on New button
  • Fill Name field with descriptive name of your synchronizer
  • Fill in WIQL field.
    • All fields that are to be synchronized should be contained in WIQL SELECT list enclosed within [] (e.g. SELECT [System.WorkItemType], [System.Id], [System.Title] etc.)
    • In addtion the following fields must be included in WIQL SELECT [System.Id], [Jira.IssueKey], [System.ChangedDate]
    • WIQL must contain the following condition in WHERE statement [System.ChangedDate] > '%2$s'
      The %2$s will be replaced during exection with last synchronization time so that only work items that were added/modified since last synchronization will be processed
    • WIQL should contain the following condition in WHERE statement [System.Id] >= '%1$s'
      The %1$s will be replaced with next work item ID after one that was the most recently created since UseTFS repository was configured and activated. This prevents from "importing"/synchronizing all existing issues.
      Example of correct WIQL query.
#

SELECT [Microsoft.VSTS.Build.FoundIn], [System.WorkItemType], [System.Id], [System.Title], [System.Description], [Microsoft.VSTS.Common.Priority], [Microsoft.VSTS.TCM.ReproSteps], [Jira.IssueKey], [System.AssignedTo], [System.State], [System.ChangedDate], [System.CreatedBy], [System.Reason] FROM WorkItems WHERE [System.WorkItemType] = 'Bug' AND [System.Id] >= '%1$s' AND [System.ChangedDate] > '%2$s' ORDER BY [System.ChangedDate] ASC
  • (Optional) You may fill in JQL field to narrow down JIRA -> TFS synchronization to issues that match particular JQL. If you leave it empty all the issues should be synchronized.
    If you decide to define JQL query you must build your query with key = %1$s as mandatory condition. It's best to have that as first condition in query combined by AND with other conditions inside quotes ()
    Example - only issues of type 'Bug' OR 'Task' will be synchronized
#

key = %1$s AND (type = 'Bug' OR type = 'Task')
  • (Optional) Specify JIRA context user name - this is going to be a user who runs JQL query. Also serves as a fallback user e.g. when cannot assign issue to user mapped from TFS this setting will be considered as fallback option.
    User's access rights apply (e.g. if not able to search issues in given project they cannot be synchronized). Recommended to enter administrator user. First member of administrator group will be considered if empty.
  • Use differential updates - if checked UseTFS will parse revision history for JIRA issues and TFS work items and synchronize only fields that were changed since last synchronization
  • (Optional) Enter top level groovy script. See Groovy expressions
  • Choose if you want to synchronize comments
    • (Optional) Provide JIRA project role (e.g. Users, Developers) or group (jira-users, jira-developers) that will be allowed to view comments synchronized from TFS to JIRA
  • Choose if you want to synchronize attachments
  • Add field mappings

Adding field mappings

  • jiraName name of the field in JIRA. Please use either exactly the same name that is defined in UseTFS (see Fields) otherwise UseTFS will search for custom field with given name.
  • tfsName full reference name of given field in TFS
  • fieldDataType defines how UseTFS should treat the value of given field
    • TEXT is just 1:1 text mapping
    • HTML is to map HTML fields in TFS to plain text in JIRA (as JIRA does not render HTML in text fields by default). In general it strips off some HTML when transferring field value from TFS to JIRA and adds <P> (paragraph) tags when transferring from JIRA to TFS (otherwise no text is visible in Visual Studio)
    • USER it will try to match user display name from TFS with JIRA username and the other way arround, by having JIRA username it'll try to set proper user in TFS when synchronizing.
    • DATE placeholder to handle date/time values - not supported
  • limitSynchToDirection you can choose to synchronize given field in particular direction (tfs<=>jira, tfs=>jira,jira=>tfs or none)
  • mappingValuesJiraToTfs and mappingValuesTfsToJira are sets of dictionary entries that map value in one system to correct value in the other one. Good example here is mapping status - in this case it's Jira Status to TFS System.State
key = Open, value = Active
key = In Progress, value = Active
key = Resolved, value = Resolved
key = Closed, value = Closed
key = Reopened, value = Active

Note that you could actually skip mapping 'Resolved' and 'Closed' statuses as they're 1:1 value and don't require any translation.
If all the values map 1:1 you can just leave the mappings empty.

  • defaultIfNull will tell to return defaultValue if value is null. Useful for fields that require a value in one of the systems but not in the other on (e.g. Description field)
  • defaultValueJiraToTfs and defaultValueTfsToJira are the defaultValues if value is not mapped or null
    fieldSetup.png
  • groovyExpression makes it possible to manipulate the result field value with Groovy language. See Groovy expressions

Field values are returned based on the following rules

if fieldValue is null and defaultIfNull is false then return null
if fieldValue is null and defaultIfNull is true then return defaultValue
if fieldValue is not null and mappings contain corresponding value then return corresponding value
if fieldValue is not null and defaultValue is not null then return defaultValue
otherwise return fieldValue

After all the above apply groovyExpression

Sample setup

BugWorkSynchronizer.xml is shipped together with UseTFS. It is a good example for configuring Work Synchronizers.

Note: The sample configuration assumes that Team Project name in TFS is exactly the same as Project name in JIRA (including upper/lower case characters), as well as Work Item Type is same as Issue Type in JIRA. Only Issues/Work items that met those conditions will be synchronized.

  1. Right click on UseTFS tray icon icon.png
  2. Select Administration -> Repositories configuration
  3. Choose your repository in Repository dropdown
  4. Click Load XML button
  5. Navigate to UseTFS install location and get the XML file in WorkSynchronizerSamples folder
    by default C:\Program Files (x86)\UseTFS\WorkSynchronizerSamples\BugWorkSynchronizer.xml
  6. Review settings
  7. Click Save in JIRA
  8. Create new 'Bug' issue in JIRA, wait 2 minutes and you should see a clone of that issue in TFS assuming that settings were correct

Logs

If you want to check the work item <=> issue synchronization you can access the logs at http://your-jira-server:8080/secure/admin/ViewUsetfsRepositories.jspa or from Administration panel Plugins -> TFS Repositories. Enter WorkSynchronizer logs operation under your repository.

Updated