Walkthrough: Create a UII Application Adapter

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2013, Dynamics CRM 2015, Dynamics CRM 2016

You can create an application adapter if you want to integrate an external application with Unified Service Desk. Microsoft Dynamics 365 provides a Microsoft Visual Studio template for creating an application adapter. The template provides basic code as comments to help you get started with creating the application adapter.

In this walkthrough, you’ll build an external application QsExternalApp and host it in Unified Service Desk. You’ll then create and configure an application adapter ExternalApplicationAdapter for the external application to interact with Unified Service Desk. The external application has four labels: one each for the customer’s first name, last name, address and ID and four corresponding text boxes to display the values from Unified Service Desk.

In This Section

Prerequisites

Step 1: Build a sample external application

Step 2: Configure the external application in Microsoft Dynamics 365.

Step 3: Test the external application

Step 4: Create the application adapter

Step 4: Configure the application adapter in Dynamics 365

Step 5: Test the application adapter

Prerequisites

• Microsoft .NET Framework 4.5.2

• Unified Service Desk client application; required for testing the hosted control.

• Microsoft Visual Studio 2012, Visual Studio 2013, or Visual Studio 2015

• NuGet Package Manager for Visual Studio 2012, Visual Studio 2013, or Visual Studio 2015

• Microsoft Dynamics 365 SDK templates for Visual Studio that contains the UII hosted control project template. You can get it in one of the following ways:

  • Download the CRM SDK template. Double-click the CRMSDKTemplates.vsix file to install the template in Visual Studio.

  • Download and extract the CRM SDK package. Go to the SDK\Templates folder in the SDK, and double-click the CRMSDKTemplates.vsix file to install the template in Visual Studio.

Step 1: Build a sample external application

1. Download the UII SDK package.

2. Double-click the package file to extract the contents.

3. Navigate to the <ExtractedFolder>\UII\SampleCode\UII\AIF\QsExternalApp folder, and open the Microsoft.Uii.QuickStarts.QsExternalApp.csproj file in Visual Studio.

4. Press F5 or choose Debug > Start Debugging to create a sample external application. The application (Microsoft.Uii.QuickStarts.QsExternalApp.exe) is created in the /bin/debug folder of the project.

   

Step 2: Configure the external application in Microsoft Dynamics 365.

In this step, you will create a hosted control of External Hosted Application type to display the Windows forms application.

1. Sign in to Microsoft Dynamics 365.

2. On the navigation bar, click or tap Microsoft Dynamics 365, and then select Settings.

3. Click or tap Settings > Unified Service Desk > Hosted Controls.

4. Click New.

5. On the New Hosted Control page, specify the following values:

   Field	Value
   Name	QsExternalApp
   USD Component	CCA Hosted Application
   Hosted Application	External Hosted Application
   Application is Global	Checked
   Display Group	MainPanel
   Adapter	Use No Adapter
   Application is Dynamic	No
   External App URI	Microsoft.Uii.QuickStarts.QsExternalApp.exe

   

   

6. Click Save.

Step 3: Test the external application

1. Copy the application from your Visual Studio project output folder (<ProjectFolder>\bin\debug) to the Unified Service Desk application directory. In this case, we will copy the Microsoft.Uii.QuickStarts.QsExternalApp.exefile to the C:\Program Files\Microsoft Dynamics CRM USD\USD directory.

2. Run the Unified Service Desk client to connect to your Microsoft Dynamics 365 server.

3. On successful sign in, you’ll see the Sample External Application button on your desktop.

4. Choose Sample External Application to see your external application hosted within Unified Service Desk.

Note

At this point the fields are empty as you’re only hosting the application in Unified Service Desk. To populate them with values from Unified Service Desk, you’ll have to create an application adapter as described in the next step.

Step 4: Create the application adapter

1. Start Microsoft Visual Studio, and create a new project.

2. In the New Project dialog box:

   1. From the list of installed templates, expand Visual C#, and select Dynamics 365 SDK Templates > Unified Service Desk > UII Application Adapter

   2. Specify the name and location of the project, and click OK to create a new project.

      

3. In Solution Explorer, expand the References section to ensure all the assembly references resolve correctly.

4. Open the AppAdapter.cs file and add the following lines of code to set the locations for each component on the page in the class definition.

   // Set up your locations for each component on the page.
           // If you wish, you could use Spy++ to get the actual names as well.
           // First Name text box
           int intFirstNameCoordX = 47;
           int intFirstNameCoordY = 32;
           // Last Name text box
           int intLastNameCoordX = 223;
           int intLastNameCoordY = 32;
           // Address Text box
           int intAddressCoordX = 47;
           int intAddressCoordY = 81;
           // Customer ID text box
           int intIDCoordX = 47;
           int intIDCoordY = 126;
   

