Make phone calls in web applications

WAS v8.5 > End-to-end paths > Communications enabled applications
Make phone calls in web applications

We can embed the ClickToCall widget in an existing application to enable users to enter their phone number and request an immediate callback from your company. You embed the communications enabled applications (CEA) widget using the Dojo Toolkit provided with the CEA feature.
Dojo widgets are prepackaged components of JavaScript code, HTML markup and CSS style declarations that can be used to enhance web sites with interactive features. We can use the Dojo Toolkit that comes with the CEA feature to embed the CEA widgets in the applications. This capability also requires an IP private branch exchange (PBX) as part of your infrastructure. An IP PBX is a business telephone system designed to deliver voice over a data network and interoperate with the Public Switched Telephone Network (PSTN). A sample IP PBX application is included in the Samples Gallery.stem The sample IP PBX is in the form of an enterprise application archive (EAR) file and is for test purposes only. The details of installing and configuring the vendor-specific IP PBX are not provided. Along with the sample IP PBX, two soft phones are needed to test the application.
Deprecated feature: CEA Dojo widgets encapsulate various user interfaces that are based on the CEA Rest API. These widgets are deprecated. We can also obtain the source for these widgets from developerWorks ..
The ClickToCall widget is built using the functionality provided in the Dojo Toolkit. This widget can be configured to create a call between a hard-coded number provided to the widget during initialization and a number provided by the end user. The ClickToCall widget can also be customized to match the look and feel of the page by overriding the default CSS file. The functionality provided by the widget can also be extended, allowing the user to create their own custom version to handle more advanced tasks.
This task lists the steps needed to enable phone call management in an existing application, including how to install the SIP IP PBX sample application and configure the application server. To quickly learn how the CEA widgets work in an online application, we can install the PlantsByWebSphere Ajax Edition for CEA (PlantsByWebSphereAjax) sample application. For more information about the sample application, see the supporting documentation provided in the PlantsByWebSphere directory of the CEA samples package that we can download from the WebSphere Application Server Samples page. Additionally, read about setting up and using the communications enabled application samples.
In the following procedure, complete either Step 6 or Step 7. Step 6 enables the widget for desktop browsers. Step 7 enables the widget for Apple and Android mobile browsers.

Enable the system application.
Install and configure the IP PBX.
Configure the IP PBX location.
Restart the application server.
Copy the CEA widgets into the application you are enhancing.
Embed the widgets in the application you are enhancing for desktop browsers.
Embed the mobile widgets in the application you are enhancing.
Install and start the application that we have enhanced.
Test the application that we have enhanced.

Procedure
Enable the system application.
The system application owns the REST interface. Update the configuration for each server running CEA.

Access the CEA settings panel in the dmgr console.

In a single-server environment
Servers | Server Types | WebSphere application servers | server_name | CEA

In a clustered environment
Servers | Clusters | WebSphere application server clusters | server_cluster | CEA

Because servers in a cluster are clones of each other, you only need to make configuration changes from the main cluster panel for the cluster, not for each individual server in the cluster.

Ensure the check box labeled "Enable communications service" is checked.

Install and configure the IP PBX.
The IP PBX must support the ECMA TR/87 protocol. Complete the following actions to set up a sample PBX application that we can use for unit testing in the absence of an official PBX.

Start the application server.
Install the SIP IP PBX sample application. The sample IP PBX is an enterprise application that must be installed using the dmgr console or wsadmin tool. This sample application is located in the installableApps directory of the CEA samples package.
Notes:

We can use the Fast Path option when installing the application using the dmgr console, and no changes to the default (Fast Path) settings are required.
In an initial demonstration or test environment, it is acceptable to install the sample IP PBX application to the instance of WebSphere Application Server that hosts one or more communications enabled applications. When this approach is taken, the default CEA settings can be used in cases where the application server is configured to utilize the default SIP_DEFAULTHOST port (5060); it is unnecessary to make any changes to the CEA settings using the dmgr console or wsadmin.

