WorkItemMigrationContext

Ref

  

Less than 1 minute to read

  

2024-09-06 09:35:04 +0100

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
AttachRevisionHistory	Boolean	This will create a json file with the revision history and attach it to the work item. Best used with `MaxRevisions` or `ReplayRevisions`.	?
Enabled	Boolean	If enabled then the processor will run	false
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.	?
GenerateMigrationComment	Boolean	If enabled, adds a comment recording the migration	false
MaxGracefulFailures	Int32	The maximum number of failures to tolerate before the migration fails. When set above zero, a work item migration error is logged but the migration will continue until the number of failed items reaches the configured value, after which the migration fails.	0
PauseAfterEachWorkItem	Boolean	Pause after each work item is migrated	false
SkipRevisionWithInvalidAreaPath	Boolean	When set to true, this setting will skip a revision if the source area has not been migrated, has been deleted or is somehow invalid, etc.	missng XML code comments
SkipRevisionWithInvalidIterationPath	Boolean	This will skip a revision if the source iteration has not been migrated i.e. it was deleted	missng 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
WorkItemIDs	IList	A list of work items to import	[]

Example

A basic sample for WorkItemMigrationContext configuration.

{
  "$type": "WorkItemMigrationConfig",
  "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,
  "PauseAfterEachWorkItem": false,
  "AttachRevisionHistory": false,
  "GenerateMigrationComment": true,
  "WorkItemIDs": null,
  "MaxGracefulFailures": 0,
  "SkipRevisionWithInvalidIterationPath": false,
  "SkipRevisionWithInvalidAreaPath": false
}

WIQL Query Bits

The Work Item queries are all built using Work Item Query Language (WIQL).

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 ProcessorEnricher TfsNodeStructure

Iteration Maps and Area Maps

Moved to the ProcessorEnricher 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