V1.1 of the Migration Toolkit has been released

This release (Migration Sync Toolkit v1.1 (Prerelease)) contains many bug fixes as well as some new functionality for branch and merge. Visit the release page to download the files and be sure to read the Release Notes. This release of the toolkit has also been used to update the TFS to TFS Migration Tool.

Key features of the Toolkit

  • Ability to migrate historical data for VC and WIT
  • Ability to migrate individual projects independent from one another
  • Bi-directional synchronization of data between TFS and another system allowing teams to transition over time
    • Enables integration of TFS with other VC and WIT systems (i.e. using TFS for VC but a proprietary system for bug tracking)
  • Includes several reference implementations to demonstrate Toolkit capabilities and provide an example to tool authors

Other interesting sites


Toolkit Documentation

The documentation for building tools based on the Toolkit is contained below.
  • Getting Started
  • Features
    • Capabilities and Limitations
    • Configuration Files
    • Version Control Feature Details
      • Version Control Settings
    • Work Item Tracking Feature Details
      • Work Item Tracking Policies
    • Linking Features
  • Building a Tool
    • Creating a VC migration tool
    • Creating a WIT migration tool
  • WSS to TFS Tools
  • Migration Console
  • Limitations and Known Issues

Getting Started

Getting the Toolkit

Contents of the download

In the zip archive, there are 5 top level folders
  • Linking - Contains the code to migrate system links
  • Migration Console - Contains the sample application used to run migration sessions
  • Toolkit - Contains the source code for the core Toolkit functionality
  • VC - Contains the sample version control adaptor and helper classes
  • WIT - Contains the sample work item tracking adaptor

At the root level of the zip archive, there is also a sample configuration file, SampleConfig.xml

Below the Toolkit folder there are several subfolders
  • Configuration - Source code related to the configuration of a migration session
  • Eventing - Source code for the events used by the Toolkit
  • Linking - Source code to migrate links, including those between changesets and work items
  • Reporting - Source code for the SQL and text reporting adaptors
  • VC - Source code specific to the migration/syncing of version control data
  • WIT - Source code specific to the migration of work item tracking data

Building the Toolkit and Samples

In order to use the Toolkit and run the samples, the project must be built on the local machine from which the samples will be run.
  1. Visit the Release Notes page and verify that the necessary prerequisites have been installed.
  2. Extract the files from the source package to your working directory for Visual Studio 2005.
  3. Open the Toolkit.sln file with Visual Studio. (Located in the Toolkit directory)
  4. In Visual Studio, build the Toolkit solution by going to Build->Build Solution.

Running the samples

After the Toolkit solution is built, the samples included with the Toolkit can be run. To run the reference implementations, a host process is needed to start the migration sessions. Included with the Toolkit is a sample application to be used to run migration sessions.

MigrationConsole

This sample application is to be used to demonstrate the functionality of the Toolkit and the WSS reference implementations. Although this application is provided to run sessions for the sample providers, it can also be used to run any custom providers built on the Toolkit.

Included in the source package is a sample config file (SampleConfig.xml) for use with the MigrationConsole application when running the WSS migration tools. Please note that the SampleConfig.xml file must be edited to match the details for your TFS server and WSS server before the sample application will run.
To run the MigrationConsole application
  1. Open a command window.
  2. Navigate to the folder containing the application file (MigrationConsole\bin\Debug)
  3. Run the tool using the following syntax
    • MigrationConsole <path to SampleConfig.xml>

Note: If there are dependencies on other DLL’s (linking engine, etc), these DLLs must be copied into the working directory.

WSS to TFS Migration Tools

For more details on the reference implementations visit the detailed tool pages.
  • WSS to TFS Tools

Features

Capabilities and Limitations

The TFS Migration and Sync Toolkit was developed with the intention of migrating and synchronizing both version control and work item tracking data to TFS. There are however some things outside of the scope of VC and WIT that can be migated with the Toolkit. Below is the list of items that can and cannot be migrated, and some areas with limited migration.
  • Capabilities and Limitations

The following pages will help to define what the capabilities of the Toolkit are, and to provide details on the migration of some specific artifacts.
  • Configuration Files
  • Version Control Feature Details
  • Work Item Tracking Feature Details
  • Linking Features

