Access telephony services with web services clients

WAS v8.5 > End-to-end paths > Communications enabled applications
Access telephony services with web services clients

We can integrate telephony services into new and existing applications using the web services interface of communications enabled applications (CEA). Telephony services include making phone calls, receiving phone calls, and receiving call notifications within the web application.
The CEA capability 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 application 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.
Web services require a WSDL file that describes the interface. The WSDL file can be interpreted by web service tools to generate the web services client code needed to communicate with the web service. As a result, an application developer need only call the correct set of Java APIs to manage phone calls in an application.
This task lists the steps needed to create and deploy an application that can manage phone calls, including how to configure the application server. Formerly, this capability required building SIP servlets and a detailed understanding of the SIP specification. The CEA technology greatly reduces the amount of code required.
Using CEA capabilities, we can perform the following:

Open a session to start monitoring a phone
Get notifications about phone activity
Make phone calls between two phones
End an active phone call
Close a session to stop monitoring a phone

To open a session and monitor a phone for activity, provide an address of record for the phone. This could be a URI (uniform resource indicator) of a phone. A SIP URI, for example, has the format of sip:username@serviceprovider, which represents the address of your phone on the Internet.

Enable the system application.
Install the WSDL file.
Install and configure the IP PBX.
Configure the IP PBX location.
Restart the application server.
Develop an application.
Install and start the new application.
Test the new application.

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 the WSDL file.
Point the web browser to http://host:port/commsvc.rest/ControllerService?wsdl, where host is the IP address or host name on which the web container is listening, and port is the port number on which the web container is listening. When we do this, the WSDL file created in the file system during installation is read by the web services infrastructure, and the correct host and port are configured in the WSDL file sent to the browser.

Install and configure the IP PBX.
Restriction: 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.
Develop an application.
The application that you develop is to call the web services interface. Use the following CEA web service APIs to access telephony services with web service clients:

W3CEndpointReference openSession(CommWsRequest)
void makeCall(CommWsRequest)
void endCall()
void closeSession()

For another example, see the CEA sample application that comes with the CEA feature.
The following example shows how each of the APIs is used. For example, the return value from openSession is very important. It is an endpoint reference that must be used in all other APIs called related to the session monitoring that phone.
import com.ibm.ws.commsc.webservice.client.*;
...
public class Sample {

   private ControllerService controllerService = null;
   private Controller controllerPort = null;
   private W3CEndpointReference EPR = null;
   private Controller controllerPortWithEPR = null;

   // Constructor 
   public Sample() {
      // Access the web services client       
      controllerService = ControllerService();
      if (controllerService!= null) {
         // Access the port on which main APIs are called          
         controllerPort = controllerService.getControllerPort();
      }
      ...
   }
 
   // Open a session to monitor/control a phone
   public void openSession(String addressOfRecord, String notifyCallback) {
      // Build a request object       CommWsRequest wsRequest = new CommWsRequest();
      wsRequest.setAddressOfRecord(addressOfRecord);
      wsRequest.setNotifyCallback(notifyCallback);
      EPR = controllerPort.openSession(wsRequest);
      controllerPortWithEPR = EPR.getPort(Controller.class, new AddressFeature(true));
   }

   // Make a call
   public void makeCall(String calleeAddressOfRecord) {
      // Build a request object       CommWsRequest wsRequest = new CommWsRequest();
      wsRequest.setPeerAddressOfrecord(calleeAddressOfRecord);
      // Make the call, using the EPR returned in openSession()
      controllerPortWithEPR.makeCall(wsRequest);
   }

   // End an active call
   public void endCall() {
      // End the call, using the EPR returned in openSession()
      controllerPortWithEPR.endCall(wsRequest);
   }
   
   // Close the session monitoring the phone
   public void closeSession() {
      // Close the session, using the EPR returned in openSession()
      controllerPortWithEPR.closeSession();
   }

   ...}
Install and start the new application.

Test the new application.

Verify the application that includes a call to the web service is running.
Take the application-specific action that triggers the call to the web service API.
Answer the source phone when it rings.
Answer the destination phone when it rings.
Results

An application has been developed and deployed that uses a web services client to handle phone calls and call notifications.
If problems are encountered, use the following check list for troubleshooting the problem:

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.

To avoid connection timeout exceptions, it is a best practice to increase the default connection using the Java virtual machine custom property...
com.ibm.websphere.webservices.http.maxConnection

The default connection is 50 and once it is reached, the next request waits for a connection to be freed. If it does not get a connection in 5 minutes, it can time out. You might increase the default connection from 50 to 200 in a scenario where you need more connections. To learn more about this custom property, see the HTTP transport custom properties for web services applications. To learn how to configure this custom property, see the JVM custom properties information..
This task lists the steps needed to access telephony services with web services clients. A sample web services application is also available in the CEA samples package that we can download from the WebSphere Application Server samples site. For more information about the sample application, see the supporting documentation provided in the root directory of the CEA samples package. Additionally, read about setting up and using the communications enabled application samples.

Related
Access the samples
Set up the communications enabled application samples
Samples documentation
HTTP transport custom properties for web services applications
Java virtual machine custom properties
Install enterprise application files
Start or stop enterprise applications

+
Search Tips | Advanced Search