Walkthrough: Create a UII Web Application Adapter

 

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

You can create a web application adapter if you want to enhance and modify web applications for which you don’t have access to the source code or don’t have permissions to change by using managed code. Microsoft Dynamics 365 provides a Microsoft Visual Studio template for creating a web application adapter. The template provides basic code as comments to help you get started with creating the web application adapter.

In this walkthrough, you’ll build an external web application called QsWebApplication and host it in Unified Service Desk. You’ll then create and configure a web application adapter called MyWebApplicationAdapter for the external web application to interact with Unified Service Desk. The web 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 Unified Service Desk values.

In This Topic

Prerequisites

Step 1: Build a sample web application

Step 2: Configure the web application in Dynamics 365

Step 3: Test the web application

Step 4: Create the web application adapter

Step 5: Configure the web application adapter in Dynamics 365

Step 6: Test the web 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:

Step 1: Build a sample web application

  1. Download the UII SDK package (.exe)

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

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

  4. Press F5 or choose Debug > Start Debugging to host the sample web application locally on your computer. The application will be hosted at http://localhost:2627/.

    Web app in Visual Studio

Step 2: Configure the web application in Dynamics 365

  1. Sign in to Microsoft Dynamics 365.

  2. Go to Settings > Unified Service Desk.

  3. Choose Hosted Controls.

  4. Choose New.

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

    Field

    Value

    Name

    QsWebApplication

    USD Component Type

    CCA Hosted Application

    Hosted Application

    Web Hosted Application

    Application is Global

    Checked

    Display Group

    MainPanel

    Adapter

    Use No Adapter

    Application is Dynamic

    No

    Application Hosting

    Use SetParent

    URL

    Specify the location where your web application is hosted. In this case, it is http://localhost:2627/

    Screenshot of Web App Config in Dynamics 365

  6. Choose Save.

Step 3: Test the web application

  1. Make sure that the sample web application that you built in step 1 is still running.

  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 Web Application on your desktop.

  4. Click the Sample External Web Application tab to see your web application hosted within Unified Service Desk.

Hosting web app in Unified Service Desk

Note

At this point the fields are empty because you’re only hosting the external web application in Unified Service Desk. To populate them with values from Unified Service Desk, we have to create a web application adapter as illustrated in the next step.

Step 4: Create the web 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 on the left, expand Visual C#, and select Dynamics 365 SDK Templates > Unified Service Desk > UII Web Application Adapter.

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

      Screenshot of Web Adapter in Visual Studio

    3. Choose WebAppAdapter.cs and update the definition of NotifyContextChange with the following code to populate the text fields from the context information. More information:NotifyContextChange

      public override bool NotifyContextChange(Context context)
              {
                  // Populating text fields from context information.
      
                  HTMLDocument htmlDoc = Browser.Document as HTMLDocument;
                  if (htmlDoc != null)
                  {
                      IHTMLElementCollection htmlElementCollection = htmlDoc.all;
                      IHTMLElement htmlFirstName = htmlElementCollection.item("txtFirstName", 0) as IHTMLElement;
                      htmlFirstName.setAttribute("value", context["firstname"], 0);
                      IHTMLElement htmlLastName = htmlElementCollection.item("txtLastName", 0) as IHTMLElement;
                      htmlLastName.setAttribute("value", context["lastname"], 0);
                      IHTMLElement htmlAddress = htmlElementCollection.item("txtAddress", 0) as IHTMLElement;
                      htmlAddress.setAttribute("value", context["address1_line1"], 0);
                      IHTMLElement htmlID = htmlElementCollection.item("txtID", 0) as IHTMLElement;
                      htmlID.setAttribute("value", context["CustomerID"], 0);
                  }
                  return base.NotifyContextChange(context);
              }
      
    4. Add the following code to the override definition of DoAction to update the application with values from Unified Service Desk

      public override bool DoAction(HostedWebApplication.WebAction action, ref string data)
              {
                  Trace.WriteLine(string.Format("{0}>>>>> RECEIVED (WebAction) Action : {1} ", this.Name, action.Name));
      
                  // Check to see if the browser is working on something before allowing the system to do 'normal' behavior.
                  if (Browser.WebBrowser.ReadyState != tagREADYSTATE.READYSTATE_COMPLETE)
                  {
                      // Browser is not in a state to process this request,  Queue it for when the browser is ready to handle it. 
                      Trace.WriteLine(string.Format("{0}>>>>> Browser Busy,({2}) Queuing Action : {1} ", this.Name, action.Name, Browser.WebBrowser.ReadyState.ToString()));
                      qReqActionList.Enqueue(new BrowserActionData(action, data));
                      return false;
                  }
                Trace.WriteLine(string.Format("{0}>>>>>>>>>>> Action:Name={1} Action:Url={2} Action:Query={3} Action:Init={4}", this.Name, action.Name, action.Url, action.QueryString, action.Initialization));
      
                  // Get browser DOM and element collection.
                  // Create an XML Document to load the passed in data to.
                  HTMLDocument htmlDoc = Browser.Document as HTMLDocument;
                  IHTMLElementCollection htmlElementCollection = htmlDoc.all;
      
                  // Check action name for something we know how to process.
                  switch (action.Name)
                  {
                      case "UpdateFirstName":
                          IHTMLElement htmlFirstName = htmlElementCollection.item("txtFirstName", 0) as IHTMLElement;
                          htmlFirstName.setAttribute("value", data, 0);
                          break;
                      case "UpdateLastName":
                          IHTMLElement htmlLastName = htmlElementCollection.item("txtLastName", 0) as IHTMLElement;
                          htmlLastName.setAttribute("value", data, 0);
                          break;
                      case "UpdateAddress":
                          IHTMLElement htmlAddress = htmlElementCollection.item("txtAddress", 0) as IHTMLElement;
                          htmlAddress.setAttribute("value", data, 0);
                          break;
                      case "UpdateID":
                          IHTMLElement htmlID = htmlElementCollection.item("txtID", 0) as IHTMLElement;
                          htmlID.setAttribute("value", data, 0);
                          break;
                  }
                  return false;
              }
      
    5. Save your project, and build it (Build > Build Solution). After the project builds successfully, an assembly (MyWebApplicationAdapter.dll) is generated in the \bin\debug folder of your project folder. You’ll need this assembly later for testing and using your web application adapter.

Step 5: Configure the web 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 QsWebApplication hosted control.

    Hosted controls list in Dynamics 365

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

    Field

    Value

    Adapter

    Use Adapter

    URI

    MyWebApplicationAdapter

    Type

    MyWebApplicationAdapter.WebAppAdapter

    Web adapter configuration in Dynamics 365

    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 MyWebApplicationAdapter and name of the class is WebAdapter, which is the default class name when you create a web application adapter.

  6. Choose Save to save the changes.

Step 6: Test the web application adapter

  1. Copy the assembly that contains your web application adapter definition from your Visual Studio project output folder (<ProjectFolder>\bin\debug) to the Unified Service Desk application directory. In this case, you’ll copy the MyWebApplicationAdapter.dll file 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 will see the sample external web application button on your desktop.

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

    Screenshot of contact list

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

    Testing WebApp Adapter screenshot

Note

This walkthrough showed you how to read or display data from Unified Service Desk in the external web application. To update the data in Unified Service Desk from the external web application, and vice versa, 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