Start the application.

Configure the IP PBX location.
The following information must be configured on the server where the CEA system application is running.

In the dmgr console
Servers | Server Types | WebSphere application servers | server_name | CEA

Use the CEA settings page to select the Use SIP CTI (ECMA TR/87) gateway for telephony access option and configure the following fields:
Set the following fields based on the server that is running the PBX application.

Host name or IP address
Port - For the TCP Protocol, select the port SIP_DEFAULTHOST for the server that is running the PBX application.
Protocol (TCP)
Superuser name

We can specify a Superuser name on the CEA settings panel. The superuser corresponds to a user, who is configured on the PBX, and has the ability to control any phone that is configured on the PBX. Also, the superuser has the ability to control multiple phones concurrently. This functionality, however, is not supported on every PBX. The Cisco PBX requires set a user name for each phone to control. The Superuser name field on the CEA settings panel can only pass a single user name; therefore, it can only control a single device. To control multiple phones concurrently using the Cisco PBX, you must derive the user name from the user credentials for this PBX. To accomplish this task, ensure the Extract user name from request check box is selected on the CEA settings panel.

Restart the application server.

Restart the application server.

Copy the CEA widgets into the application you are enhancing.
Restart the application server.
The CEA widgets are included in the Dojo Toolkit installed at...
app_server_root/etc/cea/javascript

Copy the ceadojo directory into the WebContent directory of the application.
Embed the widgets in the application you are enhancing for desktop browsers.
Import the default Dojo and ClickToCall widget CSS.
<style type="text/css"> 
   @import "<contextRoot>/ceadojo/dijit/themes/tundra/tundra.css";
   @import "<contextRoot>/ceadojo/cea/widget/ClickToCall/ClickToCall.css";
   @import "<contextRoot>/ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
</style>  
Add the following JavaScript code to import the Dojo Toolkit that is included with the CEA feature.
<script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js"
   djconfig="parseOnLoad: true, isDebug: false"></script>  
If the page is already using a version of Dojo add the following JavaScript code instead of the preceding code. This code enables multiple versions of the Dojo on the same page.
<script type="text/javascript">     var djConfig = { baseUrl:"<contextRoot>/ceadojo/dojo/" };
</script> 
<script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js"></script>
gotcha
Place the widget on the page using the following HTML code:
<div ceadojoType="cea.widget.ClickToCall" 
     widgetNumber="xxx-xxx-xxxx" 
     enableCollaboration="false" 
     canControlCollaboration="false" 
     defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html">  
Replace all instances of "<contextRoot>/" with the context root of the application.
Relative URIs can also be used instead of specifying the paths including the context root. The joinCollaborationUri, however, must be specified as an absolute or full URI.

Replace xxx-xxx-xxxx with the destination SIP URI.
To configure this widget to be available for a web collaboration session, change enableCollaboration="false" to "true".
To configure this widget to be available to drive the web collaboration session, change canControlCollaboration="false" to "true".
enableCollaboration must also be set to true.

To configure the default page shown when the Collaboration Dialog is launched, update defaultCollaborationUri.
enableCollaboration must also be set to true.
Override the widget CSS if necessary to match the look and feel of the page.
Example
Use the following example HTML code to place the ClickToCall widget on a web page.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">; 
   <html xmlns="http://www.w3.org/1999/xhtml">; 

   <head>;
   <title>;Click To Call Widget</title>; 

   <style type="text/css">; 
       @import "<contextRoot>;/ceadojo/dijit/themes/tundra/tundra.css";
       @import "<contextRoot>;/ceadojo/cea/widget/ClickToCall/ClickToCall.css";
       @import "<contextRoot>;/ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
     </style> 
<script type="text/javascript" 
        src="<contextRoot>/ceadojo/dojo/dojo.js"
        djconfig="parseOnLoad: true, isDebug: false"></script> </head> 

