[preview] Export users for mapping context

.gitignore

@@ -162,3 +162,4 @@ $RECYCLE.BIN/
 
 docs/Reference/Generated/MigrationTools.Host.xml
 /docs/Reference/Generated/MigrationTools.Host.xml
+/docs/.obsidian

GitVersion.yml

@@ -1,20 +1,36 @@
 assembly-versioning-scheme: MajorMinorPatch
 mode: ContinuousDeployment
 continuous-delivery-fallback-tag: ''
-next-version: 12.5.0
+next-version: 15.0.1
 branches:
  main:
  mode: ContinuousDeployment
  tag: ''
+ increment: Patch
  regex: ^master$|^main$
  is-release-branch: true
  is-mainline: true
+ prevent-increment-of-merged-branch-version: true
+ track-merge-target: false
+ tracks-release-branches: false
  preview:
+ mode: ContinuousDeployment
  tag: Preview
  regex: ^((?!(master)|(feature)|(pull)).)
  is-release-branch: false
  is-mainline: false
  source-branches: [ 'main', 'master' ]
+ prevent-increment-of-merged-branch-version: false
+ track-merge-target: false
+ tracks-release-branches: true
+ feature:
+ mode: ContinuousDelivery
+ tag: useBranchName
+ increment: Inherit
+ regex: features?[/-]
+ prevent-increment-of-merged-branch-version: false
+ track-merge-target: false
+ tracks-release-branches: false
 ignore:
  sha: []
 merge-message-formats: {}

configuration.json

@@ -2,8 +2,8 @@
  "ChangeSetMappingFile": null,
  "Source": {
  "$type": "TfsTeamProjectConfig",
- "Collection": "https://dev.azure.com/nkdagility-preview/",
- "Project": "migrationSource1",
+ "Collection": "https://dev.azure.com/nkdagility/",
+ "Project": "AzureDevOps-Tools",
  "ReflectedWorkItemIDFieldName": "nkdScrum.ReflectedWorkItemId",
  "AllowCrossProjectLinking": false,
  "AuthenticationMode": "Prompt",
@@ -75,31 +75,47 @@
  "Description": "Remove invalid characters from the end of the string"
  }
  ]
+ },
+ {
+ "$type": "TfsUserMappingEnricherOptions",
+ "Enabled": true,
+ "UserMappingFile": "C:\\temp\\userExport.json",
+ "IdentityFieldsToCheck": [
+ "System.AssignedTo",
+ "System.ChangedBy",
+ "System.CreatedBy",
+ "Microsoft.VSTS.Common.ActivatedBy",
+ "Microsoft.VSTS.Common.ResolvedBy",
+ "Microsoft.VSTS.Common.ClosedBy"
+ ]
  }
  ],
  "Processors": [
  {
  "$type": "WorkItemMigrationConfig",
- "Enabled": true,
+ "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",
  "LinkMigration": true,
- "AttachmentMigration": true,
- "AttachmentWorkingPath": "c:\\temp\\WorkItemAttachmentWorkingFolder\\",
  "FixHtmlAttachmentLinks": false,
  "SkipToFinalRevisedWorkItemType": false,
  "WorkItemCreateRetryLimit": 5,
  "FilterWorkItemsThatAlreadyExistInTarget": false,
  "PauseAfterEachWorkItem": false,
- "AttachmentMaxSize": 480000000,
  "AttachRevisionHistory": false,
  "LinkMigrationSaveEachAsAdded": false,
  "GenerateMigrationComment": true,
  "WorkItemIDs": null,
  "MaxGracefulFailures": 0,
  "SkipRevisionWithInvalidIterationPath": false,
  "SkipRevisionWithInvalidAreaPath": false
+ },
+ {
+ "$type": "ExportUsersForMappingConfig",
+ "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",
+ "OnlyListUsersInWorkItems": true
  }
  ],
  "Version": "15.0",

docs/Reference/v1/Processors/ExportUsersForMapping-notes.md

