Upgrading Your MS Dynamics 365 Integration (CIF 1.0)

Requirements:

Comm Widget 2.0 requires BPCC 5.36.0 or later

Migration

Comm Widget 2.0 is compatible with both CIF 1.0 and CIF 2.0 (Channel Integration Framework). This guide covers CIF 1.0 specifically — for CIF 2.0 (Agent experience profiles), see the companion CIF 2.0 guide.

The app package is the same for the old and new widget, for both CIF 1.0 and CIF 2.0. For existing customers (on Universal Repeater or Comm Widget 1.0), migration is done simply by updating the Channel URL on the Channel Provider record to the Comm Widget 2.0 format.

The old and new widget can run side by side in the same Dynamics 365 instance for testing and gradual migration. Limitation: a user loads only one Channel Provider — in CIF 1.0 this is determined by their security role (via "Select the Roles for the Channel").

Set Up a New Channel Provider (CIF 1.0)

Open the Channel Integration Framework app, then create a new Channel Provider record. Alternatively, you can use an existing draft.
Update the Channel URL format to <contact center>/agent/crmembedded/adapters/msdyn-omnichannel.html
Under Select Unified Interface Apps for the Channel, choose the apps where the widget should be available (e.g. CRM Hub).
Under Select the Roles for the Channel, choose the role(s) that should get the new widget.

Note: If you plan to continue using an older widget as well as Comm Widget 2.0, make sure to exclude these roles from the old Channel Provider's role assignment, if applicable.
Save the record.
Open Customer Service Hub / CRM Hub and check the Channel panel. If the "Agent Desktop — Powered by Bright Pattern" login screen loads, the new Comm Widget 2.0 is connected and working correctly.

Using Multiple Widget Versions Concurrently

It is possible to have both the old and the new integration active in the same Dynamics 365 instance, for testing and gradual migration purposes, with the following exceptions:

Widgets cannot run simultaneously for the same user, since a user's app/role assignment determines which single Channel Provider they load in CIF 1.0.
Running them in parallel org-wide requires splitting access by security role in CIF 1.0.
- For example, users with RoleA are scoped to the old Channel Provider, and users with RoleB are scoped to the new Channel Provider.
Switching users back and forth between widget versions is done via role reassignment in CIF 1.0. No other configuration updates are required.

Create a Pilot Role for Testing

For a clean test, it's easiest to create a dedicated pilot security role (Settings > Security roles > New role), e.g. "BP_CommWidget2.0_Pilot", and simply add/remove that role on the test user instead of touching dozens of existing roles.


	Critically important: if the old Channel Provider's Select the Roles for the Channel field is left blank ("---"), that means "unrestricted" and matches every user regardless of their role. Assigning a pilot role to the new provider does not automatically override this. For roles to actually enforce exclusivity, the old provider also needs an explicit role assignment (e.g. a dedicated role like "BP_oldWidget") that excludes the pilot role.

Set Up a Clean (Non-Admin) Test User

To properly validate role-based routing, the test user must not be a System Administrator (see Important Notes below). The cleanest way is to create a brand new user dedicated to this test:

Go to portal.azure.com > Microsoft Entra ID > Users > New user to create a new user. Set the user's name and generate a password.
Go to admin.cloud.microsoft (Microsoft 365 admin center) > Users > Active users > select the user > Licenses and apps tab to assign the required Dynamics 365 license (e.g. "Dynamics 365 Customer Service Enterprise" trial) and any other app license needed (e.g. Power Automate). Then, press Save.

Note: Azure AD (Microsoft Entra) admin roles like "Dynamics 365 Administrator" and "Power Platform Administrator" are a separate, tenant-level privilege layer from Dynamics security roles. They do not automatically add "System Administrator" to the user's Dynamics security roles. It's fine to keep them if the account is also used for admin work.
Give the sync into the Dynamics 365 environment a few minutes, or use Power Platform admin center > Environments > the environment > Users > Refresh to speed it up.
In Dynamics 365 (via Power Platform admin center > Users > the new user > Manage roles), assign the real working Dynamics security role the user should normally have (e.g. "Customer Service Representative") plus the pilot role or the old-widget role from Create a Pilot Role for Testing above, instead of System Administrator.


	What actually causes the bypass is the Dynamics-internal System Administrator security role (visible under Power Platform admin center > Users > the user > Direct Assigned Roles), not the Azure AD tenant admin roles. Double-check that "System Administrator" isn't in that Direct Assigned Roles list for the test user.

Final Verification

As the test user (non-admin, with the pilot role added and access granted to the target app), open Customer Service Hub / CRM Hub and check the Channel panel. If the "Agent Desktop — Powered by Bright Pattern" login screen loads, the new Comm Widget 2.0 is connected and working correctly.

Important Notes

Role changes don't apply instantly.

After changing a user's role, click Refresh user (Power Platform admin center > Environments > the environment > Users > select the user > click Refresh user in the top command bar).
Then the user must fully sign out and sign back in (not just refresh the page) to update their permissions.

The System Administrator role bypasses Channel Provider restrictions.

If the test user is a System Administrator, they can match any Channel Provider regardless of what's set in Select the Roles for the Channel. Use a non-admin test user to properly validate role-based routing.

When assigning roles via the Manage Roles panel, double-check the resulting list before saving.

The confirmation dialog shows the full resulting set of roles for the user, not just the one you added. If only the new role ends up checked, saving will remove all of the user's other roles.

App access is a separate setting from the Channel Provider.

Even with the right role, a user may see a "We can't find any apps for your role" message if that role hasn't been granted access to the app itself (Customer Service Hub / CRM Hub).
To resolve this, in Dynamics 365, open the app management grid (Apps, showing published apps) > click "..." on the relevant app > Manage Roles > check the required role(s) > Save.

The Manage Roles panel shows a full searchable list of all security roles in the environment (225 in this case) — check the role(s) that should be able to open the app (e.g. "Customer Service Representative") and Save.

< Previous | Next >