Receive call notifications in web applications

WAS v8.5 > End-to-end paths > Communications enabled applications
Receive call notifications in web applications

We can embed the CallNotification widget in an existing application to enable users to enter their phone number and receive notifications of incoming calls. 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 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 section of the information center. The sample IP PBX is in the form of an 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 CallNotification widget is built using the functionality provided in the Dojo Toolkit. This widget can be configured to allow users to enter their phone number and receive notifications of incoming calls. The CallNotification 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 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 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.
Embed the mobile widgets in the application you are enhancing.
Install and start the application we have enhanced.
Test the application 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, click...
Servers > Server Types > WebSphere application servers > server_name > CEA

In a clustered environment, click...
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. Start the application server where you deploy the sample PBX application.
Install the SIP IP PBX sample application. This sample application is located in the installableApps directory of the CEA samples package.
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, click 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.

Copy the CEA widgets into the application you are enhancing.
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.
Import the default Dojo and CallNotification widget CSS.
<style type="text/css"> 
   @import "<contextRoot>/ceadojo/dijit/themes/tundra/tundra.css";
   @import "<contextRoot>/ceadojo/cea/widget/CallNotification/CallNotification.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>
Place the widget on the page using the following HTML code:
<div ceadojoType="cea.widget.CallNotification" 
     enableCollaboration="false" 
     canControlCollaboration="false" 
     defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html">
Replace "<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.
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.
The following example HTML code will place the CallNotification 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>Call Notification Widget</title> 
<style type="text/css"> 
    @import "<contextRoot>/ceadojo/dijit/themes/tundra/tundra.css";
    @import "<contextRoot>/ceadojo/cea/widget/CallNotification/CallNotification.css";
    @import "<contextRoot>/ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
</style> <script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js" 
    djConfig="parseOnLoad: true, isDebug: true"></script> </head> 
<body class="tundra">  <div ceadojoType="cea.widget.CallNotification" enableCollaboration="true" 
 canControlCollaboration="true" defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html"> </body> </html>
This example renders the following interface controls.
CallNotification widget attributes and descriptions

ceaContextRoot

The context root to access the CEA service.

widgetNumber

Used by the widget to determine what device to monitor for incoming calls. If not specified the user will be presented with a textfield to enter the number.

enableCollaboration

Whether this widget will be made available for Contact center cobrowsing. If Contact center cobrowsing is enabled you should 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 will be using a Proxy to access the web application.
Embed the mobile widgets in the application you are enhancing.
Add the following 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 CallNotification 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/CallNotification/CallNotification.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">
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>
Use the following HTML code to place the widget on the page.
<div ceadojoType="cea.mobile.widget.CallNotification" 
     enableCollaboration="false" 
     canControlCollaboration="false" 
     defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html">
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.
The following example HTML code will place the CallNotification mobile 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>Call Notification 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/CallNotification/CallNotification.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: true"></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.CallNotification" enableCollaboration="true" 
      canControlCollaboration="true" defaultCollaborationUri="<contextRoot>/cobrowseWelcome.html"> </body> 
</html>
CallNotification mobile widget attributes and descriptions

ceaContextRoot

The context root to access the CEA service.

widgetNumber

Used by the widget to determine what device to monitor for incoming calls. If not specified the user will be presented with a textfield to enter the number.

enableCollaboration

Whether this widget will be made available for Contact center cobrowsing. If Contact center cobrowsing is enabled you should 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 will be using a Proxy to access the web application.
Install and start the application we have enhanced.

Test the application we have enhanced.

Verify the application containing the page with the embedded CallNotification widget is running.
Browse to the page with the embedded CallNotification widget, enter your destination SIP URI, and then click the Start Call Notification button. To successfully test using the soft phones and specify numbers or addresses when using the CallNotification 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.
Initiate a call using the ClickToCall widget or a soft phone.
If the call is initiated from the ClickToCall widget, answer the source phone when it rings.
Answer the destination phone when it rings.
Results

You have enabled the CallNotification widget within an application to allow users to enter their phone number and receive notifications of incoming calls.
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 completely 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, will cause 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
Samples documentation
Troubleshoot applications with HPEL
Multiple Versions of Dojo in a Page

+
Search Tips | Advanced Search