Using the IBM Lotus Sametime Unified Telephony API

This article describes the IBM® Lotus® Sametime® Unified Telephony API and the steps you take to deploy, configure, and invoke it. The Lotus Sametime Unified Telephony API is a REST (Representation State Transfer) API that provides click-to-call and click-to-conference semantics.

Mark Wallace (mark_wallace@ie.ibm.com), Software Architect, IBM

Mark Wallace is a software architect working in the Dublin Software Lab for IBM Ireland. He joined IBM Lotus in 1993 and since then has worked on a wide range of projects including IBM Lotus Sametime Translation Services, Lotus Sametime Everyplace, the IBM data access tool, and Lotus Component Designer. His current role is technical lead for a team in Dublin that is contributing to the IBM Lotus Sametime Unified Telephony project. You can reach him at mark_wallace@ie.ibm.com.



John Crawley (CRAWLEYJ@ie.ibm.com), Software Developer, IBM

John Crawley is a software developer and has been an IBM employee since 2006. He is currently working on the IBM Lotus Sametime Unified Telephony project and was previously a member of the IBM Learning team. You can reach John at CRAWLEYJ@ie.ibm.com.



30 June 2009

Also available in Chinese

Editor's note: Know a lot about this topic? Want to share your expertise? Participate in the IBM Lotus software wiki program today.

Introduction

IBM Lotus Sametime Unified Telephony software is middleware that provides unified communications features in heterogeneous telephony environments. The product includes the ability to start a phone call with one or more contacts or external numbers, telephony presence to show if a contact is currently on a phone call, and preferences to allow the users to configure how their incoming calls are routed using multiple criteria.

This article assumes that you are familiar with Lotus Sametime, IBM WebSphere® Application Server, Java™ Server Pages, and Web technologies. The article begins with the steps to install and configure the REST API and then describes how to invoke the API. Additionally, some advanced deployment options are discussed.

The REST API provides click-to-call and click-to-conference semantics, allowing a call to be established between a registered user and one or more Lotus Sametime contacts or external phone numbers. This REST API shares a common signature with the Lotus Sametime Connect Web Kit telephony API, which allows you to write an application that switches between using the local or remote API depending on availability.

Figure 1. Minimal Lotus Sametime Unified Telephony deployment
Minimal Lotus Sametime Unified Telephony deployment

There are two server types employed as part of a Lotus Sametime Unified Telephony deployment:

  • Lotus Sametime Unified Telephony core server. This server type manages the call model, aggregates telephony presence, keeps track of users and devices, executes workflows for calls, manages registration and routing for the Lotus Sametime soft-phone, and provides tones and announcements and ad hoc conference support. Optionally, it can also host the REST API.
  • Lotus Sametime Unified Telephony connect server. This server type provides the interface with the existing telephony environment. It is responsible for orchestrating the session initiation protocol (SIP) dialogue between the endpoints during a call, handling unified numbers, and maintaining SIP trunks to multiple private branch exchanges (PBXs), gateways, or both.

Installation and configuration

The Lotus Sametime Unified Telephony API is provided as a Java Platform, Enterprise Edition (Java EE) enterprise application and can be installed as part of the Lotus Sametime Unified Telephony Core server. Some configuration steps are required after the enterprise application is configured to allow it to connect to the Lotus Sametime server and optionally to support publishing information about the Lotus Sametime Unified Telephony API. Installation and configuration steps are automated as part of the Lotus Sametime Unified Telephony Core server installer; this is the easiest way to install the enterprise application.

Follow these steps to install the Lotus Sametime Unified Telephony API using the Lotus Sametime Unified Telephony Core server installer:

  1. Open an SSH session on the Lotus Sametime Unified Telephony Core server and authenticate as the root user.
  2. Change to the /software/IBM folder
  3. Start the installer to install the REST API using the following command:

    ./install.sh rest
  4. Enter YES when you are prompted to read the license agreement and accept it. The REST API enterprise application is installed.
  5. Start the WebSphere Application Server using the following command:

    /opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
  6. Restart the OSGI container using the following command:

    /etc/init.d/symphoniad restart

