If you have previously synchronised your repository using either V1 or V2 of the TFS plugin, you need to migrate your repository first before using V3. If you do not migrate to V3, all of the cards in your repository will be treated as new requirements and will be synchronised with TFS as new requirements, duplicating existing requirements in TFS.

WARNING After migrating to V3, we recommend not reverting back to a previous version of the synchronisation plugin, as this may cause issues when synchronising existing requirements!

To migrate a repository to V3:

1. Stop the old plugin:
2. Select Manage repositories from the main menu.
3. Connect to your server.
4. Click on the small arrow to the right of the repository you want to migrate and select Configure plugins.
5. Scroll to the SpecLog.TFSPlugin.V1 or SpecLog.TFSPlugin.V2 entry and click on the small arrow on the right and select Configure.
6. Disable the Enable plugin check box and click on Save.
7. Run SpecLog.TfsPlugin.Console.exe prepareforv3 in the server's Plugins directory (see below for details).
8. Configure the V3 plugin (see above) and enable it.

Note that migrating stores the current synchronisation state in your database, but does not make any changes to data in either SpecLog or TFS. Unsynchronised requirements are not updated until the next synchronisation:

• The first time requirements are synchronised, requirements linked to work items in TFS that have been deleted in TFS will also be deleted in SpecLog if back synchronisation is enabled.
• Items added to TFS and not yet present in SpecLog are only added to SpecLog (if back synchronisation is enabled) after a change has been made to the requirement in TFS (you can simply add a space or any other minor alteration and then undo the change).
• You can force requirements and work items to synchronise by making a small change in the to the requirement or work item whose changes you want to propagate, e.g. add a space and then delete it.

This tool migrates repositories synchronised with TFS using a previous version of the plugin to the new plugin version. You do not need to run this tool if you are creating a new repository: in this case, just configure the V3 plugin for the new repository.

SpecLog.TfsPlugin.Console.exe supports the following commands:

This command migrates a repository previously synchronised with an earlier version (V1 or V2) of the TFS plugin to be compatible with V3. This updates your database to include the synchronisation state required by V3 of the plugin. You can remove the synchronisation state from the database using removesyncstate (see below).

Usage: SpecLog.TfsPlugin.Console prepareforv3 repositoryName tfsURL projectName [/tfsUserName:UserName] [/tfsPassword:Password] [/tfsDomain:Domain] [/connection:DBstring] [/projectTemplate:Template] [/areaPath:Path]

• repositoryName: The name of the SpecLog repository to migrate
• tfsURL: The URL of the TFS server, e.g. https://yourTFS.domain/tfs
• projectName: The name of the project in TFS
• /tfsUserName:UserName: Specifies the TFS user used to authenticate with TFS; default: the current user
• /tfsPassword:Password: Specifies the TFS user's password for authenticating with TFS; default: the current user's password
• /tfsDomain:Domain: Specifies the domain of the TFS account
• /connection:DBstring: Specifies SpecLog server's database connection string. If no database connection string is specified, the following default value is used: Server=.;Database=SpecLog;Trusted_Connection=True
• /projectTemplate:template: Specifies the name of the project template in TFS; either VSScrum (default) or MSFAgile
• /areaPath:path: You can specify the area paths (comma-separated) in TFS whose requirements synchronised from SpecLog will be migrated. If not specified, the default area (with the same name as the project) is used.

This command removes the TFS.V3 synchronisation state stored in the database (added using the prepareforv3 command).

Usage: SpecLog.TfsPlugin.Console removesyncstate repositoryName [/connection:DBstring] [/q]

• repositoryName: The name of the SpecLog repository whose synchronisation state you want to remove
• /connection:DBstring: Specifies the SpecLog server's database connection string. If no database connection string is specified, the following default value is used: Server=.;Database=SpecLog;Trusted_Connection=True
• /q: Disables interactive mode; all operations are performed without requiring confirmation

Tests the connection to TFS. For more details, see test connection tool. Use this command to verify that you can connect to TFS successfully.

Use SpecLog.TfsPlugin.Console.exe listsyncerrors to display synchronisation errors. The following optional parameters are supported:

• /repositoryName:Name: The name of the SpecLog repository to monitory. If no repository is specified, all repositories using the V3 plugin are monitored.
• /connection:Connection: The SpecLog server database connection string. If not specified, the tool uses the previously configured "database" connection string, i.e. "Server=.;Database=Speclog;Trusted_Connection=True".
• /minFailureCount:X: The minimum number of synchronisation errors required before a problem is listed. The default is 5.

If you are encountering synchronisation errors, these can often be solved by making a minimal change to the requirement causing the problem, for example by adding a space (which you can later remove).

Use SpecLog.TfsPlugin.Console.exe cleanupsyncerrors to clean up synchronisation errors reported by the TFS.V3 plugin. When an error occurs, SpecLog retries the synchronisation 10 times. If all these retries fail as well, the requirement is flagged accordingly, and SpecLog no longer attempts to synchronise it for performance reasons. If the cause of the error has been fixed, use this command to force these work to be synchronised again.

The following parameters are supported:

• /repositoryName:Name (required): The name of the SpecLog repository with synchronisation errors.
• /connection:Connection (optional): The SpecLog server database connection string. If no string is specified, the entry in \SpecLog\Server\Plugins\SpecLog.TfsPlugin.Console.exe.config is used (default entry: <add name="database" connectionString="Data Source=.;Initial Catalog=SpecLog;Integrated Security=True" providerName="" />.

The command lists your requirements and work items as pairs including the synchronisation errors. If you confirm that the work items should be resynchronised, they will be included in the next synchronisation cycle. However, if a requirement again causes an error, synchronisation is again stopped after the 10th retry.

This command outputs information on the available commands. Use SpecLog.TfsPlugin.Console help command to display detailed information on a specific command.

TFS Synchronisation Plugin V3
Configuring the SpecLog Server Plugin
Synchronisation