TFS Integration Platform – Troubleshooting an unhappy migration world

  • Article

Continued from TFS Integration Platform – Planning a migration … starting with a solid foundation … refer to TFS Integration Platform – Summary of Links, section “Migration & Planning” for a list of these posts.

When there is a bug or anomaly smell in a one-way migration or even worse, in a bi-directional synchronisation, then you need to take a step back and troubleshoot the issues. Avoidance is the recommended approach, in other words, before you migrate 10 years worth of work item and version control data, you should validate that you are able to migrate the data by testing the various challenge points (i.e. links, branching, history, …) on a small dataset in a test, not production, environment. Refer back to TFS Integration Platform – Planning a migration … starting with a solid foundation for some ideas of how to plan and complete a proof-of-concept (POC) trial, before hitting the migrate button in a production environment.

We have a problem …. gathering the evidence

Investigating and resolving technical problems related to migrations from technological different systems are, undeniably, one of life's most frustrating experiences.

Looking at the proof-of-concepts conducted in the field, the TFS Integration platform forum and numerous humanoid and email based conversations, most problems reported have been related to security issues or bad assumptions made, which did not take the product limitations into consideration.

Before we look at the recommended basic troubleshooting steps, let us summarise the information that you should gather, especially if you are planning to raise a support call with the product team:

 

  • Document the “trouble” you are investigating, to ensure you understand the issue and that it will be easy discuss with others.
  • Include appropriate screen dumps in the documentation, because a picture speaks volumes and allows those not directly involved to visualise your environment.
  • Secure the session configuration file and any other configuration files that may be of value for further analysis.
  • Run the System Information tool and export the system configuration.
  • Secure the Application, Security and System event logs.

Submit this information when raising a thread on https://social.msdn.microsoft.com/Forums/en-US/tfsintegration/threads or if you are in direct contact with the Rangers or the Product Team, ensuring that initial problem analysis is based on fact, not assumptions and that lengthy and time consuming information gathering ping-pong sessions can be avoided.

Basic Troubleshooting Steps

Most importantly keep it simple … which also means that you should test, verify and perform migration steps in manageable junks. As mentioned before … you should test your setup and your migration scenario with a small sample of test data. Troubleshooting the latter will be a lot easier and less frustrating, with far less blocked developers, testers, program managers and other stakeholders breathing down your neck!

When the bugs announce themselves and you are unable to resolve the issue based on the information presented in the user interface, the recommended basic trouble shooting steps are as follows:

  • Analyse the TFS Integration Platform log files, which document the pipeline activities and the error in great detail.
  • Analyse the Windows Event logs, looking for technical and especially security issues that could be the root cause of the error.
  • Verify that you can access the source and target systems with the credentials you are using for the migration. In other words, use Team Explorer to verify access to TFS and clients such as Clear Quest and Clear Case Explorer to verify access to the source and target systems. If you are unable to access the systems using the relevant client tools, the TFS Integration Tools will definitely not have access either.
  • Verify that the steps defined in the manual use cases, not using the TFS Integration Tools, do not light up with the same error before you switch to automation.
  • Finally if all else fails, raise a thread on the TFS Integration MSDN forum or raise a support call if urgent.

What’s Next?

Today we focused on the basics of troubleshooting. In the next two related posts we will briefly deviate to ClearCase and Subversion to explore some of the differences and challenges of migrations. Thereafter we will return to two other troubleshooting topics, namely conflict resolution and monitoring.

See you next time.