Follow these steps to install the REST API using the WebSphere Application Server integrated solutions console:

  1. Copy the following file from the Lotus Sametime Unified Telephony Core server to the machine where you plan to run the integrated solutions console:

    /software/IBM/SUT/Admin/webApps/sutapi-app-8.0.ear
  2. Open the WebSphere Application Server integrated solutions console for your Lotus Sametime Unified Telephony Core server; for example:

    https://<your server>:9043/ibm/console/logon.jsp
  3. Navigate to Applications - Enterprise Applications, and the click the Install button.
  4. Select the Remote file system option, and then click the Browse button.
  5. Browse to the following location:

    /software/IBM/SUT/Admin/webApps
  6. Select the file sutapi-app-8.0.ear, and click OK.
  7. Keep the default option Prompt me only when additional information is required, and click the Next button.
  8. Click Next to accept the default installation options.
  9. Click Next' to accept the default server module mapping.
  10. Click the Finish button to complete the installation, and then click Save to update the configuration.
  11. Select the Sametime Unified Telephony API option, and then select the Environment entries for web modules option.
  12. Enter the IP address of the Lotus Sametime Unified Telephony Core server in the serviceAddress field.
  13. Enter the host name of the Lotus Sametime server into the sametimeServer field.
  14. Enter the port number (typically 1516) to be used when connecting to the Lotus Sametime server in the sametimePort' field.
  15. This step is optional; it is required only for Lotus Sametime 8.5 interoperability. Enter the attribute number (typically 40002) in the baseUrlAttr field.
  16. This step is optional; it is required only for Lotus Sametime 8.5 interoperability. Enter the base URL for the REST API in the baseURL field. For example, enter:

    http://<server>:<port>/sutapi MW
  17. Click OK and then click Save to update the configuration.

After you have installed the Lotus Sametime Unified Telephony API, you need to complete some configuration steps to configure security for the application. This process is required because the REST API will work only for users who are provisioned on the Lotus Sametime Unified Telephony Core server. If unauthenticated users or users who are not provisioned to use Lotus Sametime Unified Telephony invokes the REST API, their requests are ignored.

NOTE: The Lotus Sametime Unified Telephony Core server installer does not automate the process of configuring the security settings so the following steps must always be performed.

Follow these steps to configure security for the Lotus Sametime Unified Telephony API:

  1. Open the WebSphere Application Server integrated solutions console for your Sametime Unified Telephony Core server:

    https://>your server>:9043/ibm/console/logon.jsp
  2. Navigate to Security - Secure administration, applications, and infrastructure.
  3. Select the Enable application security option, and then click Apply.
  4. Click Save to update the configuration.
  5. Navigate to Applications - Enterprise Applications.
  6. Select the Sametime Unified Telephony API option, and then select the Security role to user/group mapping option.
  7. For the AllAuthenticateUsers role, select All authenticate and then click OK.
  8. Click Save to update the configuration.
  9. Select Sametime Unified Telephony SIP Registrar, and then select the Security role to user/group mapping option.
  10. For the secureRole and admins roles, select the Everyone option, and then click OK.
  11. Click Save to update the configuration.
  12. Restart the Sametime Unified Telephony Core server so that these changes take effect.

Next, WebSphere Application Server must be configured so that it uses the same enterprise directory or directories as the Lotus Sametime server to authenticate users. WebSphere Application Server is configured to use a file-based repository for the default administration users. A federated repository can be used to allow this to co-exist with the enterprise directory. For more information on configuring a federated repository for WebSphere Application Server, refer to the WebSphere Application Server Version 6.1 Information Center.

To validate that the Lotus Sametime Unified Telephony API is working properly, perform the following steps:

  1. Log on with a Lotus Sametime Unified Telephony enabled client.
  2. Open a browser, and enter a URL like this one:

    http://sutd-tas03.mul.ie.ibm.com:9080/sutapi/stwebapi/call?device=<preferred device>&userId=<user ID or phone number>
  3. When prompted, authenticate and use a valid user name for your Sametime Unified Telephony Core server.

The specified device rings; when it is answered, the specified telephone number or user is called.


Invoking the REST API

Now that the Lotus Sametime Unified Telephony API is installed and configured, you can begin testing. The simplest type of call that can be made is between a user's dependable device and an external phone number. This is the syntax for invoking the REST API to make this type of call:

http://<your server>/sutapi/stwebapi/call?userId=<external phone number>

When you enter this URL into a browser, you are prompted to enter your credentials. When you have authenticated successfully, your dependable device rings; when you answer, the external phone number is dialed. One thing to note is that, when specifying the external number using the E.164 format, you must encode the leading + as %2B. The parameter name is userId to maintain compatibility with the Telephony API in the Lotus Sametime Connect Web Kit, which is part of the Lotus Sametime 8.0.2 Software Developer Kit.

The next option is to specify the phone that is used by the caller. This is the syntax for invoking the REST API to make this type of call:

http://<your server>/sutapi/stwebapi/call?device=<your phone number>&userId=<external phone number>

Using the device parameter allows the caller's dependable device to be overridden with the currently preferred device. Note that specifying your unified number as the preferred device is not valid in the first release of Lotus Sametime Unified Telephony.

