-
-
Notifications
You must be signed in to change notification settings - Fork 345
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Export users for mapping context (#1969)
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... this is not free
and takes some work. Runnin the `ExportUsersForMappingConfig` to get the
list of users will produce:
```
[
{
"Source": {
"FriendlyName": "Martin Hinshelwood nkdAgility.com",
"AccountName": "[email protected]"
},
"target": {
"FriendlyName": "Hinshelwood, Martin",
"AccountName": "[email protected]"
}
},
{
"Source": {
"FriendlyName": "Rollup Bot",
"AccountName": "[email protected]"
},
"target": {
"FriendlyName": "Service Account 4",
"AccountName": "[email protected]"
}
},
{
"Source": {
"FriendlyName": "Another non mapped Account",
"AccountName": "[email protected]"
},
"target": null
}
]
```
##How it works
1. Run `ExportUsersForMappingConfig` which will export all of the Users
in Soruce 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...
##Notes
- Applies to all identity fields specified in the list
- It really sucks that we have to match on Display name! Email is
included for internal matching
- 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.
- Both use the `TfsUserMappingEnricherOptions` setting in
`CommonEnrichersConfig` to know what to do.
```
{
"ChangeSetMappingFile": null,
"Source": {
"$type": "TfsTeamProjectConfig",
"Collection": "https://dev.azure.com/nkdagility/",
"Project": "AzureDevOps-Tools",
"ReflectedWorkItemIDFieldName": "nkdScrum.ReflectedWorkItemId",
"AllowCrossProjectLinking": false,
"AuthenticationMode": "Prompt",
"PersonalAccessToken": "",
"PersonalAccessTokenVariableName": "",
"LanguageMaps": {
"AreaPath": "Area",
"IterationPath": "Iteration"
}
},
"Target": {
"$type": "TfsTeamProjectConfig",
"Collection": "https://dev.azure.com/nkdagility-preview/",
"Project": "migrationTest5",
"ReflectedWorkItemIDFieldName": "nkdScrum.ReflectedWorkItemId",
"AllowCrossProjectLinking": false,
"AuthenticationMode": "Prompt",
"PersonalAccessToken": "",
"PersonalAccessTokenVariableName": "",
"LanguageMaps": {
"AreaPath": "Area",
"IterationPath": "Iteration"
}
},
"FieldMaps": [],
"GitRepoMapping": null,
"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"
]
}
],
"Processors": [
{
"$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"
}
```
Resolves #1976- Loading branch information
Showing
29 changed files
with
710 additions
and
171 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: {} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
15 changes: 15 additions & 0 deletions
15
docs/Reference/Generated/MigrationTools.Clients.AzureDevops.ObjectModel.xml
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
97 changes: 81 additions & 16 deletions
97
docs/Reference/v1/Processors/ExportUsersForMapping-notes.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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": "[email protected]" | ||
| }, | ||
| "target": { | ||
| "FriendlyName": "Hinshelwood, Martin", | ||
| "AccountName": "[email protected]" | ||
| } | ||
| }, | ||
| { | ||
| "Source": { | ||
| "FriendlyName": "Rollup Bot", | ||
| "AccountName": "[email protected]" | ||
| }, | ||
| "target": { | ||
| "FriendlyName": "Service Account 4", | ||
| "AccountName": "[email protected]" | ||
| } | ||
| }, | ||
| { | ||
| "Source": { | ||
| "FriendlyName": "Another non mapped Account", | ||
| "AccountName": "[email protected]" | ||
| }, | ||
| "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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
34 changes: 34 additions & 0 deletions
34
docs/_data/reference.v1.processors.exportusersformappingcontext.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
47 changes: 40 additions & 7 deletions
47
docs/_data/reference.v2.processorenrichers.tfsusermappingenricher.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.