@@ -1,18 +1,83 @@
-## Additional Samples & Info
+There was a request to have the ability to map users to try and maintain integrity across different systems. We added a `TfsUserMappingEnricher` that allows you to map users from Source to Target.
+
+##How it works
+
+1. Run `ExportUsersForMappingConfig` which will export all of the Users in Source Mapped or not to target.
+2. Run `WorkItemMigrationConfig` which will run a validator by detail to warn you of missing users. If it finds a mapping it will convert the field... 
+
+## ExportUsersForMappingConfig
+
+Running the `ExportUsersForMappingConfig` to get the list of users will produce something like:
+
+```
+[
+ {
+ "Source": {
+ "FriendlyName": "Martin Hinshelwood nkdAgility.com",
+ "AccountName": "martin@nkdagility.com"
+ },
+ "target": {
+ "FriendlyName": "Hinshelwood, Martin",
+ "AccountName": "martin@othercompany.com"
+ }
+ },
+ {
+ "Source": {
+ "FriendlyName": "Rollup Bot",
+ "AccountName": "Bot@nkdagility.com"
+ },
+ "target": {
+ "FriendlyName": "Service Account 4",
+ "AccountName": "randoaccount@somecompany.com"
+ }
+ },
+ {
+ "Source": {
+ "FriendlyName": "Another non mapped Account",
+ "AccountName": "not-mapped@nkdagility.com"
+ },
+ "target": null
+ }
+]
+```
+
+Any `null` in the target field means that the user is not mapped. You can then use this to create a mapping file will all of your users.
+
+IMPORTANT: The Friendly name in Azure DevOps / TFS is not nessesarily the AAD Friendly name as users can change this in the tool. We load all of the users from both systems, and match on "email" to ensure we only assume mapping for the same user. Non mapped users, or users listed as null, will not be mapped.
+
+### Notes
+
+- On `ExportUsersForMappingConfig` you can set `OnlyListUsersInWorkItems` to filter the mapping based on the scope of the query. This is greater if you have many users.
+- Configured using the `TfsUserMappingEnricherOptions` setting in `CommonEnrichersConfig`
+
+## WorkItemMigrationConfig
+
+When you run the `WorkItemMigrationContext`
+
 
 ```
-{
- "$type": "ExportUsersForMappingConfig",
- "Enabled": false,
- "LocalExportJsonFile": "c:\\temp\\ExportUsersForMappingConfig.json",
- "WIQLQuery": "SELECT [System.Id], [System.Tags] FROM WorkItems WHERE [System.TeamProject] = @TeamProject AND [System.WorkItemType] NOT IN ('Test Suite', 'Test Plan') ORDER BY [System.ChangedDate] desc",
- "IdentityFieldsToCheck": [
- "System.AssignedTo",
- "System.ChangedBy",
- "System.CreatedBy",
- "Microsoft.VSTS.Common.ActivatedBy",
- "Microsoft.VSTS.Common.ResolvedBy",
- "Microsoft.VSTS.Common.ClosedBy"
- ]
-}
-```
+...
+ "LogLevel": "Debug",
+ "CommonEnrichersConfig": [
+ {
+ "$type": "TfsUserMappingEnricherOptions",
+ "Enabled": true,
+ "UserMappingFile": "C:\\temp\\userExport.json",
+ "IdentityFieldsToCheck": [
+ "System.AssignedTo",
+ "System.ChangedBy",
+ "System.CreatedBy",
+ "Microsoft.VSTS.Common.ActivatedBy",
+ "Microsoft.VSTS.Common.ResolvedBy",
+ "Microsoft.VSTS.Common.ClosedBy"
+ ]
+ }
+ ],
+...
+```
+
+
+### Notes
+
+- Configured using the `TfsUserMappingEnricherOptions` setting in `CommonEnrichersConfig`
+- Applies to all identity fields specified in the list

docs/Reference/v2/ProcessorEnrichers/TfsNodeStructure-notes.md

@@ -7,7 +7,7 @@
 
 You have two options to solve this problem:
 
-1. You can manualy create the mentioned work items. This is a good option if you have a small number of work items or a small number of missing nodes. This will not work if you have work items that were moved from one project to another. Those Nodes are imposible to create in the target project.
+1. You can manually create the mentioned work items. This is a good option if you have a small number of work items or a small number of missing nodes. This will not work if you have work items that were moved from one project to another. Those Nodes are impossible to create in the target project.
 1. You can use the `AreaMaps` and `IterationMaps` to remap the nodes to existing nodes in the target project. This is a good option if you have a large number of work items or a large number of missing nodes.
 
 ### Overview

docs/_data/reference.v1.processors.exportusersformappingcontext.yaml

@@ -0,0 +1,34 @@
+optionsClassName: ExportUsersForMappingConfig
+optionsClassFullName: MigrationTools._EngineV1.Configuration.Processing.ExportUsersForMappingConfig
+configurationSamples:
+- name: default
+ description: 
+ code: >-
+ {
+ "$type": "ExportUsersForMappingConfig",
+ "Enabled": false,
+ "WIQLQuery": null,
+ "OnlyListUsersInWorkItems": true
+ }
+ sampleFor: MigrationTools._EngineV1.Configuration.Processing.ExportUsersForMappingConfig
+description: ExportUsersForMappingContext is a tool used to create a starter mapping file for users between the source and target systems. Use `ExportUsersForMappingConfig` to configure.
+className: ExportUsersForMappingContext
+typeName: Processors
+architecture: v1
+options:
+- parameterName: Enabled
+ type: Boolean
+ description: missng XML code comments
+ defaultValue: missng XML code comments
+- parameterName: OnlyListUsersInWorkItems
+ type: Boolean
+ description: missng XML code comments
+ defaultValue: missng XML code comments
+- parameterName: WIQLQuery
+ type: String
+ description: missng XML code comments
+ defaultValue: missng XML code comments
+status: ready
+processingTarget: Work Items
+classFile: ''
+optionsClassFile: /src/MigrationTools/_EngineV1/Configuration/Processing/ExportUsersForMappingConfig.cs

docs/_data/reference.v2.processorenrichers.tfsattachmentenricher.yaml

@@ -8,7 +8,7 @@ configurationSamples:
  "$type": "TfsAttachmentEnricherOptions",
  "Enabled": true,
  "ExportBasePath": "c:\\temp\\WorkItemAttachmentExport",
- "MaxAttachmentSize": "480000000"
+ "MaxAttachmentSize": 480000000
  }
  sampleFor: MigrationTools.Enrichers.TfsAttachmentEnricherOptions
 description: missng XML code comments
@@ -25,7 +25,7 @@ options:
  description: '`AttachmentMigration` is set to true then you need to specify a working path for attachments to be saved locally.'
  defaultValue: C:\temp\Migration\
 - parameterName: MaxAttachmentSize
- type: String
+ type: Int32
  description: '`AttachmentMigration` is set to true then you need to specify a max file size for upload in bites. For Azure DevOps Services the default is 480,000,000 bites (60mb), for TFS its 32,000,000 bites (4mb).'
  defaultValue: 480000000
 - parameterName: RefName

docs/_data/reference.v2.processorenrichers.tfsusermappingenricher.yaml

@@ -1,12 +1,45 @@
-optionsClassName: 
-optionsClassFullName: 
-configurationSamples: []
-description: missng XML code comments
+optionsClassName: TfsUserMappingEnricherOptions
+optionsClassFullName: MigrationTools.Enrichers.TfsUserMappingEnricherOptions
+configurationSamples:
+- name: default
+ description: 
+ code: >-
+ {
+ "$type": "TfsUserMappingEnricherOptions",
+ "Enabled": true,
+ "IdentityFieldsToCheck": [
+ "System.AssignedTo",
+ "System.ChangedBy",
+ "System.CreatedBy",
+ "Microsoft.VSTS.Common.ActivatedBy",
+ "Microsoft.VSTS.Common.ResolvedBy",
+ "Microsoft.VSTS.Common.ClosedBy"
+ ],
+ "UserMappingFile": null
+ }
+ sampleFor: MigrationTools.Enrichers.TfsUserMappingEnricherOptions
+description: The TfsUserMappingEnricher is used to map users from the source to the target system. Run it with the ExportUsersForMappingContext to create a mapping file then with WorkItemMigrationContext to use the mapping file to update the users in the target system as you migrate the work items.
 className: TfsUserMappingEnricher
 typeName: ProcessorEnrichers
 architecture: v2
-options: []
+options:
+- parameterName: Enabled
+ type: Boolean
+ description: If enabled this will run this migrator
+ defaultValue: true
+- parameterName: IdentityFieldsToCheck
+ type: List
+ description: This is a list of the Identiy fields in the Source to check for user mapping purposes. You should list all identiy fields that you wan to map.
+ defaultValue: missng XML code comments
+- parameterName: RefName
+ type: String
+ description: For internal use
+ defaultValue: missng XML code comments
+- parameterName: UserMappingFile
+ type: String
+ description: This is the file that will be used to export or import the user mappings. Use the ExportUsersForMapping processor to create the file.
+ defaultValue: missng XML code comments
 status: missng XML code comments
 processingTarget: missng XML code comments
-classFile: /src/MigrationTools.Clients.AzureDevops.ObjectModel/Enrichers/TfsUserMappingEnricher.cs
-optionsClassFile: 
+classFile: /src/MigrationTools.Clients.AzureDevops.ObjectModel/ProcessorEnrichers/TfsUserMappingEnricher.cs
+optionsClassFile: /src/MigrationTools.Clients.AzureDevops.ObjectModel/ProcessorEnrichers/TfsUserMappingEnricherOptions.cs