Are there sample configuration files to migrate team-specific work items when splitting and merging Azure DevOps Projects

Question

We need to migrate selected work item types for a specific team (under area path X) from an on-prem TFS Server to Azure DevOps. We have tried to set the QueryBit and BasePaths to the source area path but are not having any success to filter the work items for the team.

• Should we be using QueryBit or BasePaths, or both?
• Are there any sample configuration files that can be used as a quick start or reference?

We have watched the overview video a couple of times and battling to find the relevant documentation.

Answer 1

You should be using the QueryBit to scope the workitem to just what you want. For a Team you should look to scope to specific area paths that are owned by that team.

The latest version has some example configs (not all in date) for reference in the SampleConfigs folder.

e.g.

{
  "Version": "0.0",
  "TelemetryEnableTrace": false,
  "workaroundForQuerySOAPBugEnabled": false,
  "ChangeSetMappingFile": null,
  "Source": {
    "Collection": "https://dev.azure.com/nkdagility-preview/",
    "Project": "migrationSource1",
    "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId",
    "AllowCrossProjectLinking": false,
    "PersonalAccessToken": "",
    "LanguageMaps": {
      "AreaPath": "Area",
      "IterationPath": "Iteration"
    }
  },
  "Target": {
    "Collection": "https://dev.azure.com/nkdagility-preview/",
    "Project": "migrationTarget1",
    "ReflectedWorkItemIDFieldName": "Custom.ReflectedWorkItemId",
    "AllowCrossProjectLinking": false,
    "PersonalAccessToken": "",
    "LanguageMaps": {
      "AreaPath": "Area",
      "IterationPath": "Iteration"
    }
  },
  "FieldMaps": [
    {
      "ObjectType": "MultiValueConditionalMapConfig",
      "WorkItemTypeName": "*",
      "sourceFieldsAndValues": {
        "Field1": "Value1",
        "Field2": "Value2"
      },
      "targetFieldsAndValues": {
        "Field1": "Value1",
        "Field2": "Value2"
      }
    },
    {
      "ObjectType": "FieldBlankMapConfig",
      "WorkItemTypeName": "*",
      "targetField": "TfsMigrationTool.ReflectedWorkItemId"
    },
    {
      "ObjectType": "FieldValueMapConfig",
      "WorkItemTypeName": "*",
      "sourceField": "System.State",
      "targetField": "System.State",
      "defaultValue": "New",
      "valueMapping": {
        "Approved": "New",
        "New": "New",
        "Committed": "Active",
        "In Progress": "Active",
        "To Do": "New",
        "Done": "Closed",
        "Removed": "Removed"
      }
    },
    {
      "ObjectType": "FieldtoFieldMapConfig",
      "WorkItemTypeName": "*",
      "sourceField": "Microsoft.VSTS.Common.BacklogPriority",
      "targetField": "Microsoft.VSTS.Common.StackRank",
      "defaultValue": null
    },
    {
      "ObjectType": "FieldtoFieldMultiMapConfig",
      "WorkItemTypeName": "*",
      "SourceToTargetMappings": {
        "SourceField1": "TargetField1",
        "SourceField2": "TargetField2"
      }
    },
    {
      "ObjectType": "FieldtoTagMapConfig",
      "WorkItemTypeName": "*",
      "sourceField": "System.State",
      "formatExpression": "ScrumState:{0}"
    },
    {
      "ObjectType": "FieldMergeMapConfig",
      "WorkItemTypeName": "*",
      "sourceField1": "System.Description",
      "sourceField2": "Microsoft.VSTS.Common.AcceptanceCriteria",
      "targetField": "System.Description",
      "formatExpression": "{0} <br/><br/><h3>Acceptance Criteria</h3>{1}",
      "doneMatch": "##DONE##"
    },
    {
      "ObjectType": "RegexFieldMapConfig",
      "WorkItemTypeName": "*",
      "sourceField": "COMPANY.PRODUCT.Release",
      "targetField": "COMPANY.DEVISION.MinorReleaseVersion",
      "pattern": "PRODUCT \\d{4}.(\\d{1})",
      "replacement": "$1"
    },
    {
      "ObjectType": "FieldValuetoTagMapConfig",
      "WorkItemTypeName": "*",
      "sourceField": "Microsoft.VSTS.CMMI.Blocked",
      "pattern": "Yes",
      "formatExpression": "{0}"
    },
    {
      "ObjectType": "TreeToTagMapConfig",
      "WorkItemTypeName": "*",
      "toSkip": 3,
      "timeTravel": 1
    }
  ],
  "WorkItemTypeDefinition": { "sourceWorkItemTypeName": "targetWorkItemTypeName" },
  "GitRepoMapping": null,
  "Processors": [
    {
      "ObjectType": "NodeStructuresMigrationConfig",
      "PrefixProjectToNodes": false,
      "Enabled": false,
      "BasePaths": [ "Product\\Area\\Path1", "Product\\Area\\Path2" ]
    },
    {
      "ObjectType": "WorkItemMigrationConfig",
      "ReplayRevisions": true,
      "PrefixProjectToNodes": false,
      "UpdateCreatedDate": true,
      "UpdateCreatedBy": true,
      "BuildFieldTable": false,
      "AppendMigrationToolSignatureFooter": false,
      "QueryBit": "AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan')",
      "OrderBit": "[System.ChangedDate] desc",
      "Enabled": false,
      "LinkMigration": true,
      "AttachmentMigration": true,
      "AttachmentWorkingPath": "c:\\temp\\WorkItemAttachmentWorkingFolder\\",
      "FixHtmlAttachmentLinks": false,
      "SkipToFinalRevisedWorkItemType": false,
      "WorkItemCreateRetryLimit": 5,
      "FilterWorkItemsThatAlreadyExistInTarget": true,
      "PauseAfterEachWorkItem": false,
      "AttachmentMaxSize": 480000000,
      "CollapseRevisions": false,
      "LinkMigrationSaveEachAsAdded": false
    },
    {
      "ObjectType": "TestVariablesMigrationConfig",
      "Enabled": false
    },
    {
      "ObjectType": "TestConfigurationsMigrationConfig",
      "Enabled": false
    },
    {
      "ObjectType": "TestPlansAndSuitesMigrationConfig",
      "PrefixProjectToNodes": false,
      "Enabled": false,
      "OnlyElementsWithTag": null,
      "TestPlanQueryBit": null,
      "RemoveInvalidTestSuiteLinks": false
    },
    {
      "ObjectType": "ImportProfilePictureConfig",
      "Enabled": false
    },
    {
      "ObjectType": "ExportProfilePictureFromADConfig",
      "Domain": null,
      "Username": null,
      "Password": null,
      "PictureEmpIDFormat": null,
      "Enabled": false
    },
    {
      "ObjectType": "FixGitCommitLinksConfig",
      "TargetRepository": "migrationTarget1",
      "Enabled": false,
      "QueryBit": null,
      "OrderBit": null
    },
    {
      "ObjectType": "WorkItemUpdateConfig",
      "WhatIf": false,
      "QueryBit": "AND [TfsMigrationTool.ReflectedWorkItemId] = '' AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] IN ('Shared Steps', 'Shared Parameter', 'Test Case', 'Requirement', 'Task', 'User Story', 'Bug')",
      "Enabled": false
    },
    {
      "ObjectType": "WorkItemPostProcessingConfig",
      "QueryBit": "AND [TfsMigrationTool.ReflectedWorkItemId] = '' ",
      "WorkItemIDs": [ 1, 2, 3 ],
      "Enabled": false
    },
    {
      "ObjectType": "WorkItemDeleteConfig",
      "Enabled": false
    },
    {
      "ObjectType": "WorkItemQueryMigrationConfig",
      "PrefixProjectToNodes": false,
      "SharedFolderName": "Shared Queries",
      "SourceToTargetFieldMappings": { "SourceFieldRef": "TargetFieldRef" },
      "Enabled": false
    },
    {
      "ObjectType": "TeamMigrationConfig",
      "Enabled": false,
      "PrefixProjectToNodes": false,
      "EnableTeamSettingsMigration": true
    }
  ]
}

