Team Security Role Mapper compares Dataverse team security-role assignments in a source environment with a target environment, previews the differences, and applies only the changes selected by the operator.
Using the tool for the first time? Start with the illustrated user guide for connection setup, preview review, one-to-many mapping, safe application, and troubleshooting.
- Uses XrmToolBox's multi-connection workflow for separate source and target environments.
- Matches Entra group teams by Entra object ID first.
- Falls back to case-insensitive team name plus the relative business-unit path. Root business-unit names are intentionally ignored because they commonly differ by environment.
- Resolves each security role by name in the matched target team's business unit.
- Supports mapping one source team to one or more target teams when automatic matching is not suitable.
- Shows one preview row per source team, with all targets listed alphabetically in the target column.
- Uses one Apply choice for every target mapped to that source team.
- Supports editing the target list or explicitly leaving a source team unmapped without changing either environment.
- Exports and imports reusable JSON mapping profiles, including row selections and exact-sync mode.
- Filters the preview table by partial, case-insensitive source team name.
- Resets all local preview settings and reloads read-only data without updating Dataverse.
- Excludes access teams, which cannot hold security-role assignments.
- Never creates teams, business units, or security roles. These records must already exist in the target.
Loading a preview performs read operations only. The default mode is add-only, so target-only roles remain untouched.
Exact synchronization is deliberately opt-in. When enabled, the preview shows every role that would be removed. All target writes require a separate confirmation dialog that identifies the target connection and summarizes team, addition, and removal counts.
Ambiguous teams, missing roles, and ambiguous roles are blocked from application. During exact synchronization, additions are attempted before removals for each team; if an addition fails, no removals are attempted for that team.
Reset preview clears manual mappings, imported-profile state, checkbox choices, the source-team search, and exact-sync mode. It then reloads the preview using read operations only; it never calls the apply path or writes to Dataverse.
Remove mappings removes all targets from the selected source team and leaves it intentionally unmapped and non-actionable. To remove only some targets, reopen Map targets and edit the checked list. Auto match removes all manual mappings or the explicit unmap for that source and runs the normal matching rules again. These actions change only the local preview unless the operator later checks an actionable row and separately confirms Apply.
The complete user guide follows the normal operator workflow and uses screenshots with fictional environment data:
- Getting started and choosing connections
- Reviewing the preview and mapping teams
- Applying changes safely
- Saving and reusing mapping profiles
- Troubleshooting and frequently asked questions
Prerequisites:
- Windows
- .NET Framework 4.8 Developer Pack
- A current .NET SDK or Visual Studio with MSBuild
dotnet restore TeamSecurityRoleMapper.sln
dotnet test TeamSecurityRoleMapper.sln -c Release
dotnet build TeamSecurityRoleMapper.sln -c ReleaseThe release build creates:
artifacts/TeamSecurityRoleMapper.XrmToolBox.1.2.5.3.nupkgsrc/TeamSecurityRoleMapper/bin/Release/net48/TeamSecurityRoleMapper.dll
All automated tests use synthetic in-memory entities and a recording IOrganizationService; they do not connect to Dataverse or touch live data.
For local development, copy TeamSecurityRoleMapper.dll into an XrmToolBox Plugins folder and start XrmToolBox with that folder as its override path. For distribution, publish the generated NuGet package to a feed used by XrmToolBox Tool Library.
XrmToolBox caches plugin author and image metadata against the assembly version. Increment Version, AssemblyVersion, and FileVersion in the project whenever author, icon, description, or other exported metadata changes; otherwise XrmToolBox can continue displaying its cached values.
The Tool Library package metadata is maintained in src/TeamSecurityRoleMapper/TeamSecurityRoleMapper.nuspec.
After loading a preview, select Export to save a versioned JSON mapping profile. The profile records:
- Whether exact synchronization was enabled.
- Every source team shown in the preview and whether its grouped row was selected.
- All resolved target teams for a source team that was mapped to more than one target.
- The match method shown when the profile was saved.
Select Import to restore a JSON profile. A profile can be imported before loading a preview; it will be resolved after the next preview loads. Teams are resolved by Entra object ID when available, then by case-insensitive team name plus relative business-unit path. Saved targets are restored as explicit mappings so the same source-to-target choices are replayed.
One-to-many exports use profile format 2. The importer remains compatible with existing format 1 one-to-one profiles; format 2 prevents older tool versions from silently discarding additional targets.
If a saved source or target team is missing or ambiguous, that mapping is blocked and a warning is written to the activity log. Its saved Apply choice is retained so it returns if the mapping is repaired. Imported profiles never apply role changes by themselves; the normal preview review and target confirmation are still required.
Profiles do not contain credentials, connection strings, environment snapshots, or security-role assignments. They do contain the team names, business-unit paths, and Entra object IDs needed to identify mapped teams, so store them as environment configuration files.
- Open the tool and select Load preview.
- If either connection is missing, choose the prompted source and target environments.
- The preview loads automatically after both connections are available.
- Review matched, blocked, added, and removed counts.
- Use Search source teams to narrow a large preview without changing checkbox selections.
- Use Reset preview whenever all local choices should be cleared and the table reloaded.
- Use Map targets to check one or more targets for the selected source team, Remove mappings to intentionally clear all its targets, or Auto match to discard all manual mappings for that source.
- Select only the rows to apply.
- Optionally export the reviewed mappings and selections for future runs.
- Confirm the target and change totals.
- Refresh the preview after application to verify the current target state.
The operator needs permission to read business units, teams, security roles, and team-role associations in both environments, plus permission to manage team-role associations in the target.
Role names are environment-specific text. If environments use different role names or languages, the affected mapping is blocked and must be resolved in Dataverse before application. Manual mappings and selections survive preview refreshes for the same connections. Changing either connection clears that in-memory state; export a profile when it needs to be reused later.
The plugin targets .NET Framework 4.8 and references XrmToolBoxPackage 1.2025.10.74. It also pins MscrmTools.Xrm.Connection 1.2025.9.64 to the assembly version used by that XrmToolBox release.
MIT. See LICENSE.