Synchronization Workitems TFS - techtalk/SpecLog-Resources GitHub Wiki

WARNING This section refers to legacy versions of the TFS synchronisation plugin. In most cases, we recommend using V3 of the TFS plugin instead. Please refer to SpecLog.TFSPlugin.V3 for more details. Please also refer to the known limitations before upgrading to V3, as V3 currently has a few minor limitations compared to previous versions. Note that if you have synchronised a repository with one of the legacy version of the TFS synchronisation plugin (V1 or V2), you need to first migrate your repositories before using the V3 plugin.

This section covers synchronising work items with with Microsoft Team Foundation Server. More information on work item tracking synchronisation in general can be found here.

The following TFS versions are currently supported (more recent versions may also be supported):

• Microsoft Team Foundation Server 2010, 2012 and 2013
• Microsoft Visual Studio Online (Team Foundation Services, visualstudio.com)

The following TFS templates are supported (customised templates and more recent versions may also be supported):

• MSF for Agile Software Development v5.x and v6.x
• Microsoft Visual Studio Scrum 1.x and 2.x

Synchronising work items with TFS requires the following core fields in the template:

• Title
• Description
• Acceptance Criteria
• Estimate

Warning: Additional validation rules in custom templates can cause synchronisation errors if these rules are violated by updates synchronised from SpecLog.

You can log synchronisation errors encountered by the plugin in the SpecLog server logs (if logs are enabled), which can help you identify compatibility issues with customised templates.

SpecLog provides two different plugins for synchronising work items with TFS:

• SpecLog.TFSPlugin.V2: This plugin is recommended for synchronisation with TFS. Synchronisation is bi-directional (including creating SpecLog requirements from new TFS work items) and collates multiple SpecLog updates into a single TFS work item update.
• SpecLog.TFSPlugin.V1: This plugin is provided for backwards compatibility with previous SpecLog releases. It provides uni-directional synchronisation (SpecLog to TFS) for requirements, and back synchronisation of estimates (TFS to SpecLog). Furthermore, individual SpecLog updates are synchronised as TFS work item updates whenever they occur.

To configure the plugin:

1. The plugin assemblies must be located in the SpecLog server's /Plugins folder.
   Note: the plugins are automatically installed here unless you unselected them during installation.
2. Select Manage repositories from the menu and connect to the SpecLog server.
3. Select Configure plugins for the repository you want to synchronise work items with:
   
4. Select Configure for the plugin you want to configure from the menu on the right:
   
5. Enter the necessary information to allow the service to access the TFS project:
   

You need to set the following parameters in step 5 when using TFS on-premise:

