Configuring the SpecLog Server TFS Plugin - techtalk/SpecLog-Resources GitHub Wiki

Attention: If you are using Visual Studio Online, you need to enable alternate credentials for your Visual Studio online account before configuring the plugin.

To configure the plugin:

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.
Start the SpecLog client, select Manage repositories from the menu and connect to your SpecLog server.
Select Configure plugins for the repository you want to synchronise work items with:
/ScreenShots/ManageRepositoriesConfigurePlugins.png
Select Configure for the plugin you want to configure from the menu on the right:
/ScreenShots/Server_plugin_config.png
The plugins settings are displayed:
/ScreenShots/TFSPlugin-V3-Settings.png
Configuring the plugin depends on whether you are using TFS on-premise or Visual Studio Online (TFS server, visualstudio.com).

On-premise settings

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
TFS User: Click on the Change button to enter the TFS user name and password used by the plugin to connect to TFS. Refer to the TFS Synchronisation chapter for information on the permissions required by this user.
Enable Impersonation: If enabled, the plugin tries to map the SpecLog user to a matching TFS user when synchronising updates. If a matching user is found, changes made in TFS are attributed to this user (with the exception of deletions).
Polling interval: The interval in minutes used by the plugin to synchronise changes between TFS and SpecLog (in both directions).
Enable back-synchronisation from TFS: Enable this option to synchronise changes made in TFS to linked work items back to SpecLog. If this option is enabled, deleting a work items in TFS linked to a SpecLog requirement also deletes the SpecLog requirement.
Polled area paths: Enter the TFS paths to poll for changes here (comma separated). You need to specify the full area path (e.g. SpecLog.Dev.VSScrum\Demo).
Note: If you move a work item in TFS to a path not specified here, the requirements is no longer synchronised in either direction.
New card mapping: Select the desired template from the drop-down list and click on Add to define a new card mapping

Visual Studio Online Settings

TFS URL: The name of the VSTS account subscription (this should be: https://<YourAccountName>.visualstudio.com
Project: The name of the team project, as created under this account
TFS User: Click on the Change button to enter the TFS user name and password used by the plugin to connect to TFS:
- User name: The user name that VSTS alternate authentication is enabled for (this is usually an email address, e.g. [email protected])
- Domain: Leave this field empty
- Password: The password you specified in the alternate credentials
- Confirm password: Enter the password here a second time to confirm it
Enable Impersonation: This option is not supported in VSTS
Polling interval: The interval in minutes used by the plugin to synchronise changes between TFS and SpecLog (in both directions).
Enable back-synchronisation from TFS: Enable this option to synchronise changes made in TFS to linked work items back to SpecLog. If this option is enabled, deleting a work items in TFS linked to a SpecLog requirement also deletes the SpecLog requirement.
Polled area paths: Enter the TFS paths to poll for changes here (comma separated). You need to specify the full area path (e.g. SpecLog.Dev.VSScrum\Demo).
New card mapping: Select the desired template from the drop-down list and click on Add to define a new card mapping

Changing the TFS Project or URL

If you move an existing project to a new URL or change the project name, you can simply update the entries in the plugin's configuration, and the synchronisation will continue to work.

If you add a new (blank) TFS project to replace the old project, use the migration tool to remove the existing synchronisation data from the SpecLog database before synchronising with the new project.

Impersonation for TFS Users

Note: Impersonation is not supported with Visual Studio Online.

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 the basis. Based on this email address, SpecLog searches for a matching TFS user in the following order:

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

Note: Deletions performed in SpecLog cannot be attributed to a user even when impersonation is active.

Configuring Card Mappings

You can map card templates (e.g. user stories, user activities) to specific TFS work item types (e.g. product backlog item, feature).

To add a new card mapping:

Select the template you are using from the drop-down list.
Click on the Add button. A new section is added to the configuration with some fields pre-filled:
/ScreenShots/V3-card-mapping.png
Configure the mapping:

Card template ID: Enter the ID of the card template. You can view the card's ID in the XML view of the card template. To view the XML, select Edit card templates from the New Requirement widget's menu, and switch to the XML editor tab. Note: If you subsequently change the card's ID in the template, you will need to update this setting as well.
Work item type: Name of the work item type in TFS that the card should be mapped to.
Note: If you edit the target work item type after synchronising requirements with TFS, previously synchronised requirements will retain their original work item type. The new target work item type is only applied to new (i.e. previously unsynchronised) requirements.
Area path: The area the work item should be added to in TFS for requirements defined in SpecLog.
Note: This path should be one of the paths entered under Polled area paths. If you enter a path that is not entered under Polled area paths, no synchronisation will take place.
If you change this path after previously synchronising requirements, previously synchronised requirements will retain their original area path, and changes made in SpecLog will continue to be synchronised at that location. However, any changes made in TFS can no longer be synchronised with SpecLog, as SpecLog will no longer poll this area path for updates. In this case, you can manually change the area path in TFS to allow these work items to synchronise.
Acceptance criterion field: The name of the TFS field used to store acceptance criteria for this card type.
Description field: The name of the TFS field used to store the description.
Create requirement from new TFS Work Item: If you enable this option and Enable back-synchronisation from TFS is enabled, new requirements are added to SpecLog for each work item added to TFS.
Note: If you want to create SpecLog requirements from new TFS work items, the mapping from TFS work item to SpecLog requirement must be unique. You therefore cannot enable this option if a conflicting mapping has already been defined (i.e. a mapping for the same TFS work item type where Create requirement from new TFS Work Item is already enabled). In other words, you cannot map TFS product backlog items to both user stories AND user activities in SpecLog and enable the option to create SpecLog requirements for both card mappings. You can only enable the option in one of the mappings. If you want to map both user stories and user activities in SpecLog to product backlog items in TFS, this is possible, but you can only create new SpecLog requirements of one type from PBI added in TFS.

Changes to Card Template after Synchronisation

If you update a card template (e.g. add a new field), the changes are not immediately synchronised with TFS. Changes are only communicated once you make a change to the contents (e.g. entering data in the new field).

You should not make changes of this type in TFS; apply the changes to the card template in SpecLog and synchronise with TFS to update the TFS work items. If make changes to a TFS work item that would require changes to the card template in SpecLog, the contents of the TFS work item can no longer by synchronised and the contents of the TFS card will instead be added to the SpecLog requirements as acceptance criteria.