VSTS Rangers Project - TFS Migration Tools: Configuration Demystified

  • Article

After creating a number of the TFS Migration Tools documents (Getting Started, Migration Guidance and Architecture Overview) and looking at the questions and problems raised by the VSTS Rangers working on this project, we have realised that the configuration file is the Clipart Illustration of a 3D White Person Leaning Against A Reflective Red Heartheart of the system. Although the next release of the TFS Migration Tools will abstract the configuration file to a great extent, it is important to understand the basic structure thereof … it is a great treasure map to the solution.

The following illustration shows a hypothetical configuration file. In this post we will look at the general structure, elements and some of the attributes numbered 1-9. In future we may follow-up with more “roll up your sleeves” specialised attributes that make this solution tick.

WARNING: 2010-Jan-13 ... there have been changes in the configuration file structure and you are advised to refer to TFS Integration Platform – WorkFlowTypeEnum Configuration element is being deprecated for an updated example of the configuration file.

image … configuration file structure

  1. The UniqueId defines a globally unique identifier (GUID) and a friendly name, in this case “TR9 HOL”. This configuration is stored in the Migration database using this information when the first session using this configuration file is run. Note that any changes made to the configuration file are not used; as the session will use the configuration in the database if present … an area of great confusion and at times frustration in our test environments.

  2. The next important element is the Providers, which defines a collection of providers. See point 8 for more information.

  3. The SessionGroup element embraces the MigrationSource and the Session elements, whereby there are always two MigrationSource elements per Session element, defining the “from” and “to” sources.

  4. The MigrationSources element encloses a collection of MigrationSource elements.

  5. The MigrationSource element has a number of interesting attributes:

    1. InternalUniqueId … a GUID defining the unique source, which is cross referenced by the Session element as shown.
    2. FriendlyName …a friendly name for those that are not too excited about the 32-byte, 256-bit globally unique identifier.
    3. ServerUrl … defines the server URL for the specific migration source. For Team Foundation Server (TFS) 2010, we need to add the /tfs suffix and the collection we wish to work with.
    4. SourceIdentifier … defines the source at the server. In case of TFS *Work Item Tracking* sessions, it is the team project name. Version Control session is not scoped at team project level and can use arbitrary string as SourceIdentifier.
    5. ProviderReferenceName … defines the globally unique identifier of the provider that provides the muscle, the functionality for this source. Personally I would have called this the ProviderReferenceID or used the friendly name of the provider, because name <> id.

  6. The Sessions element encloses a collection of Session elements.

  7. The Session element as a number of interesting attributes:

    1. SessionUniqueId … a GUID defining the unique session.
    2. FriendlyName … a friendly name, again for those that have not befriended the GUID.
    3. LeftMigrationSourceUniqueId … references the migration source for the left side of the pipeline.
    4. RightMigrationSourceUniqueId … references the migration source for the right side of the pipeline.
    5. SessionType … defines the session type, i.e. WIT, VC or WSS.

  8. Each Provider defines a friendly name and a globally unique identifier (GUID) for each provider used by the session defined by the configuration. As shown in the illustration the GUID and friendly name are also defined by the ProviderDescription of the adapters and is used to identify the correct adapter in the PlugIns directory during the session load processing of the pipeline. At the time of chiseling this blog post, the following adapters are known:

    1. 2F82C6C4-BBEE-42FB-B3D0-4799CABCF00E  TFS 2008 VC  Migration Provider
    2. 663A8B36-7852-4750-87FC-D189B0640FC1    TFS 2008 WIT Migration Provider
    3. 04201D39-6E47-416f-98B2-07F0013F8455      TFS 2010 Migration WIT Provider
    4. FEBC091F-82A2-449e-AED8-133E5896C47A    TFS 2010 VC Migration Provider

  9. The SessionGroup element also includes an attribute WorkFlowType. Please expect in future we will have multiple settings (with default value) to describe the WorkFlowType. Currently the definition thereof can be found in the Architecture Overview document, which includes the following (probably updated) table:

    Type

    Value

    Notes

    OneDirectionalMigration

    0
    • One way (direction) migration of data from source (left) to target (right).
    • Typically a once off process.

    BidirectionalMigration

    1
    • Two way (bidirectional) migration of data from source (left) to target (right), then switch source and target and migrate data from source (right) to target (left).
    • Typically a once off process.

    OneDirectionalSynchronization

    2
    • One way synchronization of data from source (left) to target (right).
    • Typically an ongoing process.

    BidirectionalSynchronization

    3
    • Two way (bidirectional) synchronisation of data from source (left) to target (right), then switch source and target and migrate data from source (right) to target (left).
    • Typically an ongoing process.

    OneDirectionalSynchronizationWithoutContextSync

    4
    • One way synchronization of data from source (left) to target (right).
    • No synchronization of context data.
    • Typically an ongoing process.
    • For internal dogfooding there is a requirement that WITD and other metadata should never be automatically updated by the tool.

    Table 1 - Workflow Types

A logical view of the environment defined by the configuration file is shown below. We have a host that loads the configuration file, locates the adapters defined by the configuration in the plugins directory and proceeds to create a pipeline between Server A and Server B, source TP-1 and TP-B respectively and moves the data from left to right if we define OneDirectionMigration, or from left to right and then from right to left, if we define BidirectionalMigration as the work flow type.

image … logical view.

 

 

Hope this post has revealed a few more secrets and is demystifying the TFS Migration Tools solution.