The next option is to call a user using the user ID. This is the syntax for invoking the REST API to make this type of call:

http://<your server>/sutapi/stwebapi/call?device=<your phone number>&userId=<user id>

Using this option, the telephony number of the person is resolved on the server using the User Information Service.

The next option is to call multiple users. This is the syntax for invoking the REST API to make this type of call:

http://>your server>/sutapi/stwebapi/call?userId=<phone1,phone2,...>

Using this option, a conference call is initiated. The caller is dialed first, and when the users join, the other participants are dialed into the conference. Note that it is not valid to use the device parameter when starting a conference call.


Advanced configuration

This section of the article covers the following advanced configuration options:

  • Installing the Lotus Sametime Unified Telephony API on a separate server
  • Clustering
  • Single sign-on
Figure 2. Lotus Sametime Unified Telephony API on a separate server
Lotus Sametime Unified Telephony API on a separate server

Figure 2 shows the Lotus Sametime Unified Telephony API installed on a separate WebSphere Application Server and connected to a cluster of Lotus Sametime Unified Telephony core servers. The Sametime Unified Telephony API can be deployed to a dedicated server by following the steps to install the REST API using the WebSphere Application Server integrated solutions console. You must also ensure that the server uses the same enterprise directory or directories as the Lotus Sametime server to authenticate users. The communication between the Lotus Sametime Unified Telephony API and the Lotus Sametime Unified Telephony core server happens through the Lotus Sametime server. The Lotus Sametime Unified Telephony API connects to the Lotus Sametime server as a server application; to work, the IP address of the server where it is installed must be listed in the trusted IPs on the Lotus Sametime server (the Lotus Sametime Unified Telephony core server also gets added to this list when it is deployed).

If your environment contains a cluster of Lotus Sametime Unified Telephony core servers, then it is possible to have a single Sametime Unified Telephony API instance handle all the requests for the cluster. For this approach to work, you must modify the communications service configuration on the Lotus Sametime Unified Telephony core server to which the Sametime Unified Telephony API is connected. Follow these steps to modify the configuration to support a cluster:

  1. Open a Secure Shell (SSH) session on the Lotus Sametime Unified Telephony core server and authenticate as the root user.
  2. Change to the /enterprise/ibm folder.
  3. Edit the sutbcomadapter.properties file.
  4. Add (or edit) the property STIBroadcastMakeCall so that the value is true.
  5. Restart the OSGI container using the following command:

    /etc/init.d/symphoniad restart

After these changes are made, any requests that the server receives to make a call on behalf of the Lotus Sametime Unified Telephony API, and that are not intended for this server, are broadcast to the cluster.

Figure 3 illustrates how the Lotus Sametime Unified Telephony API can be used by an application acquired from another vendor. There are several ways that the Lotus Sametime Unified Telephony API can be invoked. The application acquired from another vendor can do the following:

  • Emit markup to the client that directly references the Lotus Sametime Unified Telephony API
  • Directly invoke the Lotus Sametime Unified Telephony API by making an HTTP request to the server where it is hosted
Figure 3. Lotus Sametime Unified Telephony API used by an application acquired from another vendor
Lotus Sametime Unified Telephony API used by an application acquired from another vendor

For these options to work, single sign-on must be configured between the server hosting the application acquired from another vendor and the server hosting the Lotus Sametime Unified Telephony API. For information on configuring single sign-on between WebSphere Application Server and either IBM Lotus Domino® or another WebSphere Application Server, refer to the WebSphere Application Server Version 6.1 Information Center. Note that for the second option to work, the LTPA token must be explicitly passed when the request is made.

The application acquired from another vendor needs to discover the base URL of the Lotus Sametime Unified Telephony API. This task can be done by either using a configuration setting in the application or using the Lotus Sametime API to retrieve the base URL from the server attribute that the Lotus Sametime Unified Telephony API has published. The optional configuration steps for the Lotus Sametime Unified Telephony API listed above are required for this second option to work. When the base URL attribute and value are configured, the Lotus Sametime Unified Telephony API application publishes the base URL using the specified attribute value (the recommended default is 40002) as an attribute of the Lotus Sametime server to which it connects. Any application can now retrieve this value by reading the server attribute (refer to the Lotus Sametime SDK for more information on reading server attributes). Retrieving the base URL by reading the server attribute that is used for interoperability between Lotus Sametime Unified Telephony and Lotus Sametime 8.5 and later.


The sample application

Included with this article in the Download section is a sample application that demonstrates calling the Lotus Sametime Unified Telephony API from a custom application. The application displays a list of names and phone numbers and provides the following features:

  • Click to call a phone number
  • Click to call a user ID
  • Click to conference multiple phone numbers