5. Add the following code to the definition of NotifyContextChange to notify the application that the context has changed. For more information, see NotifyContextChange

   public override bool NotifyContextChange(Context context)
           {
               IntPtr ptr = MainWindowHandle;
               // Find the control (first name) by position
               IntPtr childHwnd = Win32API.FindWindowByPosition(ptr, new Point(intFirstNameCoordX, intFirstNameCoordY));
               // Fill data out
               Win32API.SetWindowTextAny(childHwnd, context["firstname"]);
               // Find the control (last name) by position
               childHwnd = Win32API.FindWindowByPosition(ptr, new Point(intLastNameCoordX, intLastNameCoordY));
               // Fill out the data
               Win32API.SetWindowTextAny(childHwnd, context["lastname"]);
               childHwnd = Win32API.FindWindowByPosition(ptr, new Point(intAddressCoordX, intAddressCoordY));
               Win32API.SetWindowTextAny(childHwnd, context["address1_line1"]);
               childHwnd = Win32API.FindWindowByPosition(ptr, new Point(intIDCoordX, intIDCoordY));
               Win32API.SetWindowTextAny(childHwnd, context["CustomerID"]);
               // Hands control back over to the base class to notify next app of context change.
               return base.NotifyContextChange(context);
   
           }
   

6. Add the following code to the override definition of DoAction to update the form fields with values from Unified Service Desk.

   public override bool DoAction(Microsoft.Uii.Csr.Action action, RequestActionEventArgs args)
           {
               IntPtr ptr;
               IntPtr childHwnd;
               switch (args.Action)
               {
                   case "UpdateFirstName":
                       // Get locations of what you want to update and handles
                       ptr = MainWindowHandle;
                       childHwnd = Win32API.FindWindowByPosition(ptr, new Point(intFirstNameCoordX, intFirstNameCoordY));
                       // Populate data into fields
                       Win32API.SetWindowTextAny(childHwnd, args.Data);
                       break;
                   case "UpdateLastName":
                       // Get locations of what you want to update and handles
                       ptr = MainWindowHandle;
                       childHwnd = Win32API.FindWindowByPosition(ptr, new Point(intLastNameCoordX, intLastNameCoordY));
                       // Populate data into fields
                       Win32API.SetWindowTextAny(childHwnd, args.Data);
                       break;
               }
               return base.DoAction(action, args);
           }
   

7. Save your project, and build it (Build > Build Solution). After the project builds successfully, an assembly (ExternalApplicationAdapter.dll) is generated in the \bin\debug folder of your project folder. You’ll need this assembly later for testing and using your application adapter.

Step 4: Configure the application adapter in Dynamics 365

1. Sign in to Microsoft Dynamics 365.

2. On the nav bar, choose Microsoft Dynamics 365, and then select Settings.

3. Choose Settings > Unified Service Desk > Hosted Controls.

4. From the list of hosted controls, select the QsExternalApp hosted control.

   

5. In the Adapter Configuration section, specify the following values:

   Field	Value
   Adapter	Use Adapter
   URI	ExternalApplicationAdapter
   Type	ExternalApplicationAdapter.AppAdapter

   

   Note

   URI is the name of your assembly and the Type is the name of your assembly (dll) followed by a dot (.) and then the class name in your Visual Studio project. In this example, the name of the assembly is ExternalApplicationAdapter and name of the class is AppAdapter, which is the default class name when you create an application adapter.

6. Click Save to save the changes.

Step 5: Test the application adapter

1. Copy the assembly that contains your application adapter definition from your Visual Studio project output folder (<ProjectFolder>\bin\debug) to the Unified Service Desk application directory. In this case, we will copy the ExternalApplicationAdapter.dll file to the c:\Program Files\Microsoft Dynamics CRM USD\USD directory.

2. Run Unified Service Desk client to connect to your Microsoft Dynamics 365 server.

3. On successful sign in, you’ll see the sample external application on your desktop.

4. Choose Search and then choose Contacts and select a contact. In this case, we’ll select Patrick Sands.

   

5. Click Sample External Application and you’ll see the customer’s first name, last name, address, and ID populated.

   

Note

This walkthrough demonstrates how to display or read data from Unified Service Desk in the external application. To understand how to update the data in Unified Service Desk from the external application, see Walkthrough: Create a UII Windows Forms Hosted Control

See Also

Use UII adapters to interact with external and web applications

Unified Service Desk 2.0

© 2017 Microsoft. All rights reserved. Copyright