Capabilities and Limitations

What IS migrated by the Toolkit

  • File data with history
  • Work item data with history
  • Check-in comments
  • Work item attachments
  • Links (work item, versioned item, changeset, hyperlinks) (optionally)
  • Hierarchies (areas, iterations)
  • Global Lists
  • Work item types

What IS NOT migrated by the Toolkit

  • Check-in notes
  • Labels (by default)
  • File encodings (by default)
  • Subscriptions (BisSubscribe)
  • Check-in policies
  • Reports
  • Team Portal / SharePoint
  • Process Templates
  • Work item queries
  • ACLs on VC Folders
  • Workspaces
  • Pending Changes
  • Shelvesets
  • Builds
  • Warehouse data

Limitations

Date-time information is not preserved

This is a limitation of TFS that impacts the Toolkit. If items are being migrated to TFS, the date-time data cannot be preserved when the check-in/work item update is made. The server applies the time of the actual check-in operation - for migration this means the time that the migration is run. The Toolkit does preserve the order of operations, including adds, edits, renames, etc.

Changeset and work item IDs are not preserved

Like the date-time, this is a limitation of TFS that impacts the Toolkit. TFS IDs are unique to the server and are monotonically increasing as changes are made to the server. The Toolkit cannot supply an ID for any migrated items, they are supplied by the server when the update is made.

Check-in policies

Check-in policies are overridden during the migration process.

Synchronization Conflicts

During the synchronization process, if changes are made to two files that are being synchronized, the conflict will be handled to avoid overwriting data. However, any conflicts that are not the result of two edits (i.e. two files with the same name are added in synced systems), an overridable exception will be thrown. See Version Control Feature Details for details.

Configuration Files

The TFS Migration and Sync Toolkit is configured by an XML file. The XML schema contains many nodes some of which are described below:

Top Level Nodes

Name Description
Providers Contains individual providers to be used by the Toolkit. A Provider is used by a Session to determine what data is being migrated/sycned to TFS. Each Provider node contains an AssemblyQualifiedName for the assembly associated with that data provider. Providers are also required for any EventSinks used by a Session and the Linking engine.
Servers Contains the TFS nodes for each Server being migrated/sycned to or from. TFS nodes contain a URL for the server.
Settings Defines the name-value mappings for global Toolkit Settings.
VC Contains the version control specific Sessions and Settings.
WIT Contains the work item tracking specific Sessions and Settings.
SQL Contains the ConnectionString, Database name, and Server name for the SQL server to be used by the Toolkit. If the ConnectionString is specified, it is not necessary to specify the Database name and Server name. If all are specified, the ConnectionString will be used in place of the Database and Server pair. Note: the SQL instance used for migration should not be the SQL instance used by the TFS data tier.

Version Control (VC) Node

Name Description
Settings Settings for all VC Sessions. A list of VC Settings can be found on the Version Control Settings page.
Sessions Defines the VC Sessions. The Session table below defines the nodes of the VC Session node.

VC Session

Name Description
Settings VC Settings specific to this Session.
Mappings Contains the Mapping of source paths to target paths to be migrated/synced by this Session. If the cloak value is set to "true", the Mapping will be cloaked out from the mapping of its parent.
Tfs Defines the TFS (destination) server and workspace to be used in this Session. This is where migrated items are migrated to.
Source Defines the source server from which data will be migrated. This node is specific to the Provider for the Session.
EventSinks Defines the sinks for events from this Session. EventSinks include report adaptors. Details are specific to the individual Provider.


Work Item Tracking (WIT) Node

Name Description
Settings Settings for all WIT Sessions.
Sessions Defines the WIT Sessions. The Session table below defines the nodes of the WIT Session node.
FieldMaps Defines the Field Maps. See Field Map table below.
ValueMaps Defines the Value Maps. See Value Map table below.

WIT Session

