The Complete Guide to Component Mapping from USD to CSW: Rebuilding Your Hosted Controls

The Sandbox Strategy: Do I need a new environment to set up Customer Service Workspace?

The short answer is yes. While you do not necessarily need an entirely new tenant, setting up Customer Service Workspace (CSW) directly in your live production environment alongside an active Unified Service Desk (USD) deployment is a recipe for data corruption and routing conflicts.

According to Dynamics 365 workspace migration best practices, your first step must be provisioning a dedicated Sandbox environment. Because CSW is a model-driven Power App natively connected to your Dataverse, you will want to clone your production database (schema and data) into this Sandbox. This allows your developers to safely test new omnichannel routing rules, build custom pages, and validate API endpoints without accidentally triggering live customer workflows or disrupting the agents currently working in the legacy USD client.

Once the Sandbox is configured, you can begin the granular process of auditing and mapping your existing setup.

Assessing Your Legacy Build: What configurations can be reused when migrating to CSW?

When analyzing a legacy USD deployment, administrators often hope for a simple "export/import" utility. Unfortunately, because the underlying technologies are fundamentally different—USD uses Windows Presentation Foundation (WPF) and .NET UII frameworks, whereas CSW uses HTML5, JavaScript, and Power Apps model-driven architecture—the UI components cannot simply be copied over.

However, your underlying business logic and data structures are entirely reusable.

Your core Dataverse tables (Cases, Accounts, Contacts, Custom Entities), underlying business rules, and classic Dataverse workflows will function perfectly in CSW. What you are replacing is the "glass"—the interface agents use to interact with that data.

Are customizations in USD transferable to Customer Service Workspace?

Direct UI customizations are not transferable. If your team wrote custom C# code to create a highly specific USD Hosted Control, that .dll file cannot be loaded into a web browser.

Instead, the functionality of that custom code must be recreated using modern cloud tools. For example, a custom USD hosted control that previously pulled data from a legacy external SQL database would need to be rebuilt as a Power Apps Custom Page utilizing a Power Automate flow to retrieve that same data via a cloud connector.

Identifying the Gaps: Which features in USD don’t have equivalents in CSW?

Before you begin mapping, it is crucial to understand the limitations of a browser-based environment. When conducting a Dynamics 365 CSW capabilities comparison, the most notable gaps relate to localized machine access.

Because USD was installed directly onto the agent's local Windows machine, it could do things that standard web browsers restrict for security reasons. Features in USD that do not have direct equivalents in CSW include:

• Deep OS Integration: USD could easily read/write to the agent's local C: drive, execute local .exe files, or scrape data from other desktop applications using Windows COM adapters. CSW, sandboxed inside a browser tab, cannot do this.
• Legacy UII Actions: The specific User Integration Interface (UII) SDK used to pass parameters between custom desktop controls does not exist in CSW.
• ActiveX Controls: Any legacy integration relying on Internet Explorer ActiveX controls will fail in the modern Edge/Chrome environments that CSW requires.

If your current contact center relies on these local-machine hooks, you must fundamentally redesign those business processes to utilize cloud-based APIs and standard web resources.

The Core Execution: How to map USD hosted controls to CSW capabilities?

The actual process of component mapping USD to CSW requires translating the terminology and functionality of the legacy desktop app into the modern Customer Service admin center.

Here is the definitive mapping guide to translate your legacy components:

1. Mapping USD Pages to CSW Sessions and Tabs

In USD, every time an agent opened a case, a new "Session" was created, and subsequent records opened as "Hosted Controls" within that session.

• The CSW Equivalent: CSW uses Session Templates and Application Tab Templates.
• How to Map It: In the Customer Service Admin Center, navigate to Workspaces > Session templates. You will create a new Session Template for your core entities (e.g., "Incoming Case Session"). Within that template, you define the "Anchor Tab" (usually the main Case form) and configure additional Application Tab Templates to dictate which related records (like the Customer Contact card) open alongside it.

2. Mapping USD Toolbars to the CSW Command Bar

