Connection Role Copier

Connection Role Copier copies connection roles from a source Dataverse / Dynamics 365 environment (online, or on-premises 9.x) to a destination environment. Typical uses are moving the connection roles of a CX (Dynamics CRM on-premises) organisation to its CX365 successor, or copying roles between two CX365 environments.

• Roles keep their GUIDs. The roles you tick are created in the destination with the same GUIDs, names, descriptions, categories and status. Roles that are inactive in the source are deactivated.
• Record types are remapped. The record types each role applies to are either copied unchanged or remapped from CX to CX365 table names: incident to ptl_matter, systemuser to ptl_employee, site to ptl_branch, contact to contact and account, account to account and contact, and so on. A table the destination does not have, or one without connections enabled, is skipped. A role is never widened to all record types.
• Existing roles only get their record types aligned. A role that already exists in the destination (same GUID, or else the same name) keeps its name, description, category, status and links. Only its record types are synchronised to the source.
• Links and categories are carried over. Links to matching roles are recreated for the roles the tool creates. Categories are matched by label, never by value. A Category mapping dialog lets you choose the destination category, leave it blank, or create a missing category in the destination.
• You can see a copy before it runs. The grid shows, for every role, whether it is already in the destination and what a copy would change. A dry run goes through every step without writing anything. The roles can also be written into a destination solution of your choice. Every step goes to a colour-coded log that you can copy or save.

• XrmToolBox 1.2025.10.74 or later.
• .NET Framework 4.8. The tool is a .NET Framework 4.8 Windows Forms assembly. XrmToolBox provides every other assembly it uses.
• Environments: Dataverse / Dynamics 365 online, or Dynamics 365 on-premises 9.x, as source and destination. Writing to an on-premises destination has not been tested: the platform behaviours the tool relies on were verified on Dataverse online.
• Two connections: the source, which is the tab's XrmToolBox connection, and the destination, chosen with Select destination environment....
• Privileges:
  • The source is only read.
  • In the destination, the user needs create and write access to connection roles.
  • Creating categories needs customisation rights, because it changes the global option set connectionrole_category. Adding roles to a solution needs them too.
• Record-type mapping: the CX to CX365 remapping follows the rules of the CX365 Entity Field Migrator (CX365 ptl_ tables). Untick Apply CX to CX365 entity mapping to copy record types unchanged, for example between two CX365 environments.

Install from the XrmToolBox Tool Library

This is not available yet: Connection Role Copier is not published to nuget.org or the Tool Library. Use the manual install below.

Manual install

1. Close XrmToolBox.
2. Right-click the downloaded zip, choose Properties, tick Unblock and click OK. Windows marks files downloaded from the internet, and XrmToolBox cannot load a plugin DLL that is still marked.
3. Extract the downloaded zip into %AppData%\MscrmTools\XrmToolBox\Plugins. The zip holds one file, MyscotekConnectionRoleCopier.dll, which is the whole tool: XrmToolBox provides every other assembly it uses.
4. Start XrmToolBox and open Connection Role Copier from the tools list.

If the tool does not appear, make sure XrmToolBox was closed while the DLL was copied. As a last resort, close XrmToolBox and delete Plugins\manifest.json; it is rebuilt on the next start.

First use

1. Connect to the source. Open the tool and connect to the environment to copy from with the XrmToolBox connection bar. Its connection roles are listed at once.

2. Choose the destination. Click Select destination environment... and pick the environment to copy to. The grid then shows three things for every role:

   • whether it is already in the destination (In destination);
   • which record types it would get there (Mapped record types);
   • what a copy would change (Record type changes).

   If the destination looks like the same organisation as the source, you are asked to confirm before anything is copied.

3. Tick the roles to copy. Use the check boxes, Select all / Select none, Select new (roles that are new to the destination) or Select changed (roles a copy would change). Filter roles by name... narrows the list and keeps the ticks.

4. Check the categories with Category mapping.... For each source category, pick a destination category, leave it blank, or create it in the destination.

5. Choose the options.

   • Apply CX to CX365 entity mapping is on by default; untick it to copy record types unchanged.
   • Dry run (write nothing).
   • Optionally, a destination Solution.

   The options are remembered between sessions.

6. Copy. Click Copy selected roles. Progress and every step appear in the log. Cancel stops before the next role or link; a role that is being written is finished first. Copy log and Save log... keep the log.

Start with a dry run, because a real copy can change the record types of roles that already exist in the destination.

Settings are stored in %AppData%\MscrmTools\XrmToolBox\Settings\MyscotekConnectionRoleCopier.xml; edit that file only while XrmToolBox is closed. PageSize (50 - 5000, default 5000) can only be set there.

Limitations and notes

• Only connection roles, their record types and their links are copied, never connections. The source is only read.
• For a role that exists in the destination, only the record types change. Its name, description, category, status and links are never written; change those by hand. Roles with an ambiguous name are skipped.
• Changing the record types of a managed destination role adds an unmanaged customisation layer to that role. Untick such roles, or use a dry run first, when that is not wanted.
• A link to a role that is neither ticked nor in the destination is skipped with a warning. Tick the matching roles too.
• Roles that are managed in the source are created unmanaged in the destination.
• A copied role keeps its source GUID, but its record-type rows get new ones.
• A record type whose table is missing from the destination, or has connections disabled, is skipped. Enable Connections for that table in the destination, or accept the skip.
• Writing to on-premises destinations has not been tested.