Name Description
Settings WIT Settings specific to this Session.
Tfs Defines the TFS (destination) server, including the Project, Filter, and MetadataSync settings.
Source Defines the source server from which data will be migrated. Note: this can be another Tfs source.
WorkItemType Defines the mapping between TFS work item types, and types from the source system. FieldMaps are specified here.
Policies Determines how various sync policies should operate. A list of Policies can be found on the Work Item Tracking Policies page.
EventSinks Defines the sinks for events from this Session. EventSinks include report adaptors. Details are specific to the individual Provider.
Linking Defines the linking Engine to be used to handle the link processing. Also specifies a Version Control Session which links from this Session are connected to.

Field Map

Name Description
Field Defines the mapping between a field in TFS and the other system being migrated/synced. Fields also contain references to ValueMaps.
Exclude Defines the fields that will not be synced and the

Value Map

Name Description
Value Defines the mapping between values in TFS and the other system being migrated/synced.


Version Control Feature Details

Below is a list of some of the key features of the Version Control portion of the Migration and Sync Toolkit.

Change Grouping

For systems that do not have a concept of a changeset, the ChangeGrouping class provides a way to group actions to be migrated together. These new ChangeGroupings are created in the analysis phase.

Handling Conflicts

During both the migration and synchronization processes, multiple classifications of conflicts can occur. Several common conflict types are handled by default by the Toolkit, requiring no further implementation by a tool author. The types of conflicts and the resolution mechanisms are described in the following sections

Analysis Conflicts

As files are analyzed by the Toolkit's analysis engine, several scenarios can arise that could lead to a potential conflict scenario. An analysis conflict is any scenario in which the actions that make up a change grouping include actions that must be performed in a specific order to produce the correct content.

A simple example of an analysis conflict is a change grouping that contains and "add" and "edit" action on a single file. In order for the content to be created correctly in TFS, the "add" must occur before the "edit". Although this example is trivial, and the solution is obvious, the Toolkit corrects the order of operations.