USD heavily utilized customizable "Toolbar Hosted Controls" at the top of the screen to give agents quick-click actions (e.g., "Escalate to Tier 2" or "Send Knowledge Article").

• The CSW Equivalent: The modern Command Bar (Ribbon).
• How to Map It: You will no longer configure toolbars in a proprietary interface. Instead, you must edit the Model-Driven App Command Bar using Power Fx formulas or JavaScript. If a USD button previously executed a complex UII Action, you will replace it by creating a Command Bar button in CSW that triggers a Power Automate flow or a modern CSW Macro.

3. Mapping Window Navigation Rules to the App Profile Manager

USD used a massive, complex list of "Window Navigation Rules" to dictate behavior. (For example: If a user clicks a phone number on a Contact record, open the CTI dialer in the left panel.)

• The CSW Equivalent: CSW handles this natively through the App Profile Manager and the Xrm.Navigation API.
• How to Map It: CSW is much smarter out-of-the-box. Standard relational clicks (clicking an Account from a Case) automatically open in new tabs without needing complex rules. For custom routing, administrators must use the App Profile Manager to assign specific Session Templates to specific security roles, or utilize the Microsoft.Apm.createTab JavaScript API to force specific web resources to open dynamically based on agent actions.

4. Mapping Custom Hosted Controls to Custom Pages

As mentioned earlier, custom C# controls are obsolete in the cloud.

• The CSW Equivalent: Custom Pages (Canvas Apps embedded in Model-Driven Apps).
• How to Map It: If you had a custom USD control that allowed agents to calculate loan interest rates on the fly, you will now build a Canvas App with that exact UI and logic. You then embed that Canvas App as a "Custom Page" within your CSW Application Tab Templates. This offers a massive upgrade in flexibility, as Custom Pages are fully responsive and infinitely easier to update than compiled C# code.

For the official Microsoft documentation on this process, refer to the Map components in Unified Service Desk to Customer Service workspace capabilities guide.

Testing and Go-Live: How do I test and validate a CSW implementation before going live?

Once you have completed the component mapping USD to CSW within your Sandbox, you cannot simply flip a switch and force hundreds of agents onto the new platform. A botched migration can cripple a contact center’s handle times and ruin customer satisfaction.

Here is the recommended validation framework:

Phase 1: Technical API Validation

Before any agent sees the new workspace, your development team must rigorously test the boundaries of the browser. Ensure that any JavaScript replacing legacy Window Navigation Rules fires correctly across both Microsoft Edge and Google Chrome. Verify that your cloud-based Power Automate flows return data to your Custom Pages as quickly as the old local database queries did.

Phase 2: User Acceptance Testing (UAT)

Select a small group of your most experienced "power-user" agents. Grant them access to the Sandbox CSW environment and ask them to process dummy cases. This is where you will discover the nuances of the modern customer service agent interface. Agents will quickly tell you if a new Command Bar button requires too many clicks compared to the old USD Toolbar, allowing you to refine the UI before a wider rollout.

Phase 3: The Parallel Pilot (Soft Launch)

Do not execute a "big bang" cutover. Instead, deploy the finalized CSW configuration to your production environment but only assign the new "App Profile" to a specific pilot team (e.g., 10% of your workforce). Let them take live customer calls and chats using CSW while the remaining 90% stay on USD. Monitor the pilot team's Average Handle Time (AHT) and error logs closely. Once parity or improvement is proven, you can safely roll out CSW to the rest of the floor, officially decommissioning USD.

At ClonePartner, we know that moving away from a deeply customized legacy system is daunting. However, executing a precise mapping strategy transforms this forced deprecation into a massive operational upgrade. If your team is struggling to untangle years of legacy USD configurations, our engineering experts are ready to audit your system and build your custom CSW transition roadmap.

External Sources

Add these to the bottom of Satellite Post 1 to provide system administrators with the official technical documentation for migrating legacy configurations.

• Migration Playbook: Migrate to Customer Service Workspace (Microsoft Learn)
• Data Migration Tools: Migrate Unified Service Desk configuration data (Microsoft Learn)
• Legacy Architecture Reference: Unified Service Desk Guide & System Requirements (Microsoft Learn)