Getting Started
Article
3 minutes to read
2024-10-30 09:13:32 +0000
If you want to perform a bulk edit or a migration then you need to start here. This tool has been tested on updating from 100 to 250,000 work items by its users.
Watch the Video Overview to get started in 30 minutes. This tool is complicated and it’s not always easy to discover what you need to do.
Prerequisits
- Install the tools using your prefered method.
- Check that you have the required Permissions to run the tools.
- Get to grips with the Configuration to understand how to configure the tool. (you can skup this for now and come back to it later)
Getting Started
This is going to be a crash course and I really recommend watching What can go wrong and what can go right with a migration via Azure DevOps and then Basic Work Item Migration with the Azure DevOps Migration Tools before you get started! This will prep you for the journey ahead.
1. Create a default configuration file
- Open your Windows Terminal in your chosen working folder
- Run
devopsmigration init --options Basic
to create a default configuration - Open
configuration.json
from the current directory
You can now customize the configuration depending on what you need to do. However, a basic config that you can use to migrate from one team project to another with the same process will likley look somethig like:
{
"Serilog": {
"MinimumLevel": "Information"
},
"MigrationTools": {
"Version": "16.0",
"Endpoints": {
"Source": {
"EndpointType": "TfsTeamProjectEndpoint",
"Collection": "https://dev.azure.com/nkdagility-preview/",
"Project": "migrationSource1",
"Authentication": {
"AuthenticationMode": "AccessToken",
"AccessToken": "jkashdjksahsjkfghsjkdaghvisdhuisvhladvnb"
}
},
"Target": {
"EndpointType": "TfsTeamProjectEndpoint",
"Collection": "https://dev.azure.com/nkdagility-preview/",
"Project": "migrationTest5",
"Authentication": {
"AuthenticationMode": "AccessToken",
"AccessToken": "lkasjioryislaniuhfhklasnhfklahlvlsdvnls"
},
"ReflectedWorkItemIdField": "Custom.ReflectedWorkItemId"
}
},
"CommonTools": {},
"Processors": [
{
"ProcessorType": "TfsWorkItemMigrationProcessor",
"Enabled": true,
"WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request') ORDER BY [System.ChangedDate] desc",
}
]
}
}
The default TfsWorkItemMigrationProcesor processor will perform the following operations:
- Migrate iterations and sprints
- Attachments
- Links including source code. Optionally clone the repositories before starting the migration to have links maintained on the initial pass.
How to execute configuration.json with minimal adjustments
Remember to add custom field ‘ReflectedWorkItemId’ to only the target team project before starting migration!
[NOTE!] In older versions of the tool we updated the Source work items with a link back to the Target to make migration easier. This has been removed and replaced with the
FilterWorkItemsThatAlreadyExistInTarget
option instead. You do not need to add the reflected work item ID custom field to the Source environment.
- Adjust the value of the
Collection
attribute for Source and Target - Adjust the value of the
Project
attribute for Source and Target -
Set the
AuthenticationMode
(Prompt
orAccessToken
) for Source and TargetIf you set Authentication mode to
AccessToken
, enter a valid PAT as value for thePersonalAccessToken
attribute, or set thePersonalAccessTokenVariableName
to the name of an environment variable containing your PAT. -
Adjust the value of the
ReflectedWorkItemIdField
attribute (field name of the migration tracking field) for Source and TargetFor example:
TfsMigrationTool.ReflectedWorkItemId
for TFS,ReflectedWorkItemId
for VSTS, orCustom.ReflectedWorkItemId
for Azure DevOps - Enable the
WorkItemMigrationConfig
processor by settingEnabled
totrue
- [OPTIONAL] Modify the
WIQLQueryBit
to migrate only the work items you want. The default WIQL will migrate all open work items and revisions excluding test suites and plans - Adjust the
NodeBasePaths
or leave empty to migrate all nodes - From your working folder run
devopsmigration execute --config .\configuration.json
Remember: If you want a processor to run, its Enabled
attribute must be set to true
.
Refer to the Reference Guide for more details.
Other Configuration Options
When running devopsmigration init
you can also pass --options
with one of the following:
- Full -
- WorkItemTracking -
- Fullv2 -
- WorkItemTrackingv2 -