<body class="tundra">    <div ceadojoType="cea.widget.ClickToCall" 
        widgetNumber="sip:CSR@localhost" 
        enableCollaboration="true" 
        canControlCollaboration="true" 
        defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html"> </body> </html>
ClickToCall widget attributes and descriptions

ceaContextRoot

The context root to access the CEA service.

widgetNumber

Used by the widget to determine what device to call.

enableCollaboration

Whether this widget will be made available for Contact center cobrowsing. If Contact center cobrowsing is enabled, you must also configure canControlCollaboration and defaultCollaborationUri.

canControlCollaboration

Whether this widget will be able to drive the collaboration session

defaultCollaborationUri

What page to load first when the Contact center cobrowsing is started.

highlightElementList

A comma-separated list of HTML element types that can be highlighted during a cobrowsing session.

isHighlightableCallback

Name of the callback function to run to determine if the current element is highlightable. If not provided, only the highlightElementList will be used.

isClickableCallback

Name of the callback function to run to determine if the current element is clickable. This is useful to block certain actions from being run when follow me mode is enabled.

sendPageUrlRewriteCallback

Name of the callback function to run when send page is called to rewrite the current URL. This is useful when one of the peers is using a Proxy to access the web application.

peerDeviceControlled

Determines which device should be controlled to initiate the call. If true, the device specified by widgetNumber is used and if false, the device specified by the end user ( 'My Number' ) will be used.
Embed the mobile widgets in the application you are enhancing.
Add the viewport metatag to make the widget display in full-screen mode.
<meta name="viewport" content="height=device-height, width=device-width, initial-scale=1,
   maximum-scale=1, user-scalable=no"/>
Import the default Dojo and ClickToCall widget CSS.
<style type="text/css"> 
   @import "<contextRoot>/ceadojo/dijit/themes/tundra/tundra.css";
   @import "<contextRoot>/ceadojo/dojox/mobile/themes/iphone/iphone.css";
   @import "<contextRoot>/ceadojo/cea/mobile/widget/ClickToCall/ClickToCall.css";
   @import "<contextRoot>/ceadojo/cea/mobile/widget/CollaborationDialog/CollaborationDialog.css";
   @import "<contextRoot>/ceadojo/cea/mobile/widget/iFrame/iFrame.css"; 
</style>
Add the following JavaScript code to import the Dojo Toolkit that is included with the CEA feature.
<script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js"
   djconfig="parseOnLoad: true, isDebug: false"></script>  
If the page is already using a version of Dojo add the following JavaScript code instead of the preceding code. This code enables multiple versions of the Dojo on the same page.
<script type="text/javascript">    var djConfig = { baseUrl:"<contextRoot>/ceadojo/dojo/" };
</script> 
<script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js"></script>
gotcha
Add the following JavaScript to hide the location bar for the browser, and display the widget in full screen mode.
<script type="text/javascript">    window.onload = function() {
      setTimeout(function(){window.scrollTo(0, 1);}, 100);
   }
</script>
Place the mobile widget on the page using the following HTML code:
<div ceadojoType="cea.mobile.widget.ClickToCall" widgetNumber="xxx-xxx-xxxx" 
   enableCollaboration="false" canControlCollaboration="false" 
   defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html">
Replace xxx-xxx-xxxx with the destination SIP URI.
To configure this widget to be available for a web collaboration session, change enableCollaboration="false" to "true".
To configure this widget to be available to drive the web collaboration session, change canControlCollaboration="false" to "true".
enableCollaboration must also be set to true.
To configure the default page shown when the Collaboration Dialog is launched, update defaultCollaborationUri.
enableCollaboration must also be set to true.
Override the widget CSS if necessary to match the look and feel of the page.
Example
Use the following example HTML code to place the ClickToCall widget on a web page.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 
 <html xmlns="http://www.w3.org/1999/xhtml"> 