The main workhorse is the WorkItemMigrationConfig that contains the QueryBit.

    {
      "ObjectType": "WorkItemMigrationConfig",
      "ReplayRevisions": true,
      "PrefixProjectToNodes": false,
      "UpdateCreatedDate": true,
      "UpdateCreatedBy": true,
      "BuildFieldTable": false,
      "AppendMigrationToolSignatureFooter": false,
      "QueryBit": "AND  [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan')",
      "OrderBit": "[System.ChangedDate] desc",
      "Enabled": false,
      "LinkMigration": true,
      "AttachmentMigration": true,
      "AttachmentWorkingPath": "c:\\temp\\WorkItemAttachmentWorkingFolder\\",
      "FixHtmlAttachmentLinks": false,
      "SkipToFinalRevisedWorkItemType": false,
      "WorkItemCreateRetryLimit": 5,
      "FilterWorkItemsThatAlreadyExistInTarget": true,
      "PauseAfterEachWorkItem": false,
      "AttachmentMaxSize": 480000000,
      "CollapseRevisions": false,
      "LinkMigrationSaveEachAsAdded": false
    },

This particular query bit is my goto default and excludes closed items nad test Suits, and Plans.

"QueryBit": "AND [Microsoft.VSTS.Common.ClosedDate] = '' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan')"

To scope just to a Team you may use:

"QueryBit": "AND [System.Area] = '\MyTeamName' AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan')"