Tfs WorkItem Migration Processor

Options

Samples

Sample

{
  "MigrationTools": {
    "Version": "16.0",
    "Processors": [
      {
        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "Enabled": "False",
        "FilterWorkItemsThatAlreadyExistInTarget": "False",
        "SourceName": "Source",
        "TargetName": "Target",
        "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"
      }
    ]
  }
}

Defaults

{
  "MigrationTools": {
    "Version": "16.0",
    "Processors": [
      {
        "ProcessorType": "TfsWorkItemMigrationProcessor",
        "AttachRevisionHistory": "False",
        "Enabled": "False",
        "FilterWorkItemsThatAlreadyExistInTarget": "False",
        "FixHtmlAttachmentLinks": "True",
        "GenerateMigrationComment": "True",
        "MaxGracefulFailures": "0",
        "PauseAfterEachWorkItem": "False",
        "SkipRevisionWithInvalidAreaPath": "False",
        "SkipRevisionWithInvalidIterationPath": "False",
        "SourceName": "Source",
        "TargetName": "Target",
        "UpdateCreatedBy": "True",
        "UpdateCreatedDate": "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",
        "WorkItemCreateRetryLimit": "5",
        "WorkItemIDs": null
      }
    ]
  }
}

Classic

{
  "$type": "TfsWorkItemMigrationProcessorOptions",
  "Enabled": false,
  "UpdateCreatedDate": true,
  "UpdateCreatedBy": 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",
  "FixHtmlAttachmentLinks": true,
  "WorkItemCreateRetryLimit": 5,
  "FilterWorkItemsThatAlreadyExistInTarget": false,
  "GenerateMigrationComment": true,
  "SourceName": "Source",
  "TargetName": "Target"
}

Metadata

The WorkItemMigrationContext processor is used for migrating work items from one Azure DevOps instance to another. This encompasses a variety of activities:

1. Transferring Work Items Between Instances: The primary purpose of the processor is to transfer work items, including bugs, tasks, user stories, features, and more, from one Azure DevOps instance to another.

2. Migrating Work Item History: The processor can also replicate the entire revision history of work items, providing continuity and maintaining a record of changes.

3. Migrating Attachments and Links: The processor can transfer any attachments or links associated with work items. This includes both external links and internal links to other work items.

4. Updating Metadata: If configured, the processor can update the “Created Date” and “Created By” fields on migrated work items to match the original items in the source instance.

5. Filtering Work Items: The processor can be configured to only migrate certain work items based on their area or iteration paths.

Overall, the WorkItemMigrationContext processor is a comprehensive tool for transferring work items and their associated data and metadata between Azure DevOps instances. It should be used whenever there is a need to move work items between instances while preserving as much information as possible.

WIQL Query

The Work Item queries are all built using Work Item Query Language (WIQL) . We only support flat quereis that have FROM WorkItems in the query.

Note: A useful Azure DevOps Extension to explore WIQL is the WIQL Editor

Examples

You can use the WIQL Editor to craft a query in Azure DevOps.

A simple example config:

"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"

Scope to Area Path (Team data):

"WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.AreaPath] UNDER 'project\Team 1\' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request') ORDER BY [System.ChangedDate] desc"

Limit to specific work items (for testing purposes)

"WIQLQuery": "SELECT [System.Id] FROM WorkItems WHERE [System.Id] in (123,456,789) AND [System.TeamProject] = @TeamProject AND [System.AreaPath] UNDER 'project\Team 1\' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan','Shared Steps','Shared Parameter','Feedback Request') ORDER BY [System.ChangedDate] desc"

NodeBasePath Configuration

Moved to the TfsNodeStructure

Iteration Maps and Area Maps

Moved to the TfsNodeStructure

More Complex Team Migrations

The above options allow you to bring over a sub-set of the WIs (using the WIQLQueryBit) and move their area or iteration path to a default location. However you may wish to do something more complex e.g. re-map the team structure. This can be done with addition of a FieldMaps block to configuration in addition to the NodeBasePaths.

Using the above sample structure, if you wanted to map the source project Team 1 to target project Team A etc. you could add the field map as follows

A complete list of FieldMaps are available.

 "FieldMaps": [
   {
      "$type": "FieldValueMapConfig",
      "WorkItemTypeName": "*",
      "sourceField": "System.AreaPath",
      "targetField": "System.AreaPath",
      "defaultValue": "TargetProg",
      "valueMapping": {
        "SampleProj\\Team 1": "TargetProg\\Team A",
        "SampleProj\\Team 2": "TargetProg\\Team B"
        "SampleProj\\Team 3": "TargetProg\\Team C"
      }
    },
  ],

Note: These mappings could also be achieved with other forms of Field mapper e.g. RegexFieldMapConfig, but the value mapper as an example is easy to understand

Removed Properties

• PrefixProjectToNodes - This option was removed in favour of the Area and Iteration Maps on TfsNodeStructure