Another example that is handled by default in the Toolkit is the detection of cyclical rename operations. If two or more files are renamed in a circular fashion (A renamed to B, B renamed to A), the Toolkit handles the cycle correctly to avoid overwriting the same content in multiple files. In the example above, if the renames did happen exactly as listed, then both A and B would have the same content (A's original content). The Toolkit emulates the action of using a temp file in the process of performing a cyclical rename to ensure that all files in a change grouping are renamed correctly.

Synchronization Conflicts

Files that are being synchronized by the Toolkit are susceptible to numerous conflicts when two or more individuals have modified a common group of files. A synchronization conflict is any scenario in which an item being synchronized between TFS and the source system has changes made in each system during a single synchronization interval.

A basic example of a synchronization conflict is an edit conflict, which is resolved automatically by the Toolkit. In the case where two individuals have edited a file in synchronization, and the file is synchronized, the Toolkit will detect the edits and throw a conflict event. Because the two actions are edits, the Toolkit will handle the event by shelving the changes from the source server in TFS and pushing the changes from the TFS side to the source system. By doing this, the changes from TFS are preserved in both sides, and the other changes are preserved as well.

If any other combination of actions create a conflict scenario during synchronization (i.e. one file is renamed to two different names), the Toolkit will simply throw a conflict event and skip migrating the changes.

Settings

A list of default settings that are available for the Toolkit and the WSS reference implementation for VC can be found on the following page: Version Control Settings.

Version Control Settings

The following table lists the optional Settings that can be specified in the config files under VC settings node. These settings include settings for the Toolkit and the WSS reference implementation tool.

Setting Effect
RetryLimit Defines how many times BatchingContext will attempt to reconnect to TFS in the event of a RepositoryNotFoundException. Sets the default for the number of times the MigrationEngine will retry after a VersionControlMigrationException.
RetryDelaySeconds Defines the number of seconds between retries of BatchingContext flush for RepositoryNotFoundException. Defines the number of seconds between retries of MigrationEngine VersionControlException.
MigrationChangeCommentModifier The string that is appended to the comment of migrated changes.
AddItemNotFound Changes an action to 'Add' if the item is not found on Tfs server.
TargetWorkspaceComment The string that is used as the workspace comment when the toolkit creates a workspace in TFS.
SleepTime Number of seconds to wait between full VC synchronizations when the migration is running in service mode.
SkipChangeComment The string that determines if a changeset is skipped in migration.
UseSlotmodeMappings Determines whether items deleted from TFS will be included in migration.


Work Item Tracking Feature Details

Below is a list of some of the key features of the Work Item Tracking portion of the Migration and Sync Toolkit.

Field Mappings

When importing work items from a source system into TFS, it is unlikely that the work item type definitions are the same. If the type definitions are similar, it is unlikely that the field names will match each other, despite having the same content. In order to create TFS work items from data migrated from another system, the ability to change the mapping of fields is provided by the Toolkit.

After a MigrationWorkItem has been defined, the configuration file for the toolkit enables the mapping of TFS fields to the source system's fields. Field Mappings are defined so that they may be reused for multiple migration sessions, or they can be unique for each migration session.

In the case of at TFS to TFS migration, synchronization of work item types should be disabled for any types for which field mappings are used. Type synchronization will copy the types from the source to the target TFS which will not make use of the field mappings.

Value Mappings

Only part of the transformation of work items includes the remapping of fields. Accompanying this is the mapping of values. Value mapping is best described with an example.

Suppose in the source system, there is a field called "Priority", and the values can be "High", "Medium", or "Low". By default, the "Priority" field in TFS is an integer field, with values of "1", "2", or "3". A value mapping would allow the correct mappings between these fields to be created, as shown in the table below.

Source Field TFS Field
High 1
Medium 2
Low 3

Policies and Conflicts

Instead of having a list of default settings (as in version control), the work item tracking portion of the toolkit specifies a list of policies for how various synchronization events should be handled. These policies are defined on the Work Item Tracking Policies page.

Work items that are synchronized by the Toolkit are susceptible to several types of conflicts. The Toolkit has several policies defined to allow the users to configure how these conflicts should be resolved. Included in these policies are the mechanisms to resolve attachment, field, and link conflicts.

Hierarchies (Areas and Iterations)

For migrated work items which contain nodes under the Areas and Iterations hierarchies, any node encountered by the Toolkit will be migrated if it does not exist on the target TFS. Note that any Areas or Iterations nodes that do not have work items that belong to that node will not be migrated by the Toolkit.

Work Item Tracking Policies

Below is a list of policies for the various items that are synchronized by WIT sessions. The policies below each have a reaction associated with them that determines the action taken by the toolkit to resolve conflicts. Some of the policies also have a notion of a "master" system. In these cases, either TFS or the other system is chosen as the winner when decisions are made as to how items should be synchronized.

Missing User

The reaction for the MissingUser policy specifies how work items with a username that does not exist in TFS or the other system should be handled. The options for the reaction are defined in the table below.

throw The throw reaction will cause the Toolkit to throw an event if a username is encountered that is not in the target system.
default The default reaction will cause the Toolkit to default to a specified user account if a username is encountered that is not in the target system. Using the Default policy for the reaction requires a defaultUser value to be supplied.

Field Conflict

The reaction for the FieldConflict policy specifies how work items with conflicting fields should be handled. Fields conflicts occur when a field in two synchronized work items is changed in both systems.

throw The throw reaction will cause the Toolkit to throw an event if a field conflict is encountered.
master The master reaction will cause the Toolkit to default to the field of the system designated as the master. Using the Master policy for the reaction requires a master value to be supplied.


The table below defines the values that can be supplied for the master value of the Master reaction.
default The default system is chosen to be the master. This is the default chosen by the tool author.
tfs TFS is chosen as the master system. Any field conflict will result in the value from TFS being applied to both systems in synchronization.
other The other system (not TFS) is chosed as the master system. Any field conflict will result in the value from the other system being applied to both systems in synchronization.

Attachments Conflict

The reaction for the AttachmentsConflict policy specifies how work items with conflicting attachments should be handled. Attachments can conflict whenever attachments are found on a work item in synchronization. Because TFS does not record history for attachments, it is difficult to determine what has changed when two work items are found to have different attachments.

One scenario is if the two synced work items have attachments with different names. Without performing an expensive comparison of the contents of the attachments, a rename cannot be distinguished from a delete and add. Another scenario is if an attachment is changed in one system, but the name and size remains the same (i.e. one character changed in the attachment).

throw The throw reaction will cause the Toolkit to throw an event if an attachment conflict is encountered.
union The union reaction will cause the Toolkit to create a union of the file attachments on the synchronized work items, and save the union to both work items.
master The master reaction will cause the Toolkit to default to the attachments of the system designated as the master. Using the Master policy for the reaction requires a master value to be supplied. The options for the master value are the same as those for the FieldConflict policy.


In addition to using the name to determine if there are attachments conflicts, other criteria may be used.
createTime This is the time that the attachment was created.
lastWriteTime This is the time that the attachment was last written.
all All of the criteria are used to determine how the attachment conflict should be resolved.

Links Conflict

The reaction for the LinksConflict policy specifies how work items with conflicting links should be handled. Links conflicts are similar to attachment conflicts in that they have no history to determine the changes between synchronized work items.

throw The throw reaction will cause the Toolkit to throw an event if a links conflict is encountered.
union The union reaction will cause the Toolkit to create a union of the links on the synchronized work items, and save the union to both work items.
master The master reaction will cause the Toolkit to default to the attachments of the system designated as the master. Using the Master policy for the reaction requires a master value to be supplied. The options for the master value are the same as those for the FieldConflict policy.

Missing Area

The reaction for the MissingArea policy specifies how work items with a missing area path should be handled.

throw The throw reaction will cause the Toolkit to throw an event if an area path is missing.
create The create reaction will create the missing area path in the target system.
default The default reaction will use a default area path for the target system.

Missing Iteration

The reaction for the MissingIteration policy specifies how work items with a missing iteration path should be handled.

throw The throw reaction will cause the Toolkit to throw an event if an iteration path is missing.
create The create reaction will create the missing iteration path in the target system.
default The default reaction will use a default iteration path for the target system.



Linking Features

In TFS, there are several different types of links between system artifacts, and the Migration and Synchronization Toolkit provides a method to synchronize those links between TFS and the source system. Below are the descriptions of the various system components and the linking engine work to synchronize links.

Artifact

An artifact is an abstraction for any object used by the system. Any artifact has the following properties:

- URI. This is a string property that uniquely identifies artifact within all artifacts on the source system.
- Id. This is a string property that uniquely identifies artifact within artifacts of the same type (work item id, change list number, etc).

The need for having both id and URI is dictated by the implementation which uses ids for storing mappings between work items on both sides; change list numbers are used for storing mappings between change lists.

Artifact’s type (work item, hyperlink, change list, etc) is hardcoded in the URI; there’s no need to have a public property for it, as the linking engine does not require knowing the type for processing links.

Link

Link is a relationship of certain kind between two artifacts. Two artifacts cannot be connected with two or more links of the same type, but they can be connected with any number of links of different types. For performance reasons linked artifacts (source, target) are represented by URI’s, not by objects themselves, as instantiating these objects may require significant amount of time.

Link Container

Link container is an artifact containing links to other artifacts. Link container has URI of the source artifact; this makes SourceUri property of each link from the container obsolete (it must be identical to URI of the container).

Note that the link container interface does not have a method for extracting links: links, obtained from a container, depend on link handlers, registered in the system.

Linking Engine

Linking engine is a component providing support for the following operations:
  • Getting all supported links from the given container
  • Deferring a link by storing it in some internal database
  • Accessing all deferred links
  • Removing a deleted link
  • Finding reflection of an artifact on the opposite side
  • Extracting internal ID from the URI

Default Linking Engine

The default linking engine (LinkEngineBase class) uses conception of artifact handlers and link handlers. When getting all supported links from a link container, the engine passes the input to all registered link handlers giving them a chance to extract their links. When working with artifacts, the engine passes the input to all registered artifact handlers until one of them recognizes and processes the data. This approach allows having links of different types between two artifacts (related/dependent/duplicate links between work items, for example).

Artifact handlers are always registered in pairs (a handler per artifact type on each side). Artifact handlers are interfaces, link handlers are callback functions. The default implementation provider artifact and link handlers for TFS system, so users wouldn’t have to implement them. However, it does not register them, so users may chose which artifacts they want to handle.

Every link handler must have an artifact handler for its source and target artifacts.

API Notes

  • WorkItemTrackingSession.Start(SyncObjects mode) starts processing specified objects (work items or deferred links) in the service (asynchronous) mode.
  • WorkItemTrackingSession.ProcessDeferredLinks() processes all deferred links created within this session. This method is synchronous.
  • Synchronizing work items analyzes their links and migrates/defers them. The config file must specify linking engine assembly to enable synchronization of links.


Building a Tool

The first step in building a tool is to identify what type of artifacts you are migrating/synchronizing with TFS. If these artifacts are version control or file data, you will probably want to create a tool that syncs with TFS VC. For artifacts such as defects, test cases, or requirements, a tool to sync with TFS WIT is probably the best choice.

Creating VC tools and creating WIT tools require different interfaces to be implemented. Below are the lists of interfaces to be implemented to create specific tools for VC and WIT.

Creating a VC Migration tool

Overview

The task of migration is broken up into two major phases, analysis and migration, which run in parallel within a single host process.

During analysis, the source system is queried to determine what changes need to be mirrored to the target system. That change metadata is converted into a format the migration phase understands and is stored in a SQL database. During the migration phase the data created during the analysis phase is loaded, and the migration actions are executed against the target system.

Cannot resolve image macro, invalid image name or id.

Implementing a VC migration tool
This section outlines the classes a converter author would need to implement and how they relate to the base classes and interfaces provided by the toolkit. In this example, the author is writing a migration tool to provide bidirectional mirroring between TFS and a source system named Widget. This section does not include the host process that the converter needs to run in.

Migration to TFS

If the tool author only intends to create a one-way migration tool then they only need to implement these types.

Common Classes

Class Toolkit Parent(s) Notes
WidgetMigrationItem IMigrationItem This class uniquely describes a single revision of a single item in the Widget version control system. This type will eventually be persisted as XML to a SQL database (via the WidgetMigrationItemSerializer) during the analysis phase and loaded/used during the migration phase.
WidgetMigrationItemSerializer IMigrationItemSerializer This type is used to serialize and deserialize the WidgetMigrationItem type. This type will be used by the ChangeGroupingManager class.
WidgetProviderFactory IConfigFactory This type is loaded when the migration configuration is loaded. It is used to create an instance of the WidgetProvider type.
WidgetProvider IVersionControlEndPoint This type is the end point for the Widget version control system.

Analysis Phase

Class Toolkit Parents Notes
WidgetToTfsAnalysisEngine n/a This class implements the functionality necessary to extract history from the Widget version control system and create the ChangeGrouping instances necessary to replay those actions on the TFS server. There is currently no base class for this type since the behaviors are so specific to the Widget system.

Migration Phase

Class Toolkit Parents Notes
WidgetToTfsMigrationEngine SourceToTfsMigrationEngine This class implements the functionality necessary to migrate the actions generated during the analysis phase (WidgetToTfsAnalysisEngine) to the TFS version control server.


Bi-Directional Synchronization with TFS

If the author intends to perform bi-directional migration of version control history, the following types must be implemented.

Analysis

Class Toolkit Parents Notes
TfsToWidgetAnalysisEngine TfsToSourceAnalysisEngine This class performs the analysis of the TFS system and creates the ChangeGrouping instances that represent the revision history to migration.
TfsToWidgetAnalysisAlgorithms TfsAnalysisAlgorithms The TfsAnalysisAlgorithms class is a helper class that contains the known change type combinations that TFS can contain. This provides a prescriptive framework for writing the analysis engine in a way that will allow the most code reuse. The TfsToWidgetAnalysisEngine uses this class to handle the individual TFS changes.

Migration

Class Toolkit Parents Notes
Tfs2WidgetMigrationEngine VCMigrationEngine This type loads the ChangeGrouping instances created by the TfsToWidgetAnalysisEngine and performs the necessary actions to perform those actions on the Widget version control system.



Creating a WIT migration tool

Overview

Migration of work items operates by connecting data sources to the synchronization engine which generates change lists. For a given pair of work items, a change list to bring both items in sync is generated. This list is translated into a list of atomic updates, which are applied to the target one at a time.

Implementing a WIT migration tool

Class Toolkit Parents Notes
WidgetMigrationWorkItemStore IMigrationWorkItemStore, IWorkItemTrackingEndpoint The interface represents a system where work items are stored. It provides methods for getting and updating work items.
WidgetMigrationWorkItem IMigrationWorkItem The interface represents a work item – a single unit for synchronization
WidgetWorkItemChangeListFactory IWorkItemUpdatePackageFactory The class represents a factory for creating change list objects
WidgetWorkItemChangeList IWorkItemUpdatePackage The interface represents a collection of changes applicable to a work item. Given two work items, the engine generates a pair of change lists that should bring them in sync. Later the change list gets translated into a collection of atomic updates which get submitted into the work item store, updating the target work item (or creating it if the item does not exist).
WidgetWorkItemUpdate IWorkItemUpdate The interface represents an atomic update to a work item. A change list gets translated into a set of atomic updates that will be applied to a single item from the target work item store.
WidgetMigrationFileAttachment IMigrationFileAttachment The interface describes a single work item’s file attachment.
WidgetProviderFactory IConfigFactory This type is loaded when the migration configuration is loaded. It is used to create an instance of the WidgetProvider type.
SyncActionContainer<T> This generic type defines an action that should be performed on its member; both action and member are specified in type’s constructor. Currently supported actions are Add and Remove.


WSS to TFS Tools

The sample tools that are included with the Toolkit are two samples that convert data from WSS to TFS. One of the samples migrates and synchronizes data between a WSS Shared Document library and TFS version control (WSS2TFS_Adaptor). The other sample migrates and synchronizes data between a WSS Task List and TFS work items (Wss2TfsWit).

Configuring the Samples

Below is the list of fields that must be configured to run each of the WSS migration tools.

Fields that must be configured to run the WSS2TFS_Adaptor (VC sample):

  • Mappings
  • TFS details, including Workspace, WorkspaceRoot, and Server URL (in the Server node)
  • WSS details, including BaseUrl, DocumentLibrary, and GMTOffset

Fields that must be configured to run the Wss2TfsWit adaptor (WIT sample):

  • TFS details, including Project, Filter, and Server URL (in the Server node)
  • WSS provider details, including BaseUrl, and TaskList
  • WorkItemType mapping (the type

Fields that must be configured to run either of the sample tools:

  • Sql details, including ConnectionString, Database
  • TFS URL under the Server node

WSS Version Control Adaptor Settings

The following table lists the settings that are specific to VC sessions that are using the WSS2TFS_Adaptor.

Setting Effect
AddStubVersionOnMissingAdd Determines whether a stub version of a file will be added when the add version is missing from WSS.
LanguageId The integer id of the culture of the WSS document library. Used to parse dates of files.



Migration Console

To run the MigrationConsole application

  1. Open a command window.
  2. Navigate to the folder containing the application file (MigrationConsole\bin\Debug)
  3. Run the tool using the following syntax
    • MigrationConsole <path to SampleConfig.xml>

Note: If there are dependencies on other DLL’s (linking engine, etc), these DLLs must be copied into the working directory.

Settings

The following are the settings that are specific to the MigrationConsole host process. They can be specified in the configuration file.

Setting Effect
WarrningsAsErrors Calls TraceError for each call to TraceWarning.
AbortOnError Throws an MigrationException for each call to TraceError.
ShowMethodDetails Determines whether Entered and Exit information is logged about methods.
Mode Determines how converter is run (service or one time).


Limitations and Known Issues

  • Labels are not detected in the analysis phase. This is by design. However, if a label operation is added to the migration queue during the analysis phase, it will be migrated.
  • WIT systems that do not support file attachments and links must still implement the IMigrationFileAttachment and IMigrationLinkOperation interfaces. Returning an empty collection is a possible work around, but TFS must be the master system (to avoid overwriting the attachments with an empty collection).
  • The Toolkit cannot migrate work items with SERVERDEFAULT from=”clock”/> rules. All types containing such rules must disable the rules for the account that will run the migration tool. An example of this change is shown below.
    • <SERVERDEFAULT from=”clock” not=”DOMAIN\jsmith”/>
  • The TextReport adaptor must be given a file with a path under the <File> node. Failure to supply a path will result in an error. To place the text report file in the working directory, the following text can be used:
    • <File>.\Report.txt</File>

Last edited Nov 5, 2009 at 3:06 PM by mmitrik, version 6

Comments

No comments yet.