Feedback
Table Of Contents
WebDialer Support for Enhancements in CTI and JTAPI
Desktop-based Client Application Call Flow
Browser-based Application Call Flow
WebDialer API Programming
This chapter describes the Simple Object Access Protocol (SOAP) and HTML over HTTP (and HTTPS) interfaces used to develop customized directory search applications for Cisco Unified CallManager WebDialer Version 1.2, and contains the following sections:
Definitions
Overview
Cisco Unified CallManager WebDialer, which is installed on a Cisco Unified CallManager server and used in conjunction with Cisco Unified CallManager, allows Cisco Unified IP Phone users to make calls from web and desktop applications. For example, Cisco Unified CallManager WebDialer uses hyperlinked telephone numbers in a company directory to allow users to make calls from a web page by clicking on the telephone number of the person they are trying to call.
The two main components of Cisco Unified CallManager WebDialer are the Webdialer Servlet and the Redirector Servlet.
Webdialer Servlet
The WebDialer servlet is a Java servlet that allows Cisco Unified CallManager users in a specific cluster to make and end calls, as well as to access their phone and line configuration.
Cisco WebDialer applications interact with the WebDialer servlet through two interfaces:
•
The SOAP over HTTP interface—This interface that is based on the Simple Object Access Protocol (SOAP) gets used to develop desktop applications such as Microsoft Outlook Add-in and SameTime Client Plug-in. Developers can use the isClusterUserSoap interface to design multicluster applications that require functionality similar to a Redirector servlet.
•
Redirector Servlet
The Redirector servlet, a Java based servlet finds the Cisco Unified CallManager cluster for a request made by a Cisco WebDialer user. It redirects that request to the specific Cisco WebDialer server that is located in that user's Cisco Unified CallManager cluster. Availability of the Redirector servlet occurs only for multicluster applications and only for applications that are developed by using HTML over HTTP or secure HTTP (HTTPS) interfaces.
Figure 4-1 illustrates how a Redirector servlet redirects a call in a multicluster environment.
Figure 4-1 Multiple Clusters
Example of Cisco Unified CallManager WebDialer Using the Redirector Servlet
For example, consider three clusters, each one in a single city such as San Jose, Dallas, and New York. Each cluster contains three Cisco Unified CallManager servers with Webdialer servlets that have been configured for Cisco Unified CallManager servers SJ-CM1, D-CM2, and NY-CM3.
The system administrator configures the Webdialer servlets on any of the Cisco Unified CallManager servers by entering the IP address of that specific Cisco Unified CallManager server in the wdservers service parameter.
For information on configuring Webdialer and Redirector servlets, refer to the Cisco WebDialer chapter in the Cisco Unified CallManager Features and Services Guide, Release 5.0.
When a user who is located in San Jose clicks on a telephone number in the corporate directory search page that is enabled by Cisco Unified CallManager WebDialer, the following actions happen:
1.
2.
For a repeat request, the Redirector servlet reads the IP address of the Cisco Unified CallManager WebDialer server that previously serviced the client and sends a isClusterUser HTTP request only to that server.
3.
4.
5.
Figure 4-1 illustrates how this request is sent to the Webdialer servlets that have been configured for SJ-CM1, D-CM2, and NY-CM3. Depending on the geographical location of the calling party, the WebDialer servlet from the cluster representing that location responds positively to the Redirector servlet. The remaining Webdialer servlets that were contacted return a negative response. The WebDialer servlet SJ-CM1 responds positively to the request because the calling party is located in San Jose (SJ-CM).
The Redirector servlet redirects the original request from the user to SJ-CM1 and sets a cookie on the user's browser for future use.
Changes in Release 5.0
The following changes to the Cisco Unified CallManager WebDialer were included in Cisco Unified CallManager Release 5.0.
•
•
•
•
•
•
•
These enhancements are explained in detail in the sections that follow.
Logging Mechanism Changes
In the previous release the changes made to the logging were applied only to the Webdialer servlet. In this release the logging mechanism has been modified so that the changes are applicable to both the WebDialer and Redirector servlet.
The serviceability mechanism provided for applying the changes in one logger to another logger has been used. The fappender.jar is now included in the WebDialer class path to take care of this dependency.
Redirector Over HTTPS
Redirector support for HTTPS was only partial until the previous release. Requests to the WebDialer server were using HTTP as the protocol. Redirector now supports HTTPS completely.
Dial Rule Change Notification
In previous releases WebDialer was not subscribed to Change Notification from the Application dial rule table. The WebDialer service had to be restarted every time an add/update/delete was made to the dial rules. Starting with this release WebDialer subscribes to Change Notification from the Application dial rule table.
WebDialer Support for Enhancements in CTI and JTAPI
The following enhancements in CTI and JTAPI are supported in WebDialer:
•
•
The following configuration must be completed before WebDialer can be configured to open a CTI connection in secure mode.
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Step 7
Step 8
a.
b.
c.
d.
e.
f.
Note
g.
h.
If anything else is selected, the certificate update will fail.
New Service Parameters
WebDialer has two new service parameters for CTI connection security. These are node-specific parameters.
•
If enabled (true), Cisco Webdialer will open a secure connection to CTI Manager using the Application CAPF profile configured for the instance ID (as configured in CTI Manager Connection Instance ID service parameter) for Application user WDSysUser. The default value is false.
•
•
1.
2.
3.
4.
5.
6.
7.
Install Changes
WebDialer rpm creates a new directory "/usr/local/cm/wd/wd-certificates/" and sets permissions for users on this directory, which is used to store the certificates.
Files Changed: /vob/ccm/Projects/CMAppServices/rpm/cm-webdialer.specPartition Support
WebDialer supports the partition information that is now provided by JTAPI. The WebDialer preferences page now includes information about the partition along with the line.
Migration of Dial Rules Data
The directory exports data into a CSV file. The CSV file points to a file in the same location, which has the dial rules in binary format as they are stored in the directory. The post-install script for WebDialer parses this CSV file, finds the file that has the encoded dial rules, decodes them, and populates the database with the dial rules.
SIP Support in WebDialer
WebDialer supports SIP phones in this release. CTI only supports the new SIP phones and not the existing SIP phones, so the same support is extended by WebDialer. The APIs provided by JTAPI are used to distinguish between these two kinds of phones and hide the unsupported phones from the user on the WebDialer preferences page.
Increase in Thread Count to 3
In previous releases, WebDialer supported only two concurrent threads. The performance testing for WebDialer shows better results (in terms of successful call rate) if the thread count is increased to 3. To increase performance, this change is being made for WebDialer in this release.
Call Flows
The call flows in this section describe the flow of events for client and browser-based applications that use Cisco Unified CallManager WebDialer, and should help you design customized applications for Cisco Unified CallManager WebDialer.
Desktop-based Client Application Call Flow
Figure 4-2 shows the call flow for an outgoing call from a client application such as Microsoft Outlook Plug-in to a WebDialer servlet. The user clicks the Dial or Make Call button in the address book of the client application. If the user is making a call for the first time, the application does not have authentication or configuration information on the user.
If the user makes a call for the first time:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Note
•
•
Figure 4-2 Cisco Unified CallManager WebDialer Call Flow for a Client-based Application
Browser-based Application Call Flow
Figure 4-3 shows the call flow for an HTTP based browser application such as a directory search page, personal address book, or the Cisco Unified CallManager directory search page (directory.asp).
The user clicks the Dial or Make Call button in the address book of the client application. If the user is making a call for the first time, the application does not have authentication or configuration information on the user.
Figure 4-3 Cisco Unified CallManager WebDialer Call Flow for a Browser-based Application
If the user makes a call for the first time:
1.
2.
Note
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
For all subsequent requests, the call flow starts at number 12 and ends at number 15.
Interfaces
Cisco Unified CallManager WebDialer applications interact with the WebDialer servlet through two interfaces:
•
•
Note
installWDService.bat
installWDSOAP.bat
SOAP over HTTP Interface
To access the SOAP interfaces for Cisco Unified CallManager WebDialer, use the Cisco Unified CallManager WebDialer Web Service Definition Language (WSDL) in the "WebDialer WSDL" section.
makeCallSoap
The makeCallSoap interface is accessed by initiating a SOAP request to the URL http://CCM-IP:8080/webdialer/services/WebdialerSoapService where CCM-IP is the IP address of the Cisco Unified CallManager server on which WebDialer is configured.
Destination
Mandatory
Standard canonical form. For example +1 408 5551212 or extensions such as 2222.
String
None
None
Credential
Mandatory
The user ID or password of the user or proxy user. For more information on creating a proxy user, see the Cisco WebDialer chapter in the Cisco Unified CallManager Features and Services Guide, Release 5.0.
Refer to the credential data type in the "WebDialer WSDL" section.
None
None
Profile
Mandatory
The profile that is used to make a call. An example of a typical profile is a calling device such as an IP phone or line.
Refer to the profile data type in the "WebDialer WSDL" section.
None
None
Results
Refer to the "WebDialer WSDL" section for return values and their data type.
endCallSoap
The endCallSoap interface is accessed by initiating a SOAP request to the URL http://CCM-IP:8080/webdialer/services/WebdialerSoapService where CCM_IP is the IP address of the Cisco Unified CallManager server on which WebDialer is configured.
ValueCredential
Mandatory
The user ID or password of the user or proxy user. For information on creating a proxy user, see the Cisco WebDialer chapter in the Cisco Unified CallManager Features and Services Guide, Release 5.0.
Refer to the credential data type in "WebDialer WSDL" section.
None
None
Profile
Mandatory
The profile that is used to make a call. An example of a typical profile is a calling device such as an IP phone or line.
Refer to the profile data type in the "WebDialer WSDL" section.
None
None
Refer to the "WebDialer WSDL" section for return values and their data type.
getProfileSoap
The getProfileSoap interface is used by plug-in based clients and accessed by initiating a SOAP request to the URL http://CCM-IP:8080/webdialer/services/WebdialerSoapService where CCM-IP is the IP address of the Cisco Unified CallManager server on which WebDialer is configured.
Credential
Mandatory
User ID or password of the user or proxy user. For information on creating a proxy user, see the Cisco WebDialer chapter in Cisco Unified CallManager Features and Services Guide, Release 5.0.
Refer to the credential data type in the "WebDialer WSDL" section.
None
None
UserID
Mandatory
The user ID for which the configuration is requested.
String
None
None
Refer to the "WebDialer WSDL" section for return values and their data type.
isClusterUserSoap
The isClusterUserSoap interface is accessed by initiating a SOAP request to the URL http://CCM-IP:8080/webdialer/services/WebdialerSoapService where CCM-IP is the IP address of the Cisco Unified CallManager server on which WebDialer is configured.
This SOAP interface is used for multi-cluster applications that require functionality, similar to a Redirector servlet, for redirecting calls to the various locations where Cisco Unified CallManager WebDialer is installed on a network. The application uses this interface to locate and verify the Cisco Unified CallManager WebDialer servicing the user, followed by makeCall, endCall or getProfile requests to that WebDialer.
UserID
Mandatory
The user ID for which the the request is made.
String
None
None
Refer to the "WebDialer WSDL" section for return values and their data type.
result
Boolean
The result is true if the user is present in the directory of the cluster. The result is false if the user is not present in the directory.
HTML over HTTP Interfaces
This section describes the HTML over HTTP interfaces.
makeCall
The makeCall interface is used in customized directory search applications. It is also used by the Cisco Unified CallManager directory search page (directory.asp). The makeCall interface is accessed by initiating an HTTP request to the URL http://<ipaddress>/webdialer/Webdialer. In this URL, ipaddress is the IP address of the Cisco Unified CallManager server for which WebDialer is configured.
This interface is used by browser-based applications in which the browser accepts cookies. The user profile exists only for the length of the session if the cookies are disabled in a browser. For a sample script that is used to enable directory search pages, go to the "Sample JavaScript" section.
makeCallProxy
The makeCallProxy interface is accessed by initiating an HTTP request to the URL http://ipaddress/webdialer/Webdialer?cmd=doMakeCallProxy. This interface is used by browser-based applications in which the browser accepts cookies. If the cookies are disabled in a browser, the user profile exists for only the length of the session.
The makeCallProxy interface can be used by applications such as a personal address book, defined in theUnified CMUser pages at http://cmserver/CMUser. The credential of the application is used, as a proxy, to make calls on behalf of users. Since these users have authenticated themselves before accessing theUnified CMUser page, they are not prompted again for their user ID and password. The application sends the user ID and password of the proxy user in the form of a query string in the request, or as a parameter in the body of the POST message.
For a sample script that is used to enable directory search pages, go to the "Sample JavaScript" section.
result
Cisco Unified CallManager WebDialer displays the appropriate dialog and its applicable success or error message.
WebDialer WSDL
The Web Service Definition Language (WSDL) for Cisco Unified CallManager WebDialer mentioned below is based on the WSDL specification. This WSDL for Cisco Unified CallManager WebDialer is also available on the Cisco Unified CallManager WebDialer server installation at:
http://CCM-IP:8080/webdialer/services/WebdialerSoapService?wsdl
Use this specific WSDL and the interfaces mentioned in this document to develop customized applications for Cisco Unified CallManager WebDialer. For a list of references on Cisco Unified CallManager, SOAP, and WSDL, refer to the "Related Documentation" section in the Preface.
<wsdl:definitions xmlns:tns="urn:WebdialerSoap" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="urn:WebdialerSoap" name="urn:WebdialerSoap"><wsdl:types><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="urn:WebdialerSoap" targetNamespace="urn:WebdialerSoap"><xsd:import namespace="http://schemas.xmlsoap.org/soap/encoding/"/><xsd:complexType name="CallResponse"><xsd:sequence><xsd:element name="responseCode" type="xsd:int"/><xsd:element name="description" nillable="true" type="xsd:string"/></xsd:sequence></xsd:complexType><xsd:complexType name="Credential"><xsd:sequence><xsd:element name="userID" nillable="true" type="xsd:string"/><xsd:element name="password" nillable="true" type="xsd:string"/></xsd:sequence></xsd:complexType><xsd:complexType name="UserProfile"><xsd:sequence><xsd:element name="user" nillable="true" type="xsd:string"/><xsd:element name="deviceName" nillable="true" type="xsd:string"/><xsd:element name="lineNumber" nillable="true" type="xsd:string"/><xsd:element name="supportEM" type="xsd:boolean"/><xsd:element name="locale" nillable="true" type="xsd:string"/></xsd:sequence></xsd:complexType><xsd:complexType name="GetConfigResponse"><xsd:sequence><xsd:element name="responseCode" type="xsd:int"/><xsd:element name="description" nillable="true" type="xsd:string"/><xsd:element name="deviceInfoList" nillable="true" type="tns:ArrayOfWDDeviceInfo"/></xsd:sequence></xsd:complexType><xsd:complexType name="WDDeviceInfo"><xsd:sequence><xsd:element name="deviceName" nillable="true" type="xsd:string"/><xsd:element name="lines" nillable="true" type="tns:ArrayOfstring"/></xsd:sequence></xsd:complexType><xsd:complexType name="ArrayOfWDDeviceInfo"><xsd:complexContent><xsd:restriction base="soapenc:Array"><xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="tns:WDDeviceInfo[]"/></xsd:restriction></xsd:complexContent></xsd:complexType><xsd:complexType name="ArrayOfstring"><xsd:complexContent><xsd:restriction base="soapenc:Array"><xsd:attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:string[]"/></xsd:restriction></xsd:complexContent></xsd:complexType></xsd:schema></wsdl:types><wsdl:message name="makeCallSoap0In"><wsdl:part name="cred" type="tns:Credential"/><wsdl:part name="dest" type="xsd:string"/><wsdl:part name="prof" type="tns:UserProfile"/></wsdl:message><wsdl:message name="makeCallSoap0Out"><wsdl:part name="Result" type="tns:CallResponse"/></wsdl:message><wsdl:message name="endCallSoap1In"><wsdl:part name="cred" type="tns:Credential"/><wsdl:part name="prof" type="tns:UserProfile"/></wsdl:message><wsdl:message name="endCallSoap1Out"><wsdl:part name="Result" type="tns:CallResponse"/></wsdl:message><wsdl:message name="getProfileSoap2In"><wsdl:part name="cred" type="tns:Credential"/><wsdl:part name="userid" type="xsd:string"/></wsdl:message><wsdl:message name="getProfileSoap2Out"><wsdl:part name="Result" type="tns:GetConfigResponse"/></wsdl:message><wsdl:message name="isClusterUser3In"><wsdl:part name="userid" type="xsd:string"/></wsdl:message><wsdl:message name="isClusterUser2Out"><wsdl:part name="Result" type="xsd:boolean"/></wsdl:message><portType name="WebdialerSoapService"><wsdl:operation name="makeCallSoap"><wsdl:input message="tns:makeCallSoap0In"/><wsdl:output message="tns:makeCallSoap0Out"/></wsdl:operation><wsdl:operation name="endCallSoap"><wsdl:input message="tns:endCallSoap1In"/><wsdl:output message="tns:endCallSoap1Out"/></wsdl:operation><wsdl:operation name="getProfileSoap"><wsdl:input message="tns:getProfileSoap2In"/><wsdl:output message="tns:getProfileSoap2Out"/></wsdl:operation><wsdl:operation name="isClusterUserSoap"><wsdl:input message="tns:isClusterUser3In"/><wsdl:output message="tns:isClusterUser2Out"/></wsdl:operation></portType><binding name="WebdialerSoapService" type="tns:WebdialerSoapService"><soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/><wsdl:operation name="makeCallSoap"><soap:operation soapAction="urn:makeCallSoap"/><input><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></input><output><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></output></wsdl:operation><wsdl:operation name="endCallSoap"><soap:operation soapAction="urn:endCallSoap"/><input><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></input><output><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></output></wsdl:operation><wsdl:operation name="getProfileSoap"><soap:operation soapAction="urn:getProfileSoap"/><input><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></input><output><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></output></wsdl:operation><wsdl:operation name="isClusterUserSoap"><soap:operation soapAction="urn:isClusterUserSoap"/><input><soap:body use="encoded" encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></input><output><soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:WebdialerSoap"/></output></wsdl:operation></binding><service name="WebdialerSoap"><port name="WebdialerSoapService" binding="tns:WebdialerSoapService"><soap:address location= "http://WebDialer_ip_address:8080/webdialer/services/WebdialerSoapService"/></port></service></wsdl:definitions>Sample JavaScript
This JavaScript is a sample script that is used to enable Cisco Unified CallManager WebDialer from a directory search page.
Single Cluster Applications
This script is used for single cluster applications if all users are in only one cluster.
function launchWebDialerWindow( url ) {webdialer=window.open( url, "webdialer", "status=no, width=420, height=300, scrollbars=no, resizable=yes, toolbar=no" );}function launchWebDialerServlet( destination ) {url = 'http://<%=server_name%>/webdialer/Webdialer?destination=' + escape(destination);launchWebDialerWindow( url );}!These functions can be called from the HTML page which has a hyperlink to the phone number to be called. An example of it is:<TD><A href="javascript:launchWebDialerServlet( <%= userInfo.TelephoneNumber %> )"><%= userInfo.TelephoneNumber %></A> </TD>Multiple Cluster Applications
This script is used if all users are spread across different clusters.
function launchWebDialerWindow( url ) {webdialer=window.open( url, "webdialer", "status=no, width=420, height=300, scrollbars=no, resizable=yes, toolbar=no" );}function launchWebDialerServlet( destination ) {url= 'http://<%=server_name%>/webdialer/Redirector?destination='+escape(destination);launchWebDialerWindow( url );}!These functions can be called from the HTML page which has a hyperlink to the phone number to be called. An example of it is:<TD><A href="javascript:launchWebDialerServlet( <%= userInfo.TelephoneNumber %> )"><%= userInfo.TelephoneNumber %></A> </TD>