• TFS URL: Name of the TFS collection where the project is hosted (the default collection name in TFS is: https://<YourTFSServerName>/tfs/DefaultCollection)
• Project: Name of the project in TFS
• Project template: The project template type configured for the project. The version number doesn't need to match exactly; choose the option that matches your template. For information on the supported templates, see above.
• TFS User: The TFS user name and password used by the plugin to connect to TFS. See the notes below for information on the required permissions.
• Enable Impersonation: If enabled, the plugin tries to map the SpecLog user to a matching TFS user when synchronising updates.
• TFS polling interval (SpecLog.TFSPlugin.V1 only): The interval in minutes used by the plugin to synchronising changes back from TFS to SpecLog. See Workitem Synchronization Mechanism for further details.
• Polling interval (SpecLog.TFSPlugin.V2 only): The interval in minutes used by the plugin to synchronise changes between TFS and SpecLog in both directions. If back synchronisation from TFS to SpecLog is disabled, this setting is the same as the "TFS polling interval" setting in SpecLog.TFSPlugin.V1. See Work Item Synchronization Mechanism for further details.
• Enable back-synchronisation from TFS (SpecLog.TFSPlugin.V2 only): If enabled, the plugin tries to synchronise back changes to linked work items from TFS to SpecLog.
  • Create requirements from new TFS Work Items: If enabled, the plugin creates new requirements in SpecLog for each work item created in TFS
    • Card template for created requirements: The requirement type used by the plugin to create requirements from new work items in TFS. The default setting is UserStory, meaning that a new User Story is created in SpecLog for each work item created in TFS. Enter the ID of the requirement type (e.g. UserStory). You can look up the ID in the repository's card templates. Note that if you change the template's ID in the repository, you need to update the value here as well.
    • Idle time in TFS before requirement creation: Duration in minutes that must elapse without any changes to the work item in TFS before the corresponding requirements are created in SpecLog by the plugin. The default setting is 15 minutes, which means that you need to wait 15 minutes without making any changes before work items created in TFS are visible as requirements in SpecLog.

Both versions of the SpecLog.TFSPlugin can be also used to synchronise with Visual Studio online.

Before configuring the synchronisation, you need to enable alternate credentials for your Visual Studio online account:

1. Select My profile from the accounts control panel:
   
2. Select Enable alternate credentials on the CREDENTIALS tab of the profile:
   
3. Specify a password for the alternate credentials
   

You need to set the following parameters in step 5 to configure the plugin:

• TFS URL: The name of the TFS collection of your TFS account subscription (this should be: https://<YourAccountName>.visualstudio.com/DefaultCollection - listed under https://tfs.visualstudio.com/en-us/account/tfs-subscriptions)
• Project: The name of the team project, as created under this account
• Project template: The project template type configured for the project. The version number doesn't need to match exactly; choose the option that matches your template. For information on the supported templates, see above.
• TFS User:
  • Username: the (Live ID) user name the TFS account is registered to (this is usually an email address, e.g. [email protected])
  • Domain: The domain the TFS account is registered for (e.g. Windows Live ID)
  • Password: the password you specified in the alternate credentials
• Enable Impersonation: If enabled, the plugin tries to map the SpecLog user to a matching TFS user when synchronising updates.
• TFS polling interval (SpecLog.TFSPlugin.V1 only): The interval in minutes used by the plugin to synchronising changes back from TFS to SpecLog. See Workitem Synchronization Mechanism for further details.
• Polling interval (SpecLog.TFSPlugin.V2 only): The interval in minutes used by the plugin to synchronise changes between TFS and SpecLog in both directions. If back synchronisation from TFS to SpecLog is disabled, this setting is the same as the "TFS polling interval" setting in SpecLog.TFSPlugin.V1. See Workitem Synchronization Mechanism for further details.
• Enable back-synchronisation from TFS (SpecLog.TFSPlugin.V2 only): If enabled, the plugin tries to synchronise back changes to linked work items from TFS to SpecLog.
  • Create requirements from new TFS Work Items: If enabled, the plugin creates new requirements in SpecLog for each work item created in TFS
    • Card template for created requirements: The requirement type used by the plugin to create requirements from new work items in TFS. The default setting is UserStory, meaning that a new User Story is created in SpecLog for each work item created in TFS. Enter the ID of the requirement type (e.g. UserStory). You can look up the ID in the repository's card templates. Note that if you change the template's ID in the repository, you need to update the value here as well.
    • Idle time in TFS before requirement creation: Duration in minutes that must elapse without any changes to the work item in TFS before the corresponding requirements are created in SpecLog by the plugin. The default setting is 15 minutes, which means that you need to wait 15 minutes without making any changes before work items created in TFS are visible as requirements in SpecLog.

The TFS user assigned to the plugin is used to synchronise data with TFS, and requires the following permissions (group memberships) in TFS:

• Member of the tfs service accounts group
• In order to impersonate other users (so that the correct user name appears in the history), the account requires the Make requests on behalf of others permission (granted by default to users in the tfs service accounts group)
• An access level (e.g. "Basic") that allows access to the Code area in order to link feature files

If you are experiencing problems relating to permissions, we recommend first verifying whether you can access the TFS project with your user account. If so, enter your account details in the plugin's settings and test the synchronisation. Provided you can access the TFS project, the synchornisation service should also be able to synchronise requirements from SpecLog to TFS using your account (although impersonation may not work).

If the Enable Impersonation option is enabled in the plugin settings, the plugin attempts to map the SpecLog user who modified a requirement to a matching TFS user. If a matching user is found, the change is synchronised with TFS using that user. The email address of the user account on the SpecLog server (e.g. [email protected]) is taken as a basis. Based on this email address, SpecLog searches for a matching TFS user in the following order:

1. A TFS user with a matching Active Directory Domain User Email Address (note that the Preferred Email Adress entered for the user in TFS is currently ignored)
2. A TFS user with an Active Directory Domain User Name that matches the name in the email address (e.g. [email protected] corresponds to the domain user MyName)
3. TFS user and domain name: the Active Directory Domain User Name of the TFS user with the domain name. (E.g. [email protected] is matched to the domain account MyCompany\MyName)

If no matching TFS user can be found the plugin synchronises the updates without impersonation.

Since SpecLog continuously saves user input as update commands (implicit save), and TFS requires changes to a work item to be saved explicitly, the synchronisation plugin synchronises batches of changes in SpecLog with TFS at regular intervals.

Changing this interval affects how quickly changes in SpecLog are synchronised with TFS, as well as the size of the work items' update history (shorter update intervals mean a longer history).

You can configure the synchronisation schedule in the PluginSynchronizationSettings section of SpecLog.server.exe.config.