Scrum for Team System – Work Item Migration Utility
During the creation of the Scrum for Team System (SfTS) version 2 template, the development team created several utility programs to help test and work with the new template. One of these utilities is the “Work Item Migration Utility”.
Work Item Migration
By default, the team foundation server does not provide the ability to migrate work item data from one project to another. Work item data can be exported by opening queries in Excel, saving and then publishing to an alternative target project. This is a time consuming process that doesn’t maintain the linkage between work items and attachments and does not include all the work item history. The excel solution is less than ideal.
Enter the “Work Item Migration Utility”. This utility enables you to export work item data from SfTS v1.x and SfTS v2.x projects into an xml formatted save files and then import them into another SfTS v2.1 project. This process not only maintains the work item linkage, but also includes all the work item historical data. Global lists (Teams and Environments) are included in the exported data and in addition, you can also export / import the contents of the team project portal.
How to use the utility
This application requires that you have Team Explorer 2008 installed.
The attached zip contains all the files needed to run the migration utility. However, there is no packaged installer. Instead you will need to extract the content of the zip to a working folder and then run the Conchango.TeamSystem.SfTSWorkItemMigrationUtility.exe to get started.
The utility works by using the concept of migration projects. Three types of migration project can be created;
· Export Project:
The work item data is exported into xml data files.
· Import Project:
Previously exported data files are used to import data into a SfTS project
· Export and Import project:
This is a combination of the above projects that completes the process in a single iteration.
Example: Creating an export and import project:
Before you start this example, you will need an existing SfTS v1.x or v2.x project to use as a source for the data migration. You will also need to have downloaded and extracted the attached zip file as detailed above in the "How to use section".
1. Create the demo target project that will be the target of the data migration:
a. Create a new project and name it “DemoTarget”
b. Select the “Agile software development with scrum – v2.1.xxxxxxx”
c. Click the finish button and wait for the project creation to complete:
2. Launch the utility (Conchango.TeamSystem.SfTSWorkItemMigrationUtility.exe) and create a new Export and Import project.
3. Complete the “Migration Project Main Section” as follows:
a. Migration Project Name: Demo Project Migration
b. Working Folder: c:\temp\DemoMigration
c. Data File Name: MigrationDataFile.xml
4. Complete the “Source Server Settings” section as follows:
a. Source TFS URL: http://[yourtfshost]:8080
b. Click Connect.
(This loads the project list)
c. Source Project Name: Source project name
d. If the date format of the TFS machine differs from the execution machine, enter the TFS date format here. Otherwise leave blank.
Example: MM/dd/yyyy HH:mm:ss
5. Complete the “Target Server Settings” as follows:
a. Target TFS URL: http://[yourtfshost]:8080
b. Click Connect. (This loads the project list)
c. Target Project Name: DemoTarget (as created in step 1)
d. Installation User Name: The SfTS installation account
Note: This account must be the same as the account used to install the template.
e. Delete Existing Sprint Work Items: Checked
f. Refresh TFS Warehouse: Checked
g. Demo Mode: Not-Checked
6. Save the project definition as “DemoMigration.migproj”
7. Click the “Execute Migration Project” to begin the migration.
During the migration process several console windows will open and display the process activity. When a console window process finishes it may be necessary to hit the return key in order to continue the migration process (Note: Do not close the console windows by clicking the [X] or pressing [ctrl]+C. This will throw an exception and stop the migration process). The exported data files will be written to the working folder specified in step 3.
a. Exporting the Work Item Data:
b. Importing the Work Item Data:
c. Refreshing the Data Warehouse:
8. You have now migrated the work item data into the new “DemoTarget” project
What doesn't it do?
It is important to note that this utility does not migrate source code, build process or any version control information.
This utility was not created with the intention of being released as a third party utility. Please use with care and ensure that any important data is backed up prior to use. It is always advisable to create and migrate some test projects prior to attempting a large migration.
If you experience any problems while using this utility, please visit the Scrum for Team System and use the community forum.
Note: The attachment has been updated to solve a date parse error reported by some users - Crispin 21/10/2008
Note: Areas and Iteration paths are NOT support by this utility.