TFS Integration Tools – Where does one start? … part 1 (documentation)

  • Article

We are currently looking at the product documentation and ways of improving, considering ideas such as landing page and index on-the-web, as well as quick-start guidance. In the mean time I thought that I should start a short series of posts that look at “how to get started” and then running through a few test scenarios.

In this post I will try and answer three basic questions:

  • Where can I find the documentation?
  • Where do I start when considering a migration?
  • Where do I start when considering developing a custom adapter?

Let’s go …

Where can I find documentation?

  … as mentioned above, we are investigating the documentation and improving the end-user experience. In the meantime you will find detailed documentation and guidance material in two locations. If you are looking for the latest supported product and documentation go here, alternatively if you are looking for the latest material go here.  In case of the former you  will to install the tool and then look for the top-level index into the VSTS Ranger-produced guidance material in the Documentation link in the start menu. The latter allows you to download all documentation in a ZIP file and extract the documentation to the location of your choice.

In either case you will find a index.htm file in the Readiness Package directory, which when selected displays a documentation index. The documentation is categorized into guidance, POC, HOL, examples, tooling setup and reference sites.

If you peek in the Documentation root path, you will also notice two other valuable documents:

  • TFSIntegration.chm … which covers most of the common conflicts and recommended resolutions.
  • TFSIntegrationPlatformSDK.chm … which covers the TFS Integration Platform SDK. If you are not interested in adapter development you should probably ignore this one.

Finally we aggregate all blog posts, such as this, into the TFS Integration Platform – Summary of Links blog post. Peek into this collection of questions&answers and other topics, before you tear your hair out over a problem.

Where do I start when considering a migration?

NOTE: The index has been organized in such a way that the typical flow of working through the documentation is from top to bottom.

  1. Review the data sheet and determine if your environment is supported.
  2. Review the migration guidance and the companion migration guidance poster, which guides you through the various scenarios such as an in-place upgrade, backup&restore upgrade, migration and synchronization. What is interesting and highlighted in the poster below, is that only a few scenarios recommend the use of the TFS Integration Tools … which highlights the need to carefully peruse the migration guidance and the documented scenarios. 
  3. If you have decided to use the TFS Integration Tools, the Migration Planning Poster gives you a visual phase-by-phase process to consider.
  4. Also included are a set of technology specific migration guidance documents which should be perused where applicable, for example Perforce, Subversion, ClearQuest and ClearCase.
  5. … if you get to this point is is typically a good idea to look for users that have done similar migrations and to fin a subject matter expert for the source and target systems and the TFS Integration Tools. As highlighted in the documentation in many places, a migration is a complex and costly exercise, which requires detailed planning and testing, before we can consider migrating a production environment successfully.

As highlighted in the planning quick reference poster, a proof-of-concept is highly recommended to test the tooling in “your” environment, to expose potential challenges, which if identified only in the production environment, can turn into a crisis very quickly.

To help you with the proof-of-concept, prototype or pilot migration environment you can scroll down in the documentation index and find the POC section:

  1. PLEASE start with the POC Checklist, which presents an easy to follow POC process.
  2. Peruse the set of templates we used in POCs and which you might find useful to collect the necessary information.
  3. Take time to explore the sample scenarios, which contain POC “from-the-trenches” information and nuggets, such as overview of the scenarios, example manual migration use case examples, field mapping examples and configuration file examples.

If you have fallen through this point, you probably have a spinning head from all the documentation and recommendations. If anything is unclear, chat to us on the Team Foundation Server – Migration and Integration MSDN forum, watch the videos and step through the guided walkthrough hands-on labs.

Where do I start when considering developing a custom adapter?

  • If you are planning to develop your own adapter, first jump to “Where can I find documentation?” section above.
  • Make sure you understand the TFS Integration Platform architecture.
  • Then scroll down in the index and find the Examples section.
    1. The Custom POC Adapter explains how to setup your development environment, allows you to step through a VERY simple adapter and experiment with the TFS Integration Platform architecture.
    2. The Tooling Setup section contains more information on preparing your development environment.  When
  • After you have downloaded the latest codebase, you should be able to use the top level MigrationSolution.sln on a machine that has both TE2008 and TE2010 installed and use setup_build_environment.bat at the root of the tree to create the necessary directories and to probe the GAC to put TFS client OM bits in the right place.

In Part 2 of this series we will do the unthinkable by installing the product and trying to migrate a Team Project from one server to another, using the default configuration and hitting the START button. Not recommended, but definitely worth testing :)