Processors : TfsWorkItemMigrationProcessor

Ref

  

Less than 1 minute to read

  

2024-12-04 17:20:47 +0000

draft

This page is in draft and may include errors or omissions. Please check the discussions for any pending updates and changes to the content or to suggest your own changes.

WorkItemMigrationConfig is the main processor used to Migrate Work Items, Links, and Attachments. Use WorkItemMigrationConfig to configure.

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.

Options

Parameter name	Type	Description	Default Value
Enabled	Boolean	If set to `true` then the processor will run. Set to `false` and the processor will not run.	missing XML code comments
FilterWorkItemsThatAlreadyExistInTarget	Boolean	This loads all of the work items already saved to the Target and removes them from the Source work item list prior to commencing the run. While this may take some time in large data sets it reduces the time of the overall migration significantly if you need to restart.	true
FixHtmlAttachmentLinks	Boolean	**beta** If enabled this will fix any image attachments URL's, work item mention URL's or user mentions in the HTML fields as well as discussion comments. You must specify a PersonalAccessToken in the Source project for Azure DevOps; TFS should use integrated authentication.	true
GenerateMigrationComment	Boolean	If enabled, adds a comment recording the migration	true
SourceName	String	missing XML code comments	missing XML code comments
TargetName	String	missing XML code comments	missing XML code comments
UpdateCreatedBy	Boolean	If this is enabled the creation process on the target project will create the items with the original creation date. (Important: The item history is always pointed to the date of the migration, it's change only the data column CreateDate, not the internal create date)	true
UpdateCreatedDate	Boolean	If this is enabled the creation process on the target project will create the items with the original creation date. (Important: The item history is always pointed to the date of the migration, it's change only the data column CreateDate, not the internal create date)	true
WIQLQuery	String	A work item query based on WIQL to select only important work items. To migrate all leave this empty. See [WIQL Query Bits](#wiql-query-bits)	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	Int32	**beta** If set to a number greater than 0 work items that fail to save will retry after a number of seconds equal to the retry count. This allows for periodic network glitches not to end the process.	5

Examples

sample

This is an example of what your config might look like once configured.

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

These are the default values for this configuration. If you do not set it in your config the default always applies. You can overide by adding a diferent value in your config.

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

We have moved to a new config format, and you will need to update your old configs. This entry is a strate seralisation of the object and is here for legacy, and may provide value for debugging issues.

    {
  "$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"
}
    

## <a name="WIQLQuery"></a>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"

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: This 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