<head>    <title>Click To Call Widget</title> 
   <meta name="viewport" content="height=device-height, width=device-width, initial-scale=1, 
       maximum-scale=1, user-scalable=no/">    <style type="text/css"> 
      @import "<contextRoot>/ceadojo/dijit/themes/tundra/tundra.css";
      @import "<contextRoot>/ceadojo/dojox/mobile/themes/iphone/iphone.css";
      @import "<contextRoot>/ceadojo/cea/mobile/widget/ClickToCall/ClickToCall.css";
      @import "<contextRoot>/ceadojo/cea/mobile/widget/CollaborationDialog/CollaborationDialog.css";
      @import "<contextRoot>/ceadojo/cea/mobile/widget/iFrame/iFrame.css"; 
   </style> 
   <script type="text/javascript" 
           src="<contextRoot>/ceadojo/dojo/dojo.js"
           djconfig="parseOnLoad: true, isDebug: false"></script> 
   <script type="text/javascript">       window.onload = function() {
         setTimeout(function(){window.scrollTo(0, 1);}, 100); 
      }
   </script>  </head> 
<body class="tundra">    <div ceadojoType="cea.mobile.widget.ClickToCall" 
        widgetNumber="sip:CSR@localhost" 
        enableCollaboration="true" 
        canControlCollaboration="true" 
        defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html">  </body>  </html>
ClickToCall widget attributes and descriptions

ceaContextRoot

The context root to access the CEA service.

widgetNumber

Used by the widget to determine what device to call.

enableCollaboration

Whether this widget will be made available for Contact center cobrowsing. If Contact center cobrowsing is enabled, you must also configure canControlCollaboration and defaultCollaborationUri.

canControlCollaboration

Whether this widget will be able to drive the collaboration session

defaultCollaborationUri

What page to load first when the Contact center cobrowsing is started.

highlightElementList

A comma-separated list of HTML element types that can be highlighted during a cobrowsing session.

isHighlightableCallback

Name of the callback function to run to determine if the current element is highlightable. If not provided, only the highlightElementList will be used.

isClickableCallback

Name of the callback function to run to determine if the current element is clickable. This is useful to block certain actions from being run when follow me mode is enabled.

sendPageUrlRewriteCallback

Name of the callback function to run when send page is called to rewrite the current URL. This is useful when one of the peers is using a Proxy to access the web application.

peerDeviceControlled

Determines which device should be controlled to initiate the call. If true, the device specified by widgetNumber is used and if false, the device specified by the end user ( 'My Number' ) will be used.
Install and start the application that we have enhanced.
Install and start the application that we have enhanced.

Test the application that we have enhanced.

Verify the application containing the page with the embedded ClickToCall widget is running.
Browse to the page with the embedded ClickToCall widget, enter your source SIP URI, and then click the Call button. To successfully test using the soft phones and specify numbers or addresses when using the ClickToCall widget, the SIP phone numbers must be specified in the format sip:userName@hostName, where hostName is the host name or IP address of the SIP proxy or IP PBX.
Answer the source phone when it rings.
Answer the destination phone when it rings.

If problems are encountered, troubleshooting can be done to find the source. Here is a checklist.

Is the IP PBX installed and started? If using the sample IP PBX, the dmgr console of its application server can be used to verify the installation.

Are the phones set up correctly? They should list they are registered with the IP PBX and in ready state.

Is the new application installed and started? Check with the dmgr console or verify by looking in the SystemOut.log file.
Initiate a network trace to see how messages are exchanged on the network between the application, IP PBX, and phones.

When you test the widgets, use two separate browsers, or the same browser on two separate machines. Using tabs in the same browser, or even launching separate instances of the same browser on the same machine, causes session issues.

Enable browser cookies to allow the CEA widgets to store state information about the active widget session. This process enables the user to access another web page with the embedded CEA widget or refresh the current page while keeping the widget session active. If you disable cookies and access another page with the embedded CEA widget or refresh the current page, the CEA widget loads to the default state.
Related
Set up the communications enabled application samples
Troubleshoot applications with HPEL
Samples documentation
Multiple Versions of Dojo in a Page

+
Search Tips | Advanced Search