The sample application contains hard-coded names and phone numbers that you must change. You should edit the project using IBM Rational® Application Developer and change the values to ones that are appropriate for your deployment.

To edit the sample application, follow these instructions:

  1. Open the class PeopleBean.java. At the top of this file there is an array containing the names, user IDs, and phone numbers that are used in the sample as shown in listing 1.
Listing 1. Array of Person Bean objects
private PersonBean[] people = new PersonBean[] {
  new PersonBean("Mark Wallace", "mark_wallace@ie.ibm.com", "+18004264968"),
  new PersonBean("John Crawley", "crawleyj@ie.ibm.com", "+18887467426")
};
  1. Edit this array to add values that are appropriate for your deployment.

Then you can export the project as a Web Application Archive (WAR) file that can be installed on to your Lotus Sametime Unified Telephony core server. Refer to the section "Installing application files with the console" in the WebSphere Application Server, Version 6.1 Information Center for more information on installing a WAR file.

The application has one environment entry that must be configured:

  • The base URL for the REST API, for example, http://<server>:<port>/sutapi

See figure 4.

Figure 4. Configuring environment entries for the sample application
Configuring environment entries for the sample application

The application security role user must be mapped to All authenticated as shown in figure 5.

Figure 5. Mapping user security role to the All authenticated option
Mapping user security role to the All authenticated option

To access the application, you use a URL like this one:

http://9.45.89.226:9080/sutapisample/People.jsp

You are prompted to authenticate to access this page.

Figure 6 shows a sample application.

Figure 6. Lotus Sametime Unified Telephony API sample application
Lotus Sametime Unified Telephony API sample application

NOTE: The telephone numbers specified in the sample are IBM numbers:

General inquiries 800-IBM-4YOU (800-426-4968)Shopping assistance 888-SHOP-IBM (888-7467-426)

To start a call, you can click either a user name or a phone number. You are then prompted to specify a preferred device for placing the call as shown in figure 7.

Figure 7. Prompting for your preferred device
Prompting for your preferred device

After you enter a phone number and click OK, the Lotus Sametime Unified Telephony API is invoked and the user ID or phone number that you clicked is sent as the target for the call.

To start a conference call, you must select multiple people and then click the Call selected button.

The JSP page displays a list of names and phone numbers in an HTML table. Each name and phone number pair is displayed as a hyperlink. When these links are clicked, a JavaScript method is invoked that calls the Lotus Sametime Unified Telephony API.

The sample provided in the Download section of this article includes a JavaScript file that is responsible for invoking the Lotus Sametime Unified Telephony API. It uses the XMLHttpRequest JavaScript object to make an Ajax-style request against the API. Listing 2 shows the code used to invoke the API to make a two-party call.

Listing 2. JavaScript method to dispatch a call request
/*
 * Send a call request to the Sametime Unified Telephony API
 * baseUrl - Base URL of the SUT REST API
 * userId = user(s) or telephone number(s) to call
 */
function sendCallRequest(baseUrl, userId) {
	userId = escapeParam(userId);
	var device = promptPreferredDevice();
	if (device == null || device.length == 0) {
		alert("You must specify your preferred device.");
		return;
	}
	device = escapeParam(device);
	var url = baseUrl + "/stwebapi/call?device=" + device + "&userId=" + userId;
	alert(url);
	httpRequest.onreadystatechange = stateChange;
	httpRequest.open("GET", url, true);
	httpRequest.send(null);	
}

The JavaScript builds the correct URL to invoke by doing the following:

  • Using the base URL that was configured above when the sample application was installed
  • Encode the userId as the parameter to be included in the URL
  • Prompting users to enter their preferred device, as required for a two-party call
  • Encode the device as the parameter to be included in the URL
  • Building the URL to be invoked using the base URL and parameters
  • Using the XMLHttpRequest object to perform a HTTP GET operation using the URL

Conclusion

This article explained how to deploy and use the Lotus Sametime Unified Telephony API. It showed you how the API can be deployed as part of the Lotus Sametime Unified Telephony core server and also explained additional deployment options. The Lotus Sametime Unified Telephony API is REST based and can be integrated with applications that are built on different technology stacks. The sample application included with this article shows one example of how to integrate this API with a custom Java EE application. The techniques used in the sample application can be applied to allow the API to be invoked from your own applications.


Download

DescriptionNameSize
Code sampleSUTAPISample.zip14KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=403748
ArticleTitle=Using the IBM Lotus Sametime Unified Telephony API
publish-date=06302009