Share via

Walkthrough: Use the generic listener adapter for CTI event routing

  • Article

This walkthrough demonstrates how you can use the CTI Desktop Manager and generic listener in Unified Service Desk to expose the CTI events as screen pops in Unified Service Desk. For this walkthrough, we will use a sample CTI Simulator application that sends CTI requests to Unified Service Desk.

In this walkthrough, you’ll:

  • Search for a contact record in the sample data based on an email address specified in the sample CTI Call Tester application.

  • Create a window navigation rule to display the matching record in a session in Unified Service Desk.

Prerequisites

  • Microsoft .NET Framework 4.6.2

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

  • Visual Studio 2012 or Visual Studio 2013

  • Download the sample CTI Simulator Application Visual Studio project to your computer. Build the project, and run the application (.exe file) from the bin\debug folder of the sample application project. You must run the USD CTI Simulator application on the same computer where Unified Service Desk client is running to test the application.

Step 1: Configure a CTI Desktop Manager hosted control in Unified Service Desk

  1. Sign in to Unified Service Desk Administrator.

  2. Select Hosted Controls under Basic Settings.

  3. Select + New.

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

    Field Value
    Name CTITest
    USD Component Type CTI Desktop Manager
    Display Group HiddenPanel
    Assembly URI Microsoft.Crm.UnifiedServiceDesk.GenericListener
    Assembly Type Microsoft.Crm.UnifiedServiceDesk.GenericListener.DesktopManager

    Note

    The values specified in the Assembly URI and Assembly Type fields are the generic listener values for the CTI Desktop Manager hosted control type.

  5. Select Save to create the hosted control.

Step 2: Test if the CTI events are raised in Unified Service Desk

  1. Start Unified Service Desk client, and connect to your Microsoft Dataverse instance. After the client is up, choose SettingsGear button in the top-right corner to display the debugger control, and then choose Clear Debug OutputDelete button to clear the desktop.

    Unified Service Desk client.

  2. Start the USD CTI Simulator application, type Email in the Key column and specify a random value in the Value column. Click Send to USD.

    Unified Service Desk CTI Simulator.

  3. A screen pop-up occurs in the client application to expose the CTI event. In this case, a CTILookUpRequest is initiated with the value that was specified in the USD CTI Simulator application. Because you haven’t wired it yet with a window navigation rule, nothing further happens.

    Screen pop in for the CTI event.

Step 3: Define a window navigation rule to route the CtiLookUpRequest

Create a window navigation rule to create a session if a match is found, and then display the matching contact record in a session in Unified Service Desk

  1. Sign in to the Dynamics 365 instance.

  2. Navigate to the advanced find for contacts, and create a query where you search for active contacts where the email, email address 2, or email address 3 field equals a certain value, for example, someone_c@example.com.

    Query for contacts based on email address.

  3. Select Download Fetch XML to save the query as FetchXML.

  4. Go to the Unified Service Desk Administrator app.

  5. Select Window Navigation Rules.

  6. Select + New

  7. On the New Window Navigation Rule window, specify the following values.

    Field Value
    Name CTITestRoute
    Order 50
    From CTITest

    This is the name of your CTI Desktop Manager hosted control.
    Direction Both

  8. Save the rule. This enables the rest of the controls on the page.

  9. Now, add the FetchXML query that was saved earlier to this rule. Under the CTI Searches area, choose Add.

  10. In the New CTI Search window, specify the following values:

  • Name: CTIContactSearch

  • Order: 1

  • FetchXML:

    
<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">  
  <entity name="contact">  
    <attribute name="fullname" />  
    <attribute name="parentcustomerid" />  
    <attribute name="telephone1" />  
    <attribute name="emailaddress1" />  
    <attribute name="contactid" />  
    <order attribute="fullname" descending="false" />  
    <filter type="and">  
      <condition attribute="statecode" operator="eq" value="0" />  
      <filter type="or">  
        <condition attribute="emailaddress1" operator="eq" value="[[cti.Email]]" />  
        <condition attribute="emailaddress2" operator="eq" value="[[cti.Email]]" />  
        <condition attribute="emailaddress3" operator="eq" value="[[cti.Email]]" />  
      </filter>  
    </filter>  
  </entity>  
</fetch>

    Note

    The address someone_c@example.com was replaced with [[cti.Email]] so that the search is run based on the value specified for the Email key in the Unified Service Desk CTI Simulator application.

Define a CTI search for contacts.

  1. Save the CTI search rule, and return to the window navigation rule.

  2. Under Single Match, in the Decision field, select Create Session, Load Match then Do Action.

  3. Under Single Match, in the Action field, select the search icon to select a value, and then select + New.

  4. On the + New Action Call page, create an action call to open the contact record by specifying the following values.

    Field Value
    Name CTIOpenContact
    Hosted Control CRM Global Manager
    Action Open_CRM_Page
    Data Id=[[$Context.Id]]
    LogicalName=[[$Context.LogicalName]]

  5. Save the action call, and then close the action call page to return to the window navigation rule definition page.

  6. Under the Result area:

    1. In the Destination field, choose Tab to display the matching contact record in a tab.

    2. In the Target Tab field, choose the Contact hosted control. The Contact hosted control was created when you deployed a sample Unified Service Desk application on your Dataverse server using the Package Deployer tool. For more information, see Deploy sample Unified Service Desk applications to CRM server using Package Deployer.

    3. In the Show Tab field, choose the Contact hosted control

    Specify appropriate values for the rule definition.

  7. Save the window navigation rule.

Test your CTI adapter

  1. Start Unified Service Desk client, and connect to your Dataverse instance. After the client is up, choose SettingsGear button in the top-right corner to display the debugger control, and then choose Clear Debug OutputDelete button to clear the desktop.

    Unified Service Desk client.

  2. Start the USD CTI Simulator application, type Email in the Key column and specify a valid email ID for the contact that you want to search. In this case, type someone_d@example.com in the Value column. Select Send To USD.

    Specify the email to search for a contact.

  3. The matching contact record is displayed in a session in Unified Service Desk.

    Matching contact record displayed in a session.

  4. Check the Debugger hosted control to view the events that got raised as a result of the CTI search. Also check out the Data Parameters tab to view the context information in the $Context variable and CTI information under the CTI variable.

See also

Integrate with CTI systems
UII Computer Telephony Integration (CTI) framework