Front cover
Getting Started with the WebSphere
Application Server Feature Pack for
Communications Enabled
Applications V1.0
Access communication systems from
business applications
Use widgets to add telephony and
Web collaboration features
Access communication
services using Web services
Carla Sadtler
Tejas Parajia
Katherine Sanders
Geetika Tandon
ibm.com/redbooks
Redpaper
International Technical Support Organization
Getting Started with the WebSphere Application Server
Feature Pack for CEA V1.0
February 2010
REDP-4613-00
Note: Before using this information and the product it supports, read the information in “Notices” on
page vii.
First Edition (February 2010)
This edition applies to the Feature Pack for Communications Enabled Applications, Version 1.0. for
WebSphere Application Server V7.
This document created or updated on March 11, 2010.
© Copyright International Business Machines Corporation 2010. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
The team who wrote this paper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Now you can become a published author, too! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Chapter 1. IBM WebSphere Application Server Feature Pack for CEA 1.0 . . . . . . . . . .
1.1 CEA application scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 Scenario 1: Click-to-call with co-browsing assistance from a customer service
representative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 Scenario 2: Shopping online with a friend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 Scenario 3: Tracking and reporting call statistics . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Communication services provided by the feature pack. . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 Telephony access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 Multimodal Web interaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Interfaces to the communications services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3 REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4 Selecting the interface to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 SIP applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.1 SIP application examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5 (New) Feature Pack for CEA Version 1.0.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
2
2
3
4
4
4
4
4
5
5
5
6
6
7
7
Chapter 2. Enabling applications for communications . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.1.1 The IP PBX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.1.2 The application server with the CEA feature pack installed . . . . . . . . . . . . . . . . . 10
2.1.3 The business application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.1.4 The user interface of the business application . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 Summary of implementation steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.1 Install the IP PBX or PBX emulator application. . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.2 Installing and configuring the application server . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.3 Incorporate the features into the business application . . . . . . . . . . . . . . . . . . . . . 13
2.3 Installation tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3.1 On development machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3.2 On development machines with WebSphere Application Server . . . . . . . . . . . . . 15
2.3.3 On WebSphere Application Server machines (no Rational Application Developer
installed) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 3. CEA feature pack architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1 Architectural overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Telephony Access Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Request flow: Making a call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Programming interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Using an external Web service provider to interact with the PBX . . . . . . . . . . . . .
3.3 Multimodal Web collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
© Copyright IBM Corp. 2010. All rights reserved.
17
18
19
19
20
20
20
iii
3.3.1 Request flow: multimodal collaboration using the Collaboration widget . . . . . . . .
3.3.2 Programming interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Session Initiation Protocol (SIP) support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 SIP servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.2 SIP runtime components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
22
22
23
23
Chapter 4. REST interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.1 REST interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Rest HTTP requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Call flow example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
28
28
28
29
Chapter 5. Using widgets for telephony and Web collaboration . . . . . . . . . . . . . . . . .
5.1 CollaborationDialog widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 Using the widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 CollaborationDataTransfer Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 ClickToCall Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 Click-to-call example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2 Using the widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.3 Embedding the Widget in a Web page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4 CallNotification widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Using the widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2 Embedding the widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5 Cobrowse widget. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.1 Using the widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5.2 Embedding the widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6 Click-to-call example using widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6.1 Part 1: Integrating the ClickToCall widget in the application . . . . . . . . . . . . . . . . .
5.6.2 Part 2: Integrating the CallNotification widget in the application . . . . . . . . . . . . . .
5.6.3 Part 3: Test the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
32
32
34
34
35
35
36
37
38
39
39
40
41
42
42
45
47
Chapter 6. Using Web services for telephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1 Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Web services tooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 CEA WSDL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Architectural flow: Call flow example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5 Implementation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6 Development process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.1 Create a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.2 Obtain the WSDL files and schema files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.3 Generate the Web services client code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.4 Create the servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.5 Generate the WS-Notification consumer service . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.6 Install the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.7 Test the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
52
52
52
53
54
54
55
55
56
59
61
65
66
Chapter 7. External Web services support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1 Call flow example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 Implementation overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.1 Configuring the location of the third-party Web service WSDL . . . . . . . . . . . . . . .
69
70
70
71
Chapter 8. Working with SIP applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.1 SIP application structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
8.1.1 Creating SIP applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
iv
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
8.1.2 Metadata for deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 SIP application packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.1 Using Rational Application Developer to package (export) a SIP project: . . . . . .
8.2.2 SIP and Java EE converged application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.3 SIP and HTTP converged application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.4 Accessing a SIP application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.5 Runtime structure for converged applications. . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3 SIP session flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4 Session objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5 Dialogs and SIP session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.6 SIP application development overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.7 Proxying SIP requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.7.1 ProxyBranch objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
75
77
77
77
78
78
79
79
80
81
81
87
87
Appendix A. Sample code for the Web services example. . . . . . . . . . . . . . . . . . . . . . . 89
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to get Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
101
101
101
101
Contents
v
vi
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not give you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring
any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of these programs.
© Copyright IBM Corp. 2010. All rights reserved.
vii
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both. These and other IBM trademarked terms are
marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US
registered or common law trademarks owned by IBM at the time this information was published. Such
trademarks may also be registered or common law trademarks in other countries. A current list of IBM
trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
IBM®
Lotus®
Rational®
Redbooks®
Redpaper™
Redbooks (logo)
WebSphere®
z/OS®
®
The following terms are trademarks of other companies:
Java, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other
countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
viii
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Preface
This IBM® Redpaper™ provides information about the architecture and implementation of the
features in the IBM WebSphere® Application Server Feature Pack for Communications
Enabled Applications, V1.0 (referred to as the CEA feature pack). This paper is considered an
entry point into the information. Use this paper to learn what the feature pack is, how you
might use it to improve your customer's experience on a Web site, and to get an idea of how it
is implemented.
The team who wrote this paper
This paper was produced by a team of specialists from around the world working at the
International Technical Support Organization, Raleigh Center.
Carla Sadtler is a Consulting IT Specialist at the ITSO, Raleigh Center. She writes
extensively about WebSphere products and solutions. Before joining the ITSO in 1985, Carla
worked in the Raleigh branch office as a Program Support Representative, supporting MVS
customers. She holds a degree in mathematics from the University of North Carolina at
Greensboro.
Tejas Parajia is a senior developer in the Lotuslive BSS team. He has more than ten years of
experiece in various phases of software development encompassing a range of technologies.
He has worked with the Lotus® division for the last six years and leads many product
development initiatives. He is also a regular speaker at various IBM Academy of Technology
(AoT) conferences. An innovator at heart, he is a member of a number of IBM internal
technical bodies and is on the board of one of the world-wide patent evaluation teams. Prior
to joining IBM he worked with start-up companies.
Katherine Sanders is a software engineer at IBM Hursley in the United Kingdom. She
develops and tests Web service functionality in WebSphere Application Server, with a
particular focus on WS-Addressing, WS-ReliableMessaging and WS-Notification. She holds a
degree in Computer Science from the University of Nottingham in the United Kingdom.
Geetika Tandon has been working at IBM for almost nine years. She joined the Federal
Technical Sales team in July 2006. She is a Senior IT Specialist at IBM Federal Software
Group in Washington D.C. She was a J2EE and WebSphere developer working on RFID
solutions in her previous capacity. She currently holds five patent files and is the author of six
publications. She is an evaluator for the Systems and Technology Invention Disclosure Team
and a core team member of the Women Inventors Community, which works actively
encourage patenting and innovation within IBM. Geetika holds two masters degrees, one in
Computer Science from UC Santa Barbara and another Masters in Architecture from
UniversityofSouthern California. In her spare time she is avid reader and hiker and loves to
write as well.
Thanks to the following people for their contributions to this project:
Craig Lanzen
IBM US
Geoff Duck
IBM Canada
© Copyright IBM Corp. 2010. All rights reserved.
ix
Vanessa Grose
IBM US
Lisa Bradley
IBM US
Yafit Sami
IBM Israel
Marie Wagner
IBM US
Andy Ivory
IBM US
Nitzan Nissim
IBM Israel
Now you can become a published author, too!
Here's an opportunity to spotlight your skills, grow your career, and become a published
author - all at the same time! Join an ITSO residency project and help write a book in your
area of expertise, while honing your experience using leading-edge technologies. Your efforts
will help to increase product acceptance and customer satisfaction, as you expand your
network of technical contacts and relationships. Residencies run from two to six weeks in
length, and you can participate either in person or as a remote resident working from your
home base.
Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us!
We want our papers to be as helpful as possible. Send us your comments about this paper or
other IBM Redbooks® publications in one of the following ways:
򐂰 Use the online Contact us review Redbooks form found at:
ibm.com/redbooks
򐂰 Send your comments in an e-mail to:
redbooks@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
x
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
1
Chapter 1.
IBM WebSphere Application
Server Feature Pack for CEA 1.0
The CEA feature pack is a set of libraries, widgets, and runtime components that provides the
ability to add dynamic Web communications to any application or business process. This
functionality includes the ability to establish a call between two users, to share sessions
between two users, to integrate communications features in applications with PBX systems,
and the additional features required to support these functions.
© Copyright IBM Corp. 2010. All rights reserved.
1
1.1 CEA application scenarios
Consider the following scenarios for enabling business applications for communication. These
scenarios illustrate how you can improve the customer experience for your Web site.
1.1.1 Scenario 1: Click-to-call with co-browsing assistance from a customer
service representative
In a click-to-call scenario with co-browsing (Figure 1-1), a customer browsing a commercial
Web site has a question for a customer service representative (CSR). The customer types
their phone number into the field supplied on the Web page to request a call be initiated with
the CSR (click-to-call). On the company Web site, a CSR has logged in and is waiting for call
notifications. When the customer requests a call, the CSR is connected to the customer
through voice over IP (VOIP).
Figure 1-1 Click-to-call with co-browsing
The CSR discusses the question over the phone. During the course of the call, the CSR offers
to show the customer a different product through contact center co-browsing. The specialist
clicks a button and receives an URL for the shared session. He provides the customer this
URL. When the customer enters the URL, a link between the two users is established and
new windows open on each browser. The customer can then view the pages the CSR is
highlighting, including items on the page, such as price or model number (Figure 1-2 on
page 3)
2
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Figure 1-2 Contact center co-browsing
Registered customers, with preferences, might have additional features available. The CSR
might be able to check the inventory of their preferred store location for the item. Or the
customer might be viewing the page in a language that is different from the language used by
the product specialist.
1.1.2 Scenario 2: Shopping online with a friend
In an online co-shopping scenario (Figure 1-3), two customers are talking over the phone and
shopping the same Web site. They can co-shop by sharing their browser sessions with each
other (peer-to-peer cobrowsing). Two-way collaboration is enabled, allowing each person to
show pages to the other and highlighting items of interest. Each user, however, is able to
maintain a separate session with their own shopping cart and preferences.
Figure 1-3 Peer-to-peer co-browsing
Chapter 1. IBM WebSphere Application Server Feature Pack for CEA 1.0
3
1.1.3 Scenario 3: Tracking and reporting call statistics
A company wants to track the number of calls they receive in a day. They have a business
application with a non-Web layer that uses a Web service client generated from the WSDL file
provided by the CEA feature pack. The application registers with the IP-PBX to be notified of
incoming calls using the Web service client. When calls are received, the IP-PBX notifies the
communication service, which sends a notification to the listener that was registered with the
initial Web service call by the business application. The business application receives the
notification in its listener, and increments a counter. The data that the application gathers in its
counter is logged and stored, to be used in a report that is generated at the end of the
business day.
1.2 Communication services provided by the feature pack
These scenarios are made possible through the telephony access and multimodal Web
interaction features provided by the CEA feature pack.
1.2.1 Telephony access
Telephony access allows you to incorporate telephony services in business applications,
including making phone calls, receiving phone calls, and receiving call notifications within the
Web application.
1.2.2 Multimodal Web interaction
Multimodal Web interaction allows you to provide session linking (shared sessions) between
users browsing the same Web site from different locations. With session linking, users can
interact dynamically in collaborative ways, such as co-browsing or co-shopping Web
sessions. With a combination of click-to-call functionality and multimodal interaction, you can
support two-way synchronized text forms between the user and a customer service
representative (CSR). For example, a human resources representative can help an employee
with the selection of health benefits.
The CEA feature pack is based on SIP-enabled services that use Representational State
Transfer (REST) servlets and Web services in a converged HTTP and SIP application. The
feature pack includes a library of Dojo-style widgets for use in Web applications. Dojo widgets
are prepackaged components of JavaScript and HTML code that add interactive features that
work across platforms and browsers. CEA widgets are extensible, allowing developers to
customize them to handle more advanced tasks.
1.3 Interfaces to the communications services
The CEA feature pack provides several methods of integrating communications services into
your applications. The following sections outline the capabilities provided by each method,
and considerations for selecting which method to use.
4
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
1.3.1 Widgets
The CEA feature pack includes a library of Dojo-style widgets for use in Web applications.
Dojo widgets are pre-packaged components of JavaScript and HTML code that add
interactive features that work across platforms and browsers. CEA widgets are extensible,
allowing developers to customize them to handle more advanced tasks. These widgets
provide capabilities like making and disconnecting calls and receiving incoming call
notifications. The CEA feature pack comes with three ready-to-integrate widgets, and two
extendable widgets. These widgets have been built using the Dojo toolkit, and are provided in
the CEA custom Dojo toolkit shipped with the feature pack.
򐂰 Making phone calls in Web applications
Users can enter their phone number and request a call back from your company.
򐂰 Receiving call notifications in Web applications
Users can enter their phone number and receive notifications of incoming calls.
򐂰 Collaborating and co-browsing in Web applications
Users can share the same browsing session, with one user controlling the session.
򐂰 Implementing two-way forms in Web applications
Create and configure two-way forms in Web applications.
1.3.2 Web services
The CEA feature pack allows developers to use Web services to integrate telephony services
into their applications simply and rapidly. Developers do not require expertise in
communications technologies and they can make use of the WebSphere Application Server
and Java™ skills they already have. Communications support can be added to existing
applications as well as new ones to take advantage of an SOA approach.
It is also possible to configure the CEA feature pack to use an external Web service provider
that supports the CEA Web service WSDL file. This allows vendors to customize interactions
with their IP/PBX (Internet Protocol/Private Branch Exchange). The external Web service
provider will then be responsible for all communication with the IP/PBX to provide third party
call control.
1.3.3 REST
The REST APIs can be used to:
򐂰 Access telephony services
You can integrate Web telephony into new and existing applications.
򐂰 Share data across two sessions
You can build co-browsing into applications, allowing two Web users to share the same
browsing session using side-by-side modal windows. One user controls the session. The
other user has no control, but can view the activity of the other user.
Chapter 1. IBM WebSphere Application Server Feature Pack for CEA 1.0
5
1.3.4 Selecting the interface to use
The interfaces in the CEA feature pack have uses based on need.
򐂰 The REST interface is meant for programmers trying to use the CEA features
programmatically. They usually have an existing user interface and do not need the user
interface provided by the widgets.
򐂰 The widgets provide an easy-to-use user interface that can be embedded into any Web
application to provide CEA-enabled features such as co-browsing, calling, and session
sharing with an already-provided user interface that can also be customized.
򐂰 The Web service interface is typically used by other business applications that can embed
a Web service client.
򐂰 The JSR 289 interface is for telephony applications that prefer to use the telephony APIs
to build communication applications.
1.4 SIP applications
The Session Initiation Protocol (SIP) application-layer protocol allows for the creation and
management of multimedia communication sessions between devices. A SIP session can be
used to exchange any media using any protocol. SIP provides the technology to support the
click-to-call function in this feature pack, and is also available for use in developing SIP-based
applications.
The SIP Servlet API provides the specification and interfaces for developing SIP applications.
WebSphere Application Server V7 supports SIP Servlet 1.0 (JSR 116). The CEA feature pack
supports SIP Servlet 1.1 standard (JSR 289), which adds additional features, including:
򐂰 Application routing
JSR 289 enables developers to build complex services out of smaller applications. On
initial requests the container calls the application router to determine which application to
invoke based on the type of request. The application router is the central hub for selecting
application order.
򐂰 Annotation-based programming
Annotations provide a fast way to develop applications by embedding metadata directly in
applications. For example, you can use the @SipServlet annotation to indicate that a class
is a SIP servlet. The @SipApplication is a package-level annotation. All servlets in the
package belong to the same application unless the servlet uses
@SipServlet(applicationName). For more information about Annotations, see section 18
of the JSR 289.
򐂰 Converged applications
JSR 289 provides a new, standardized mechanism for building converged applications. A
converged application contains SIP servlet components and other Java EE components,
like HTTP servlets and enterprise beans. The specification includes two new classes to
support convergence.
– ConvergedHttpSession is an extension to HttpSession for converged applications.
– SipSessionUtil handles session management for converged applications.
For more information about converged applications, see section 13 of the JSR 289.
6
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
򐂰 Back-to-back user agent (B2BUA) APIs
A B2BUA is a SIP element that acts as an endpoint for two or more dialogs. A B2BUA
forwards requests and responses between two dialogs in some fashion. Because
B2BUA's mediate signaling between two endpoints, they must be used carefully to ensure
they do not break the functionality. SIP 1.1 introduces a new B2BUA helper class that has
the ability to create a copy of an incoming request. It automatically maintains links
between sessions on both sides of the B2BUA. This new helper class can simplify the
B2BUA pattern for application developers and reduce the risk of introducing errors to the
dialog. For more information about B2BUAs, see section 12 of the JSR 289.
1.4.1 SIP application examples
Rational® Application Developer provides three examples that you can use as a learning
excercise:
򐂰 The Call Blocking sample checks a list to determine if the caller is valid. If the caller is not
valid, the call is blocked. If the caller is valid, the call is forwarded.
򐂰 The Call Forwarding sample checks to determine if the caller is in a forwarding list and
forwards the call.
򐂰 The Third Party Call Control sample demonstrates how to use the Converged capability by
implementing a controller that sets up and manages a communications relationship
between two parties.
1.5 (New) Feature Pack for CEA Version 1.0.0.1
Notable changes to Feature Pack for CEA Version 1.0 provided by Version 1.0.0.1 include
support for the following features:
򐂰 Clustering and failover support for CEA services on distributed platforms (Web
collaboration and telephony services)
򐂰 iWidget support
򐂰 Making Web collaboration URIs more secure with a nonce to prevent session snooping
򐂰 New Dojo level supported by the widgets
On z/OS® , features related to communications services (widgets, REST interface, Web
service interface) are limited to single server environments.
This paper has not been updated to address these new features.
Chapter 1. IBM WebSphere Application Server Feature Pack for CEA 1.0
7
8
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
2
Chapter 2.
Enabling applications for
communications
This section provides a summary of the steps required to add communications features to
applications.
© Copyright IBM Corp. 2010. All rights reserved.
9
2.1 Components
There are basic components in every implementation:
򐂰
򐂰
򐂰
򐂰
The IP PBX
The application server with the CEA feature pack installed
The business application
The user interface of the business application
These components are discussed in the following sections.
2.1.1 The IP PBX
An IP PBX is a business telephone system designed to deliver voice over a data network and
inter-operate with the Public Switched Telephone Network (PSTN). For the purposes of this
discussion we will assume you have an IP PBX that is installed and running. However, note
that the CEA feature pack provides a sample application that can be deployed to the
application server to emulate a PBX for development purposes. You must provide softphones
for use the PBX emulator application.
2.1.2 The application server with the CEA feature pack installed
This is a WebSphere Application Server application server that runs the communications
services and the business application that is enabled for communications.
Clustering and failover support
򐂰 V1.0
In the CEA feature pack V1.0, clustering is only supported for the JSR 289 feature.
Features related to communications services (widgets, REST interface, Web Service
interface) are limited to single server environments.
򐂰 V1.0.0.1
The CEA feature pack V1.0.0.1 adds clustering and failover support for CEA Web
collaboration and telephony services on distributed platforms. On z/OS, features related
to communications services (widgets, REST interface, Web Service interface) are
limited to single server environments.
2.1.3 The business application
The business application uses one of the CEA APIs to implement telephony or Web
collaboration features.
2.1.4 The user interface of the business application
The business application must expose an interface to the user. If the CEA feature pack
widgets are embedded in the business application, then the user interface is a Web browser
interface exposed to the user.
10
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
2.2 Summary of implementation steps
These steps are a summary only, intended to illustrate how the CEA feature pack is used and
implemented. For information about installing the application server and configuring it for
communications, see the information center:
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.ceaf
ep.multiplatform.doc/info/ae/ae/welcome_fepcea.html
2.2.1 Install the IP PBX or PBX emulator application
Install and implement the PBX. Note that the Feature Pack provides a sample application that
emulate a PBX for light testing. These can be used during development as an alternative to
connecting to a real PBX. For information about using the PBX emulator, see the following
Web page:
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.ceaf
ep.multiplatform.doc/info/ae/ae/tcea_cea_getstart_step3.html
2.2.2 Installing and configuring the application server
The following instructions were tested by the wiki team to install the CEA feature pack V1.0 in
our lab.
1. Install WebSphere Application Server 7.0.0.5 (or later).
2. Download the CEA feature pack. Instructions and the link for downloading the feature pack
can be found at the following Web page:
http://www-01.ibm.com/software/webservers/appserv/was/featurepacks/cea/instopt/
index.html
3. Install the CEA feature pack using the Installation Manager. Installation instructions can be
found in the CEA feature pack Information Center at the following Web page:
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.c
eafep.multiplatform.doc/info/welcome_nd.html
Chapter 2. Enabling applications for communications
11
4. Create a new standalone application server with the CEA feature pack capabilities
(Figure 2-1) or augment an existing application server profile to add the CEA capabilities.
Figure 2-1 New profile environment selection for a server with CEA feature pack capabilities
5. Start the application server.
6. Use the administrative console to enable the communications service (See Figure 2-2).
You will find the setting by selecting Servers  Server Types  WebSphere
Application Servers  server_name  Communications Enabled Applications
(CEA). If you do not see this selection in the Communications section of the application
server configuration page, your profile has not been augmented or created to support the
CEA feature pack.
Figure 2-2 Enabling the CEA services
7. (Optional) Install the PBX sample application to emulate the PBX.
8. If you are using the Web services client interface, use the CEA_WSN_JAXWS_Setup.py
script to set up the WS-Notification Infrastructure in the base application server. The script
creates a Service Integration Bus, creates a WS-Notification service, creates a service
point associated with the previously-created service, and starts the deployed service point
enterprise application.
9. Configure the PBX location.
12
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
The instructions for installing the CEA feature pack are similar if you are installing it on a
WebSphere Application Server V7.0.0.5 test environment in Rational Application Developer.
2.2.3 Incorporate the features into the business application
The steps required to incorporate the communications or collaboration features into the
application are similar, but the actions you take are specific to the API you decide to use.
Using widgets
If you are using widgets in your application, perform the following steps:
1. Copy the CEA widgets from the Dojo Toolkit into the WebContent directory of your
application. The Dojo Toolkit is installed with the CEA feature pack at app_server_root
/feature_packs/cea/javascript. Copy the ceadojo directory.
2. Embed the widgets into the HTML Web page:
– To make a call: ClickToCall widget
– To receive notification of a call: CallNotification widget
– To collaborate: Cobrowse widget
– To implement 2-way forms: TwoWayForm widget ( + ClickToCall and CallNotification, or
Cobrowse). (also requires the Dojo JavaScript and Dijit form widget libraries)
3. Deploy and start the application
Using a Web services client
If you will be using a Web services client, perform the following steps:
1. Get the WSDL file for the communications service from the application server
2. Update the application to call the Web services interface:
To make a call use CommWsRequest (openSession, makeCall, endCall, closeSession)
3. Deploy and start the application.
Using the REST API
If you are using the REST API, perform the following steps:
1. Incorporate the REST API calls in the HTML Web page, using one of two formats: XML or
JSON
–
–
–
–
To collaborate: PUT,GET, DELETE /collaborationSession
To retrieve an event (call or collaborations status, collaboration data): GET /event
To make a call: PUT,GET, DELETE /call
To receive notification of a call: PUT,GET, DELETE /callNotification
2. Deploy and start the application.
Chapter 2. Enabling applications for communications
13
2.3 Installation tips
The team ran into a few issues when installing the WebSphere Application Server feature
packs. The issues were primarily due to misunderstandings dealing with the use of the
Installation Manager. We put these quick steps together to outline an installation process that
works.
2.3.1 On development machines
Applications for WebSphere are created using Rational Application Developer, which comes
with a test environment for WebSphere Application Server. When you develop applications in
Rational Application Developer, you can deploy them to the test environment, which is a fully
functional WebSphere Application Server that has been integrated into the workspace with a
nice interface for developers.
The feature packs can be installed on the test environment as well as to a stand-alone
WebSphere Application Server environment.
1. Install Rational Application Developer. The installation can be started by executing
launchpad.exe in the RAD_SETUP directory. The first thing that happens is that the
Installation Manager will install.
2. Respond to the series of screens to complete this installation. If you already have the
Installation Manager, the install wizard will check for updates and you will be asked to
update to the latest release. When it is done, you will have to restart the Installation
Manager.
3. When the Installation Manager starts, click Install.
4. Select Rational Application Developer 7.5.4 and WebSphere Application Server test
env 7.0 to install. Complete the installation following the wizard panels.
Notes:
򐂰 Take the defaults for the packages to install at this time. Do not install the feature
packs to the test environment on this round. You will need to go back through the
update process to bring the test environment up to WebSphere Application Server
7.0.0.7 before installing them. Installing them now gives you a lower level than what
is current.
򐂰 Clear the option to create a profile. Creating a profile at this stage will give you an
application server that is not augmented for the feature packs.
򐂰 Delay the installation for any additional tools that you think might be needed for the
feature packs. You will need to update to 7.5.5 first. If you find that you are missing
something later, you can always go back through the installation process and install
them.
5. After the install, go through the update process from the Installation Manager. You need to
be updated to the latest level of Installation Manager first.
6. Go through the update option again to update to Rational Application Developer 7.5.5 and
WebSphere Application Server 7.0.0.7. When you update the WebSphere Application
Server test environment to 7.0.0.7, you will have the option to install the features packs.
Allow the update process to also create an application server profile.
If the Installation Manager does not find the WebSphere Application Server or Feature
Pack updates when it scans for available updates, be sure that you have the following
repositories defined to the Installation Manager. (File  Preferences  Repositories).
14
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
When you add each repository, you will be asked to provide an IBM user name and
password. Make sure that you also look for firewall blocking from your system and allow
the Installation Manager to access the Web.
http://public.dhe.ibm.com/software/websphere/repositories/repository.config
https://www.ibm.com/software/rational/repositorymanager/repositories/websphere/
repository.config
Note: If you have WebSphere Application Server 7.0.0.7 installed and did not install the
feature packs, use the Modify option to install the feature packs (versus the Update
option).
2.3.2 On development machines with WebSphere Application Server
On systems where you plan to have both Rational Application Developer, with or without the
WebSphere Application Server test environment and you plan to install WebSphere
Application Server, the primary consideration is how to manage the use of the Installation
Manager. The following is an outline of the steps to take.
1. Install Rational Application Developer. This will also install the Installation Manager.
2. Use the Installation Manager Update option to update both the Installation Manager to
1.3.3 (it will automatically detect an update is needed), and update Rational Application
Developer to 7.5.5.
3. Install WebSphere Application Server using the launchpad. Note that this is the traditional
method. You will not use the Installation Manager to install it.
4. Download the latest fixes for WebSphere Application Server and the JDK (7.0.0.7
currently) and the latest Update Installer from the support site:
http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27004980#ver70
5. Install the WebSphere Application Server Update Installer.
6. Install both WebSphere Application Server and the JDK fixpacks using the Update
Installer.
7. Open the Installation Manager and import the WebSphere Application Server installation.
8. Update the Installation Manager repositories to include the WebSphere repository. With
both Rational Application Developer and WebSphere Application Server in the Installation
Manager, you have the following Installation Manager repositories. (File 
Preferences  Repositories.)
Accessing these repositories requires an IBM login. You will be prompted for this the first
time you attempt to access them.
http://public.dhe.ibm.com/software/websphere/repositories/repository.config
https://www.ibm.com/software/rational/repositorymanager/repositories/websphere/
repository.config
9. Use the Installation Manager Install option to install the feature packs.
Chapter 2. Enabling applications for communications
15
2.3.3 On WebSphere Application Server machines (no Rational Application
Developer installed)
Follow these steps to install the feature pack on a system with WebSphere Application
Server.
1. Install WebSphere Application Server using the launchpad. Note that this is the traditional
method. You will not use the Installation Manager to install it.
2. Download the latest fix packs for WebSphere Application Server and JDK (7.0.0.7
currently) and the latest Update Installer from the support site.
http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27004980#ver70
3. Install the WebSphere Application Server Update Installer.
4. Install both WebSphere Application Server and the JDK fix packs using the Update
Installer.
5. Download the Installation Manager for WebSphere and install it.
http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg24023498
6. Open the Installation Manager and import the WebSphere Application Server installation.
7. Update the Installation Manager repositories to include the WebSphere repository. (File 
Preferences  Repositories.)
Accessing these repositories requires an IBM login. You will be prompted for this the first
time you attempt to access them.
http://public.dhe.ibm.com/software/websphere/repositories/repository.config
8. Use the Install option in the Installation Manager to install the feature packs.
The Installation Manager is used to add feature packs to WebSphere. Installation of
maintenance will continue to be done using the Update Installer.
16
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
3
Chapter 3.
CEA feature pack architecture
The goal of the CEA feature pack is to provide a fast path to integrate communications
support into Web and enterprise applications. It provides an easy-to-use interface for
programmers to integrate telephony into their applications with no prior knowledge of
communications technology or the Session Initiation Protocol (SIP). The CEA feature pack
makes it simple for a developer with Java skills to use standard interfaces to embed
communication services directly into an application.
The standard interfaces include Java API for XML Web Services (JAX-WS) and widgets
created using the Dojo toolkit. The interfaces provided with the feature pack provide:
򐂰 Simplification in terms of making and monitoring calls from enterprise and Web-based
applications
򐂰 Support for new forms of communication such as sharing session data through a
co-browsing link. Co-browsing allows two participants to see the same content in their
browsers.
򐂰 Communication services that can be integrated into existing applications and
communication infrastructure.
The function provided by the CEA feature pack is based on SIP-enabled services. The feature
pack provides support for the JSR 289 specification, SIP servlet 1.1.
© Copyright IBM Corp. 2010. All rights reserved.
17
3.1 Architectural overview
Figure 3-1 illustrates the basic architecture of the CEA feature pack and how it fits into the
WebSphere Application Server infrastructure.
Enterprise
Application
Web
Application
SIP
Application
CEA Web
Service
Call
CEA dojo
Widgets
SIP
Servlet 1.1
CEA Web
Service
CEA REST
Interface
SIP
Servlet
Container
JSR 289
IP-PBX
SIP CTI Library
CEA System Application (commsvc)
WEB SERVICE
CONTAINER
WebSphere Application Server
Figure 3-1 CEA Feature Pack architectural overview
The diagram shows the functionality added by the CEA feature pack. It illustrates how the
business applications (in green) interact with the services provided by the feature pack (in
blue). The CEA feature pack runtime code executes as a system application on the
application server. Similar to the administrative console, the commsvc system application is
not exposed through the administrative console, but you can see messages in the system log
related to it. Typically, there are two types of applications that you might run on top of this
feature pack:
򐂰 SIP-based communications applications that directly implement communications functions
򐂰 Business applications that access communication functions through APIs provided by the
feature pack.
In Figure 3-1, both the enterprise application and the Web application are considered types of
business applications. Business applications communicate to devices outside of the
application server through the SIP computer telephony integration (CTI) layer. This layer
accesses an IP-PBX through a standard ECMA TR/87 gateway.
The CEA feature pack provides three main services that provide a unique communication
mechanism to Web users and programmers. These are:
򐂰 Telephony Access Services
򐂰 Multimodal Web collaboration
򐂰 Session Initiation Protocol (SIP) support
18
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
3.2 Telephony Access Services
The telephony services of the CEA feature pack allow access to a communications
environment from within business applications. The feature pack provides the following
functionality in terms of telephony:
򐂰 Widgets that can be used to integrate call control into your applications, such as making
and disconnecting a call, and call notifications for incoming calls
򐂰 A platform for more complex communications applications using the REST or JAX-WS
Web service interfaces
򐂰 The ability to proxy to external Web service implementations to interact with the PBX
򐂰 Base services using Computer Supported Telecommunications Applications (CSTA)/SIP
(TR/87)
Telephony access services are designed to integrate with existing communications
infrastructure by communicating using standard protocols, like the ECMA TR/87 protocol.
3.2.1 Request flow: Making a call
Figure 3-2 provides insight into how the telephony service provided with CEA works. This
example illustrates the scenario of establishing a call between a caller (for example a
customer) and the callee (for example, a CSR) using the CEA telephony interface.
Web Application
ClicktoCall Widget
1
2
CEA REST
Interface
SIP CTI
Layer
Application Server
3
4
Caller
IP PBX
5
Callee
Figure 3-2 Making a call flow
Chapter 3. CEA feature pack architecture
19
Figure 3-2 on page 19 illustrates the following process:
1. A user (for example, a customer visiting a company's Web site) enters a telephone
number into the ClickToCall widget on the company's Web page. Entering the phone
number and clicking a button provided by the widget intitiates a request to be connected
over a telephone link to someone at the company (a customer service representative, for
example). An HTTP REST request is generated and sent to the application server.
2. The application server processes and interprets the request to determine the next action.
3. The application server takes the information about the requested call and sends it out to
the IP PBX through the standard SIP CTI layer in the server.
4. The IP PBX receives the request and sets up a call from the caller to the callee.
5. A call is established between the two parties.
3.2.2 Programming interfaces
The CEA feature pack provides telephony access through the following programming
interfaces:
򐂰 Web services client
򐂰 Widgets
򐂰 Representation State Transfer (REST) API
3.2.3 Using an external Web service provider to interact with the PBX
The core technology in the CEA feature pack that interacts with the IP PBX to monitor and
control phones can be substituted with an external Web service. The external Web service
provider must support the services defined by the WSDL file for the core technology Web
service.
3.3 Multimodal Web collaboration
The CEA feature pack brings a new mode of Web collaboration to the users of business
applications. The mode of communication can be called multimodal Web collaboration due to
its ability to allow linking (sharing) sessions between users browsing the same Web site from
different locations.
With session linking, Web users can interact dynamically in collaborative ways, such as
co-browsing or co-shopping, while maintaining their individual unique sessions within the
server. Commerce Web sites might find co-browsing especially useful to provide customer
support, when protecting information on the internal site. Commerce sites can also use the
collaborative shopping experience to attract more customers to their sites.
When used in conjunction with the click-to-call functionality, a shared session can be used to
allow a customer and a customer service representative to fill out an online form together at
the same time. This allows the customer to do things like verify name spelling and contact
information and to take over control of the form and provide sensitive information (like an
identification number or credit card information) in a masked field that the customer service
representative cannot see.
20
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
3.3.1 Request flow: multimodal collaboration using the Collaboration widget
As an example of how Web collaboration works, consider the architectural flow shown in
Figure 3-3.
WebPage – User A
12
4
Widget
11
1
WebPage – User B
8
Widget
3
7
5
CEA System
Application
6
9
Container
2
User
Registry
6
User A's
Session
10
User B's
Session
Figure 3-3 Web collaboration flow
In this scenario, user A is browsing a Web page, and wants to ask user B for help in finding
and evaluating products that she's considering for purchase. Because this Web page includes
the Collaboration widget, the flow is as follows:
1. User A clicks on the widget to indicate that she wants to begin a shared session with user
B. This request is sent to the application server and intercepted by the converged
Web/SIP container.
2. The container hands off the request to the CEA system application. The CEA system
application has an internal user registry into which user A is registered. The interface to
the user registry is based on SIP, so the the CEA system application makes use of the SIP
container to do this registration. Session data is established for user A and the session
location is placed in the registry.
3. The server responds to user A, providing a URI that she can use to collaborate with user
B.
4. User A provides this URI to user B so that they can collaborate and view the same session
information at the same time. User A contacts user B using e-mail or instant messaging or
another mechanism to send the URI.
5. User B receives the collaboration URI and loads it into his browser. This generates a
REST request to the CEA system application telling it that user B is trying to start a shared
collaboration session with user A.
Chapter 3. CEA feature pack architecture
21
6. The container calls the CEA system application, which adds user B to the internal user
registry, establishes user B's session data, and looks up user A in the user registry. A link
is established between user A's and user B's session data. This is done with a SIP
connection between between the sessions.
7. User B receives a REST response back from the server which includes the send and fetch
URIs that are used to exchange data with user A. At that point, modal windows are
activated in both of user A's and uUser B's Collaboration widgets and the multi-modal Web
collaboration session is on-going.
8. User B highlights text, scrolls, and performs other actions.
9. User B's widget sends these events back to the application server on the send URI for
collaboration with user A.
10.The CEA application sends the data across to user A's linked session.
11.Throughout this process, user A's widget is polling for events coming in on the fetch URI.
12.When the polling discovers a new event, user A's widget gets updated with the new
events, such as seeing the text User B has highlighted.
13.The polling and updating in steps 11 and 12 continue throughout the collaboration
session.
3.3.2 Programming interfaces
The CEA feature pack provides multimodal Web interaction through the following
programming interfaces:
򐂰 Widgets
򐂰 REST API
3.4 Session Initiation Protocol (SIP) support
SIP is used to establish sessions among various multimedia applications. SIP is a request
response protocol that closely resembles two other internet protocols, HTTP and SMTP
(Simple Mail Transfer Protocol). A SIP session can be two-way telephone call or collaborative
multi-media conference session. SIP is an RFC standard (RFC 3261) from Internet
Engineering Task Force (IETF). The first proposed standard version (SIP 2.0) was defined by
RFC 2543. The SIP Servlet API defines the standards for delivering SIP-based services. The
CEA feature pack supports the JSR 289 specification, which defines version 1.1 of the SIP
Servlet API. JSR 289 requires support for SIP as defined in RFC 3261.
򐂰 JSR 289: SIP Servlet 1.1 can be found at the following Web page:
http://jcp.org/en/jsr/detail?id=289&nbsp
򐂰 RFC 3261 can be found at the following Web page:
http://www.ietf.org/rfc/rfc3261.txt
Work for JSR 289 began in 2006 with more than 100 requirements. The requirements were
consolidated to following goals:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
22
SIP signaling
Simplicity
Converged applications
Third party application development
Application composition
Carrier grade
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
For more information, see the JSR specification at the following Web page:
http://jcp.org/en/jsr/detail?id=289
3.4.1 SIP servlets
A SIP servlet is a Java-based application component that is managed by a SIP container and
that performs SIP life cycle management and signaling. Similar to HTTP requests, SIP
requests are operation requests such as the following:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
doInvite
doAck
doOptions
doBye
doCancel
doRegister
doPrack
doSubscribe
doNotify
doMessage
doInfo
doUpdate
doRefer
doPublish
Also similar to HTTP responses, SIP servlet responses include:
򐂰
򐂰
򐂰
򐂰
doProvisionalResponse
doSuccessResponse
doRedirectResponse
doErrorResponse responses
3.4.2 SIP runtime components
Figure 3-4 illustrates the components involved in the SIP architecture.
User
Agent
SIP
Proxy
Internet
Soft
Phone
SIP
Server
PBX
Gateway
Directory
Server
PSTN
PSTN
Phone
Figure 3-4 SIP archtecture
Chapter 3. CEA feature pack architecture
23
SIP user agent
The user agent has a client element, called the User Agent Client (UAC), and a server
element, called the User Agent Server (UAS). The client element initiates the calls and the
server element answers the calls, allowing peer-to-peer calls to be made using a client-server
protocol.
SIP user agents are either lightweight clients suitable for embedding in devices such as
mobile handsets or PDAs or IP phones. Alternatively, they can be applications that are
installed on desktops that bind with other software applications, such as contact managers.
SIP servers
An application server in WebSphere has a SIP container. When a SIP application is installed
to the server, the application server starts to listen to SIP traffic. For the purposes of this
discussion, we refer to a WebSphere application server with a SIP application deployed to it
as a SIP server.
The main function of a SIP server is to provide name resolution and user location (because
the caller is unlikely to know the IP address or host name of the called party) and to pass on
messages to other servers using next-hop routing protocols. Other functions fulfilled by the
SIP servers are re-direct and forking activities.
򐂰 A re-direct is receiving calls, and rather than passing these onto the next server, sends a
response to the caller indicating the address for the called user.
򐂰 Forking is the ability to split (or fork) an incoming call such that several locations can ring
at once and the first location to answer takes the call.
SIP servers can operate in two different modes:
򐂰 Stateful
A SIP server in a stateful mode remembers the incoming requests it receives, and
processes responses based on it.
򐂰 Stateless
A SIP server in a stateless mode forgets all the information about a request after the
request has been sent. These stateless servers are likely to be the backbone of the SIP
infrastructure while stateful-mode servers are likely to be the local devices close to the
user agents, controlling domains of users.
Together, these components make up a basic SIP infrastructure. Application servers (and
applications) can sit above these components delivering SIP services to users. Application
servers host service modules such as instant messaging and and presence (user status such
as "Active," "Away," or "Do not disturb."), third party call control and user profiling. They also
interact with other media servers and can be responsible for load balancing across a
distributed architecture. These servers also typically contain the management interface.
Custom services can be created by accessing subroutines in the application servers using
Application Program Interfaces (APIs). When service modules are used in combination the
service possibilities are vast.
SIP proxy
The SIP proxy server is used to route requests to a cluster of SIP application servers,
providing load balancing and high availability. WebSphere Application Server provides both
an HTTP and SIP proxy server that are designed to run together. The SIP proxy is capable of
securing the transport using secure sockets layer (SSL), and securing the content using
various authentication and authorization schemes.The SIP proxy is also responsible for
24
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
establishing outbound connections to remote domains on behalf of the back-end SIP
containers and clients that reside within the domain that is hosted by the proxy. The SIP proxy
has the capability to protect the identity of the back-end SIP containers from the SIP clients.
SIP containers
The SIP container (sometimes referred to as the SIP servlet container) is a part of a SIP
server that provides the network services over which requests and responses are received
and sent. It decides which applications to invoke and in what order. A SIP container also
contains and manages SIP servlets through their life cycle. The SIP container services
include:
򐂰 Management of network listen points
򐂰 SIP messages and transaction processing
򐂰 Handling of headers
Chapter 3. CEA feature pack architecture
25
26
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
4
Chapter 4.
REST interface
The communication services in the CEA feature pack can be accessed using HTTP requests
sent to the REST interface. This section will provide a brief overview of the REST interface.
© Copyright IBM Corp. 2010. All rights reserved.
27
4.1 REST interface
Calls to the REST interface are similar to standard HTTP requests, except that they have a
specific format that is recognized by the REST interface implementation. The communication
service has a servlet that is constantly listening for requests. The servlet parses each
incoming request and returns a response to it in either JSON or XML format. The format of
the request is determined by a URL parameter sent in the request called JSON. If present, the
REST response is sent using JSON. Otherwise, the REST response is sent in XML format.
The REST APIs allow you to perform the following operations:
򐂰
򐂰
򐂰
򐂰
Make a call
End a call in progress
Gather information about a call.
Get call notification
There are also REST requests available to handle actions related to Web collaboration, which
are used by the cobrowse and collaboration dialog widgets. The REST requests available to
be used for Web collaboration actions include calls to enable a collaboration, get collaboration
status, and start a cobrowsing session with a peer URI. You can also use these to end a
collaboration session, and to send and receive data to and from the peer in a cobrowsing
session.
4.2 Rest HTTP requests
REST requests to the communication service interface come in as simple HTTP requests.
The URL of the request defines the REST call that is being made to the communication
service, and information needed by the service to process the request is included as JSON or
XML data.
An example of a REST request that is made to the communication service is a call from the
ClickToCall widget. The ClickToCall widget allows users of a Web site to input their telephone
number into an entry field, and select a button that says "Call me". When a user inputs their
telephone number into the entry field and presses the Call me button, the ClickToCall widget
assembles a REST request and sends it to the REST interface on the communication service.
The REST request indicates that a call is to be established to the telephone number provided.
The communication service extracts the information and establishes a call between that
number and a customer service representative (CSR). The telephone on the other end will
ring and the user is connected to a CSR.
4.3 Call flow example
Figure 4-1 on page 29 shows a simple flow describing the implementation steps that take
place in order to establish a call using an HTTP REST request. This explanation assumes
familiarity with SIP. If you are not familiar with how SIP works, see Chapter 8, “Working with
SIP applications” on page 73.
28
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Browser
1
Container
CEA System
Application
2
3
IP/PBX
UAC
4,5
UAS
Figure 4-1 Making a call using REST
Figure 4-1 describes the following process:
1. The browser sends the HTTP REST request.
2. The Web container calls the commsvc system application as follows:
a. The system application has a servlet which interprets the REST request.
b. The servlet calls the SIP computer telephony integration (CTI) layer of the system
application.
3. The system application sends the SIP flow to the IP PBX as follows:
a. The system application contacts IP PBX through SIP
b. The system application sends a call request to IP PBX
4. The IP PBX tells the user agent client (UAC) to call the user agent server (UAS).
5. The call is established between the UAC and UAS.
4.4 Implementation
When a REST request is made by the ClickToCall widget to establish a call, the request is an
HTTP PUT request that is sent to the communication service REST servlet.
The URL portion sent to the servlet looks like the following example:
PUT http://localhost:9080/commsvc.rest/CommServlet/call?JSON=true
The CommServlet portion of the URL is followed by the request type (for example, call) and
then JSON=true. In this example, call indicates to the communication service that a request
to establish a call is being made. The JSON=true parameter indicates that the body of the
response from the service will contain information about the request in JSON format.
Example 4-1 shows what a JSON body looks like.
Example 4-1 JSON body
{addressOfRecord:"sip:Customer@localhost",peerAddressOfRecord:"sip:CSR@localhost",
enableCollaboration:"true"}
Chapter 4. REST interface
29
As you can see, the JSON body includes the two telephone numbers that should be
connected. Both the customer's telephone number (addressOfRecord) and the CSR's
telephone number (peerAddressOfRecord) are in SIP format. When the call is attempted, a
response is returned to the application (ClickToCall widget) that a call has been attempted.
A sample REST API response is provided in Example 4-2.
Example 4-2 PUT request receives a JSON response
{ "success": true, "infoMsg": "Call attempted between sip:Customer@localhost and
sip:CSR@localhost.",
"collaborationId": "tgtr00bERd_ik5IyU6x4DtU",
"callerAddressOfRecord": "sip:Customer@localhost",
"calleeAddressOfRecord": "sip:Customer@localhost",
"callServiceUri": "CommServlet/call;ibmappid=local.1235055868375_170",
"collaborationStatus": "ESTABLISHED",
"collaborationServiceUri":
"CommServlet/collaborationSession;ibmappid=local.1235055868375_170",
"forPeerCollaborationUri":
"CommServlet/collaborationSession?addressOfRecord=tgtr00bERd_ik5IyU6x4DtU",
"eventUri": "CommServlet/event;ibmappid=local.1235055868375_170"}
The response can be parsed and the information used programmatically to continue with the
application processing of the communications-enabled application. In the first two lines of the
JSON response, you can see that a call has been attempted to be established between the
customer and the CSR. A collaboration ID has been generated to identify the collaboration.
The service can then be polled to see if the status of the call has changed to make sure the
call was established.
The CEA feature pack information center has a lot of information regarding building
applications to use the REST APIs, including examples and sample JavaScript code that can
be used to help build REST requests. An example of a complete HTML page with a call to the
REST interface is provided in the following Web page:
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/index.jsp?topic=/com.ibm.webs
phere.ceafep.multiplatform.doc/info/ae/ae/tcea_manage_calls_rest_step5.html
In short, it is important to remember that the REST interface of the CEA feature pack can be
accessed using XML or JSON, and it can be embedded in regular JavaScript or HTML.
30
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
5
Chapter 5.
Using widgets for telephony and
Web collaboration
The CEA feature pack provides various means for Web collaboration. One major feature is
the widgets and widget framework that help integrate telephony components into a Web page
seamlessly and quickly. The widgets interact with an IP PBX to establish telephone calls,
monitor incoming telephone calls, and establish a shared Web browsing session between two
parties. The widgets interact with the communication services, which then work with the
application server to pass data to the communications network. Only the widgets that perform
telephony-related activities will pass data to the public switch telephone network (PSTN) to
handle telephone-related activities.
The feature pack comes with three ready-to-integrate widgets and two extendable widgets.
The widgets were built using the Dojo toolkit and are provided in a custom CEA Dojo toolkit
that is shipped with the feature pack.
The widgets can be embedded into any Web page by adding a JavaScript reference to the
CEA Dojo toolkit and adding the tag definitions to the HTML files. The widgets communicate
with the back-end service using representational state transfer (REST) APIs. When using
REST, HTTP requests are sent to the waiting service in a format that the service is expecting.
Information is extracted from the request to perform operations, and information is passed
back to the widgets from the service in JSON or XML format.
The CEA feature pack includes both ready-to-integrate widgets and extendable widgets:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
CollaborationDialog widget
CollaborationDataTransfer Widget
ClickToCall Widget
CallNotification widget
Cobrowse widget
TwoWayForm widget
The TwoWayForm widget is not discussed in this publication. For more information, see
the following Web page:
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.c
eafep.multiplatform.doc/info/ae/ae/tcea_create_two_way_forms.html
© Copyright IBM Corp. 2010. All rights reserved.
31
Lastly, we will discuss scenarios where we need to combine widgets together in a typical Web
application.
Some design scenarios in this case can be:
򐂰 To integrate click-to-call:
On the Web pages customers access, add the ClickToCall widget.
򐂰 To integrate click-to-call with contact center co-browsing:
– On the Web pages customers access, add the ClickToCall widget.
– On the Web page for the Customer Service Representative, incorporate the
CallNotification widget.
򐂰 To integrate peer-to-peer co-browsing:
– Incorporate the cobrowse widget on every Web page that a co-browse session can be
initiated from. When the cobrowse session is established, you also have the
collaboration capability.
– If the cobrowsing might require files to be passed back and forth, add the
CollaborationDataTransfer widget into the same application to enable data transfer
when cobrowsing.
5.1 CollaborationDialog widget
The CollaborationDialog widget cannot be placed directly on a Web page. Rather, it is
extended and launched by the ClickToCall, CallNotification, and Cobrowse widgets to provide
the modal windows that display the Web pages in a cobrowsing session.
When two users initiate a cobrowse session, a new window is opened in each browser where
both users see the same Web pages. Features of a cobrowsing session using the
CollaborationDialog widget include:
򐂰 One user in the session can drive the Web navigation.
򐂰 Both users can highlight information on a Web page for the other user to see.
򐂰 Two-way forms allow both users to enter information into a form. For more information
about two-way forms, see the following Web page:
http://ibmcea.blogspot.com/2009/08/creating-basic-two-way-form.html
When embedded into a Web page, the widget has a standard interface with a set of default
buttons. These can be customized to suit the needs of a particular application.
5.1.1 Using the widget
The CollaborationDialog widget is available to users that are in a cobrowsing session. When
two users connect in a cobrowsing session, the CollaborationDialog widget becomes active in
their Web pages and modal windows are opened for the cobrowsing session.
In Figure 5-1 on page 33, the window on the left is the view that user A sees. The window on
the right is the view user B sees. The modal window is the prominent window, with the original
Web page and CollaborationDialog widget behind it. At any given time, one user in the
session is driving the session and the other can only view. The initiating user is in control of
the session until control is granted to the peer session.
32
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Figure 5-1 Collaboration view
The modal window has a number of buttons that can be used during a collaboration session.
Buttons are provided to browse back, forward, and refresh the page being displayed in the
collaboration dialog widget, similar to the navigation buttons in a Web browser.
Buttons to the right of the URL entry box (Figure 5-2) control how the collaboration session
Web page information is shared.
Figure 5-2 Buttons for collaboration
򐂰 The Send Page button allows the user driving the session to send the current page they
are viewing in the collaboration dialog widget to the peer's collaboration dialog widget.
򐂰 The Follow Me button enables follow me mode. In this mode, actions that the driving user
performs are displayed to the peer. For example, if the initiating user has the follow me
mode enabled and clicks on a link in the Web page in their dialog widget, the peer's
collaboration dialog widget will "follow' them along to the new page that is displayed after
the link is clicked.
򐂰 The Grant Control button grants access to the peer to drive the shared Web session.
Until the user that initiated the cobrowsing session, the peer cannot interact with the Web
content displayed in their collaboration dialog widget. The peer can only view what the
initiating user is browsing.
򐂰 The Highlight button allows you to highlight text in the shared Web page, to emphasize
portions of the page for the peer.
Chapter 5. Using widgets for telephony and Web collaboration
33
The bottom of the collaboration dialog widget has the following icons that indicate the status
of the session:
򐂰 The Connected icon (Figure 5-3) indicates that your collaboration session is connected to
WebSphere Application Server and is sharing a collaboration session.
Figure 5-3 Connected icon
򐂰 The Peer Window is Open icon (Figure 5-4) indicates that the peer sharing in the Web
collaboration has their collaboration dialog window open and is sharing the session data.
Figure 5-4 Peer Window is Open icon
򐂰 The Controlling Navigation icon (Figure 5-5) indicates that this user is controlling the
content of the collaboration session. If the initiator of the collaboration session wants the
peer sharing the collaboration to control the navigation of the Web content, they can grant
the peer that control by pressing the icon with the Grant Control button.
Figure 5-5 Controlling Navigation icon
5.2 CollaborationDataTransfer Widget
The CollaborationDataTransfer widget is used by the CollaborationDialog widget. It creates
the collaboration session used to share Web data between the two parties in a cobrowsing
session, and allows peers to join the session. This widget handles the task of passing data
behind the scenes for the CollaborationDialog widget, ClickToCall, and CallNotification
widgets.
The CollaborationDataTransfer widget is used by the other widgets, but is not seen because it
has no graphical component. It can also be extended and used to pass data in the
background of application activities.
5.3 ClickToCall Widget
The ClickToCall widget is a telephony widget that can be embedded into a Web page to
initiate calls. It allows a user to enter their telephone number into an entry box, and be
connected to another user automatically through a phone line. When a user of a Web page
needs to be connected to another user, they can click the Call Me button on the ClickoCall
widget, and the telephone for user B will ring. The two lines are connected through the
ClickToCall widget after the phone is answered at the other end.
The ClickToCall widget also allows a user that is listening in on a call to end the call, or to start
a cobrowsing session with the user they are talking to by pressing the Cobrowse button. In
addition, it displays messages notifying the users if a call has been connected or
disconnected.
34
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
5.3.1 Click-to-call example
The following steps are an example scenario of someone using the click to call feature on a
Web page.
1. A customer is browsing a Web site for a hardware store. They are looking for a good drill to
buy, but they need more information about a drill that is not shown on the Web page.
2. The customer selects the ClickToCall widget, enters their telephone number into the entry
field, and presses the Call Me button.
3. The customer's telephone rings and they answer it. The customer is connected to a
customer service representative for the hardware store.
The customer is put in contact right away with a person that can answer their questions,
without having to look up a telephone number and place the call.
5.3.2 Using the widget
Figure 5-6 shows how the ClickToCall widget appears to the user in a Web page.
Figure 5-6 ClickToCall widget on a Web page
Using the widget is simple. The user simply enters the phone number where they can be
reached and clicks the Call Me button. For testing purposes, we will use a soft phone that
requires you to input the IP address of the IP PBX application or hardware PBX system. For
example sip:Customer@192.168.1.102 where Customer is the name of the user configured
in the user registry. The results are shown in Figure 5-7.
Figure 5-7 Clicking the Call Me button
Chapter 5. Using widgets for telephony and Web collaboration
35
Figure 5-8 shows how the widget appears to the user after the call has been connected. The
user can use the End Call button to end the call or the Cobrowse button to initiate a
collaboration dialog (see 5.1, “CollaborationDialog widget” on page 32).
Figure 5-8 Call connected
Clicking the End Call button will disconnect the call (Figure 5-9).
Figure 5-9 Call disconnected
5.3.3 Embedding the Widget in a Web page
To incorporate the ClickToCall widget in a Web page, you first import the ClickToCall style
sheet and the Dojo style sheets. An example is shown in Example 5-1.
Example 5-1 Importing the style sheets
<meta name="DC.LANGUAGE" scheme="rfc1766"/>
<link href="PlantMaster.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="./ceadojo/dojo/dojo.js" djConfig="parseOnLoad:
true, isDebug: false"></script>
<style type="text/css">
@import "./dijit/themes/tundra/tundra.css";
@import "./ceadojo/cea/widget/ClickToCall/ClickToCall.css";
@import "./ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
</style>
Next, add the ClickToCall widget. The CEA widgets are built on top of Dojo's Tundra theme.
We need to add this theme to the body. The widget is added to the page as shown in
Example 5-2.
Example 5-2 Adding the ClickToCall widget
<body class="tundra">
<h1>Welcome to Communication Enabled Applications</h1>
<p>The widgets below demonstrate some of the capabilities of the IBM WebSphere
Application Server Feature Pack for CEA. </p>
<table>
<tr>
<td><h2>Click To Call</h2>
<div id="clickToCallWidget">
<div ceadojoType="cea.widget.ClickToCall" widgetNumber="sip:CSR@localhost">
</div>
</td>
</tr>
</table>
</body>
36
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
The ClickToCall widget has the following attributes that can be set:
򐂰 widgetNumber is used by the ClickToCall widget to determine what number to call.
򐂰 enableCollaboration determines whether this widget will be made available for
cobrowsing. If cobrowsing is enabled you must also configure the next two attributes
– canControlCollaboration determines whether this widget will be able to drive the
collaboration session
– defaultCollaborationUri specifies what page to load first when the Contact center
cobrowsing is started.
You can see the widgetNumber attribute in the example is specified as sip:CSR@localhost.
򐂰 CSR is the name of the SIP phone or the voice over internet phone.
򐂰 localhost is the host name of where the softphone (softphone is a software that emulates
an actual phone line) is registered. This is the host name associated with the installed
IP-PBX application. In production scenarios you will use the IP address of the IP PBX box,
(for example, 192.168.1.102 instead of localhost).
5.4 CallNotification widget
The CallNotification widget works in conjunction with the ClickToCall Widget. The
CallNotification widget is embedded into a Web page that is accessed by users that are
assigned to receive and respond to calls made through various means to the user. Authorized
users can log into their workstations, and use the CallNotification widget to register their
phones to be available to take calls from other callers. When a user registers a phone with the
CallNotification widget, the widget enters an available state. When registered, the user is
notified automatically of incoming calls in their browser and can connect to the caller.
After the user is connected to a call, they have the option to launch a cobrowsing session
using a button available on the CallNotification widget. Clicking that button launches the
CollaborationDialog widget.
The CallNotification widget can also be used without the ClickToCall widget. Although this is
not a common use, this scenario might be used when you want to extend the widget (for
example to pull customer information).
Chapter 5. Using widgets for telephony and Web collaboration
37
5.4.1 Using the widget
Figure 5-10 shows a Web page that contains the CallNotification widget. The widget can be
customized to suit the style and colors of the Web interface.
Figure 5-10 CallNotification widget
The first step to using the call notification feature requires clicking the telephone icon to
specify that a user is available if a call comes in.
The widget will now indicate that it is available to monitor for incoming calls, as shown in
Figure 5-11.
Figure 5-11 The widget is available to monitor for calls
After a call comes in and the user answers the phone, the CallNotification widget will display
that it is connected, as shown in Figure 5-12.
Figure 5-12 The call is connected
After the call is disconnected, the status will again change back to "Available".
38
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
5.4.2 Embedding the widget
Adding the CallNotification widget to a Web page is similar to adding the ClickToCall widget.
The CallNotification widget was built using the functionality of the Dojo toolkit. To use the
widget, embed it in the Web page and customize the CSS style for the widget. The
functionality provided by the widget can also be extended, allowing you to create custom
version to handle more advanced tasks. Perform the following steps:
1. Add the CEA Dojo toolkit declaration to the page (Example 5-3).
Example 5-3 Declare the CEA Dojo toolkit
<script type="text/javascript" src="./ceadojo/dojo/dojo.js"
djConfig="parseOnLoad: true, isDebug: false"></script>
2. Add the CallNotification style sheet reference (Example 5-4).
Example 5-4 Add the CallNotification style sheet
<style type="text/css">
@import "./ceadojo/dijit/themes/tundra/tundra.css";
@import "./ceadojo/cea/widget/CallNotification/CallNotification.css";
@import "./ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
</style>
3. Add the CallNotification declaration (Example 5-5).
Example 5-5 Add the CallNotification widget
<body class="tundra">
<div id="callNotificationWidget">
<div ceadojoType="cea.widget.CallNotification" enableCollaboration="true"
canControlCollaboration="true" defaultCollaborationUri="index.html"></div>
</div>
The parameters available for collaboration are:
򐂰 widgetNumber is an optional attribute that determines what number to monitor for incoming
calls. If not specified, the user is presented with a text field to enter the number.
򐂰 enableCollaboration determines whether this widget is available for cobrowsing. If
cobrowsing is enabled, you must also configure the next two attributes
– canControlCollaboration determines whether this widget is able to drive the
collaboration session
– defaultCollaborationUri specifies what page to load first when the Contact center
cobrowsing is started.
5.5 Cobrowse widget
Cobrowsing is the concept of allowing two users to view a Web page together. The Cobrowse
widget can be embedded into a Web page to launch a linked session between two peers to
allow cobrowsing. The user initiating the cobrowsing session will press a button to generate a
URL that they pass to their peer. When the peer enters that URL into their browser, the
CollaborationDialog widget will open a modal window in both Web browsers. The initiator of
Chapter 5. Using widgets for telephony and Web collaboration
39
the session is the controller of the navigation and can drive the session by sending a page to
the peer, having the peer follow his actions, or by highlighting an item on the page. The
initiator of the session can also choose to give control to the peer.
5.5.1 Using the widget
As an example, consider two people who are chatting using instant messaging when they are
both browsing the same store Web site. They can both be looking at the same product on a
Web site deciding which one to buy. The Web page has an option to start a cobrowsing
session.
User A clicks the link to start the cobrowsing session. The resulting page contains the
Cobrowse widget, as shown in Figure 5-13.
Figure 5-13 Cobrowse widget
User A clicks the Create button. This generates an URL and places it in the Invitation Link
field. User A passes this link to user B by way of an instant message or over the phone. The
Cobrowse widget Create button is replaced with an End Collaboration Session button. The
status is shown at the bottom of the widget, as seen in Figure 5-14.
Figure 5-14 Waiting for peer session
User B enters the URL into their Web browser and the two users are connected in a
cobrowsing session using the CollaborationDialog widget. User A drives the session to show
user B a particular product. As both users are viewing the item, User A highlights the price in
the page for user B.
After they are finished shopping, each user closes the collaboration window, and one or both
click the End Collaboration Session button to disconnect.
40
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
5.5.2 Embedding the widget
The first process in using cobrowsing is to add the widget to your Web application.
Example 5-6 is an example of an HTML page with the Cobrowse widget.
Example 5-6 Cobrowse widget in an HTML 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>Cobrowse Widget</title>
<script type="text/javascript" src="./ceadojo/dojo/dojo.js" djconfig="parseOnLoad:
true, isDebug: false"></script>
<style type="text/css">
@import "./ceadojo/dijit/themes/tundra/tundra.css";
@import "./ceadojo/cea/widget/Cobrowse/Cobrowse.css";
@import "./ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
</style>
</head>
<body class="tundra">
<!-joinCollaborationURI: String
Specifies the page to which the invitee is taken.
This page must be able to accept an additional parameter
-->
<div id="cobrowseWidget">
<div ceadojoType="cea.widget.Cobrowse"
joinCollaborationURI="CollabProject/Cobrowse.html"
defaultCollaborationUri="index.html"></div>
</body>
</html>
Let us look at various parts of the HTML file and the tags in the page.
򐂰 The <style> tag imports the dojo style sheets for the widgets.
򐂰 The <script> tags import the CEA Dojo toolkit.
򐂰 You see the declaration of the Cobrowse widget in the HTML code. The Cobrowse widget
has a button to generate a session and an URL that can be passed to a second person,
which can be pasted into their Web browser to initiate the collaboration session. This
widget is added to a page in a <div> tag.
The parameters for the Cobrowse widget are:
򐂰 joinCollaborationURI is used to generate the invitation link that can be sent to the peer.
This needs to be a link to a page that contains the peer cobrowse widget and can accept
an additional request paramater. Commonly, this will be a link to the current page you are
adding the widget to or a specific page created with instructions detailing how to use
peer-to-peer cobrowsing.
򐂰 defaultCollaborationUri specifies what page to load first when peer-to-peer cobrowsing
is started.
Chapter 5. Using widgets for telephony and Web collaboration
41
5.6 Click-to-call example using widgets
This scenario illustrates the use of the ClickToCall widget and CallNotification widget to add
the ability for a customer to be connected with a customer service representative (CSR) into
an existing application. The scenario will include information about the internal flow that will
occur when the widgets are used, the implementation and development details and a testing
interface using soft phones.
The ClickToCall widget is normally used by the customer who wants to talk to a CSR. The
customer enters their telephone number into the ClickToCall widget and clicks the Call Me
button. The CallNotification widget is used by the CSR. The CSR activates the
CallNotification widget so that when the call comes in from the customer, the CSR is notified
of the call. In a normal customer/CSR scenario, the customer will only see the ClickToCall
widget and the CSR will only see the CallNotification widget.
Sample application:
This example is based on the PlantsByWebSphereAjax sample application shipped with
the CEA feature pack. This example application was built using the functionality of the CEA
Dojo Toolkit. The instructions illustrate how the ClickToCall widget was integrated into the
application. This sample application and the supporting documentation can be found in the
app_server_root/feature_packs/cea/samples/plantsbywebsphere directory.
Review the documentation in this directory for information about installing and using this
application.
5.6.1 Part 1: Integrating the ClickToCall widget in the application
The ClickToCall and CallNotification widgets are both built using the functionality provided in
the Dojo toolkit. This scenario will go through process of configuring the ClickToCall widget to
create a call between a hard-coded number provided to the widget during initialization and a
number provided by the customer. This will be followed by the configuration of the
CallNotification widget that notifies the CSR of an incoming call. The scenario describes how
to customize the CSS styles for the widgets so that they have a look similar to the rest of the
application.
In this section, we go through the process of embedding the ClickToCall widget. The
ClickToCall widget is used by the customer who wants to talk to a CSR. The customer will
enter their telephone number into the ClickToCall widget and select Call. We configure the
ClickToCall widget to create a call between a hard-coded number provided to the widget and
a number provided by the customer during run time. We also customize the CSS styles for the
widget.
Note: Remember that the functionality provided by the widget can also be extended,
allowing you to create your own custom version to handle more advanced tasks.
42
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Step 1: Import the widgets to the Web application
The first step in integrating the ClickToCall widget in the application is to import the widgets
into your Plants by WebSphere Ajax edition application. The ClickToCall widget code is
located in the app_server_root/feature_packs/cea/javascript directory. It contains all the
Dojo files needed for the widget to work.
1. Expand PlantsByWebSphere_WEB and then right click the WebContent folder.
2. Select Import.
3. Select General  File System on the Import page.
4. Select Next.
5. On the File system page select Browse and enter the location of the CEA widgets,
app_server_root/feature_packs/cea/javascript.
6. Select OK.
7. Expand javascript.
8. Select ceadojo.
9. Select Finish.
Step 2: Create the customer-facing Web page
Next, create the Contact us Web page. First create the page and then import the ClickToCall
style sheet, register the CEA module using registerModulePath and load ClickToCall widget.
Finally, add the ClickToCall widget to the new page.
1. Right click WebContent under PlantsByWebSphere_WEB.
2. Select New  Web Page.
3. Enter contactus.html for the File Name and /PlantsByWebSphere_WEB/WebContent in the
Folder field.
4. Select HTML/XHTML for the Template and select Finish.
Step 3: Integrate the ClickToCall widget in the page
Next, add the ClickToCall widget to the Contact Us Web page. Customers use this widget to
request a call from a CSR.
1. Open the contactus.html file located under PlantsByWebSphere_WEB 
WebContent.
2. Add code to import the ClickToCall style sheet and the Dojo style sheets, and set ceadojo
as the main directory for dojo and the CEA widgets. We need to add other Plants by
WebSphere and Dojo imports too. Add the code shown in Example 5-7 in the "head"
section of the contacus.html page:
Example 5-7 Import the style sheets
<meta name="DC.LANGUAGE" scheme="rfc1766"/>
<link href="PlantMaster.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="./ceadojo/dojo/dojo.js"
djConfig="parseOnLoad: true, isDebug: false"></script>
<style type="text/css">
@import "./dijit/themes/tundra/tundra.css";
@import "./ceadojo/cea/widget/ClickToCall/ClickToCall.css";
@import "./ceadojo/cea/widget/CollaborationDialog/CollaborationDialog.css";
</style>
Chapter 5. Using widgets for telephony and Web collaboration
43
3. Add code to edit the default style of the ClickToCall widget, giving the widget rounded
corners, a green background, and borders. The code is shown in Example 5-8. Add it to
the "head" section of the page.
Example 5-8 Update the style for the widget
<style type="text/css">
.tundra .clickToCallWidget {
-moz-border-radius: 10px;
-webkit-border-radius: 10px;
border-left:1px solid #000000;
border-right:1px solid #000000;
border-bottom:1px solid #000000;
background-color: #669966;
}
.tundra .clickToCallWidgetPhoneNumberText {
color: #FFFFFF;
font-size:0.8em;
}
.tundra .clickToCallWidgetButton {
font-family:Arial,Helvetica,sans-serif;
font-size:13px;
font-weight: normal;
}
</style>
4. Add a style to the body tag. Replace the existing <body> tag with the code in Example 5-9.
Example 5-9 Add the style to the body
<body class="tundra">
5. Add the ClickToCall widget. Make sure to modify the phone number that the customer will
call when the customer activates click-to-call. For example,
widgetNumber="sip:CSR@localhost".
– CSR is the name of the X-Lite softphone
– localhost is the host name where your softphones are registered. This is the host
name associated with the installed IP PBX application.
6. Add the code in Example 5-10 to the body section.
Example 5-10 Add the ClickToCall widget
<h1>Welcome to Communication Enabled Applications</h1>
<p>
The widgets below demonstrate some of the capabilities of the IBM WebSphere
Application Server Feature Pack for CEA. </p>
<table>
<tr>
<td><h2>Click To Call</h2>
<div id="clickToCallWidget">
<div ceadojoType="cea.widget.ClickToCall"
widgetNumber="sip:CSR@localhost"/>
</div>
</td>
</tr>
</table>
</body>
44
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
7. Save the file.
8. Integrate the new page with the ClickToCall function into the application. In this example,
the banner.jsp file is updated to add a new tab providing a link to the contactus.html page.
Open the banner.jsp (Note this is the JSP file not HTML file) located under
PlantsByWebSphere_WEB  WebContent. Add the CONTACT US tab to the banner.
At the bottom of the file there is a table of tabs. Add the code in Example 5-11 to the table
of tabs, above the line of code adding the help.jsp.
Example 5-11 Update the banner
<a class="global" href="/PlantsByWebSphereAjax/contactus.html">Contact Us</a>
5.6.2 Part 2: Integrating the CallNotification widget in the application
In this section we will embed the CallNotification widget into the same application. In our
scenario, the CallNotification widget is used by the CSR to be notified when a call from a
customer comes in. We will add the CallNotification widget and customize the CSS style for
the widget. The functionality provided by the widget can also be extended, allowing you to
create your own custom version to handle more advanced tasks, but this is not a part of this
scenario. We are adding the CallNotification widget to the same application as the ClickToCall
widget. In a normal customer/CSR scenario the customer only sees the ClickToCall widget
and the customer service representative only sees the CallNotification widget.
First, you will create the call notification Web page. You will create the page and then import
the CallNotification style sheet, register the CEA module using registerModulePath and load
CallNotification widget. Then you will add the CallNotification widget to the new page.
Step 1: Create the CSR-facing Web page
Create the callnotification.html Web page by performing the following steps.
1. Right-click WebContent under PlantsByWebSphere_WEB.
2. Select New  Web Page.
3. Enter callnotification.html for the file name and /PlantsByWebSphere_WEB/WebContent
in the Folder field.
4. Select HTML/XHTML for the Template.
5. Select Finish.
Chapter 5. Using widgets for telephony and Web collaboration
45
Step 2: Integrate the CallNotification widget
Add the CallNotification widget to the new Web page by performing the following steps:
1. Open the callnotification.html file.
2. Add the code shown in Example 5-12 to the "head" section. This code imports the
CallNotification style sheet and Dojo style sheets. It will also set ceadojo as the main
directory for dojo and the CEA widgets. It will also add other PlantsbyWebSphere and
Dojo imports.
Example 5-12 Import the style sheets
<meta name="DC.LANGUAGE" scheme="rfc1766"/>
<link href="PlantMaster.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="./dojo/dojo.js"
djConfig="isDebug: false, parseOnLoad: true">;
</script>
<script type="text/javascript">
var djConfig = { baseUrl:"./ceadojo/dojo/"};
</script>
<script type="text/javascript" src="./ceadojo/dojo/dojo.js"></script>
<style type="text/css">
@import "./dijit/themes/tundra/tundra.css";
@import "./dojo/resources/dojo.css";
@import "./ceadojo/cea/widget/CallNotification/CallNotification.css";
</style>
3. Add the code shown in Example 5-13 to the "head" section. This code will edit the default
style of the CallNotification widget, giving the widget rounded corners, a green background
color, and borders.
Example 5-13 Edit the default style
<style type="text/css">
.tundra .callNotificationWidget {
-moz-border-radius: 10px;
-webkit-border-radius: 10px;
border-left:1px solid #000000;
border-right:1px solid #000000;
border-bottom:1px solid #000000;
background-color: #669966;
}
.tundra .callNotificationWidgetPhoneNumberText {
color: #FFFFFF;
font-size:0.8em;
}
.tundra .callNotificationWidgetButton {
font-family:Arial,Helvetica,sans-serif;
font-size:13px;
font-weight: normal;
}
</style>
46
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
4. Add a style to the body tag. Replace the existing <body> tag with Example 5-14.
Example 5-14 Add the style to the body
<bodyclass="tundra">
5. Add the CallNotification widget using the code in Example 5-15. Add this below the body
tag. Update the telephone number of the CSR, or if you wish, leave out widgetNumber. If
you do not hard code the widgetNumber, the widget will ask for the number at runtime.
Example 5-15 Add the CallNotification widget
<h1>Welcome to Communication Enabled Applications</h1>
<p>The widget below demonstrates some of the capabilities of the IBM WebSphere
Application Server Feature Pack for CEA. </p>
<table>
<tr>
<td><h2>Call Notification</h2>
<div id="callNotificationWidget">
<div ceadojoType="cea.widget.CallNotification"
widgetNumber="sip:CSR@localhost"/>
</div>
</td>
</tr>
</table>
6. Edit the banner.jsp file to add a new tab to the banner. Open the banner.jsp file (The JSP
file not the HTML file) located under PlantsByWebSphere_WEB  WebContent. Add
the CALL NOTIFICATION tab to the banner. At the bottom of the file there is a table of
tabs. Add the code in Example 5-16 to the table of tabs, below the Contact Us tab and
before the Options tab. Save the banner.jsp file.
Example 5-16 Update the banner
<a class="global" href="/PlantsByWebSphereAjax/callnotification.html" >Call
Notification</a> :
5.6.3 Part 3: Test the application
The last step is to prepare and deploy the application. After the application is deployed, test
by performing the following steps:
1. Open two browsers, using two different browser programs (for example Internet Explorer
and Firefox). Direct each browser to the following URL:
http://localhost:9080/PlantsByWebSphereAjax/
Make sure you are using browsers that are supported by the CEA feature pack. You now
see Contact Us and Call Notification on the banner of the application (Figure 5-15).
Figure 5-15 Application banner
2. Start two softphones.
Chapter 5. Using widgets for telephony and Web collaboration
47
3. On one of the browsers, act as the CSR. Select the Call Notification tab (Figure 5-16) to
display the callnotificiation.html page and the CallNotification widget.
Figure 5-16 PlantsByWebSphere Call Notification tab
4. Select the telephone icon to specify that the CSR is available if a call comes in. The widget
will now display as available, as shown in Figure 5-17.
Figure 5-17 The widget indicates you are available for calls
5. On the second browser, act as the customer. Select the Contact Us tab to display the
contactus.html page that displays the ClickToCall widget. See Figure 5-18.
Figure 5-18 Plants By WebSphere Contact Us page
48
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
6. Activate the call between the customer and customer service representative.
a. On the ClickToCall widget enter the customer number, for example
sip:Customer@localhost. See Figure 5-19.
Figure 5-19 Enter the number
b. Select the Call Me button. This will ring the customer softphone first. Answer the call.
c. After you answer the call the CSR softphone will now ring. Answer that call. You will
now have the two phones talking to each other.
Tip: Because both softphones are on the same machine it can be hard to tell that the
softphones are talking to each other. Look at the microphone and volume status bars
on the softphones when you talk.
7. The ClickToCall widget will now display that it is connected, as shown in Figure 5-20.
Figure 5-20 The customer sees the call is connected
8. The CallNotification widget will also display that it is connected, as shown in Figure 5-21.
Figure 5-21 The CSR sees the call is connected
9. To end the session, click the hang-up call icons on either softphone, or select the hang-up
icon on one of the widgets. If you select the hang-up icon on a widget you are prompted
with "Are you sure that you want to end this call?" Select Yes. The ClickToCall widget will
now display as Disconnected. The CallNotification widget will now display as Available.
Chapter 5. Using widgets for telephony and Web collaboration
49
50
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
6
Chapter 6.
Using Web services for
telephony
The Web services interface that is supported by the CEA feature pack allows telephony
services to be integrated into new and existing applications. Web service calls can be made
by non-Web components in a business application to access the communication services
from that application layer. The operations available on the Web service interface are the
same as the calls that are available for the REST APIs. Web service calls are available to
open a telephony session, make a call, end a call, close a telephony session, and to get
asynchronous call status updates using WS-Notification.
This chapter discusses the use of the Web services interface.
© Copyright IBM Corp. 2010. All rights reserved.
51
6.1 Web services
A Web service is designed to support interoperable machine-to-machine interaction over a
network. It is frequently just Web application programming interfaces (APIs) that can be
accessed over a network, and started on a remote system hosting the requested services. A
typical Web service application communicates over the HTTP protocol used on the Web. It
uses XML messages that follow the Simple Object Access Protocol (SOAP) standard. There
is a machine-readable description of the operations offered by the service written in the Web
Services Description Language (WSDL). Using Web services means that you can write
applications in a variety of languages, and on other software platforms. Also, the
standards-based approach ensures that applications written by vendors or teams can easily
share information.
The Java API for XML Web Services (JAX-WS) is a Java programming language API for
creating Web services. JAX-WS uses annotations introduced in Java SE 5, to simplify the
development and deployment of Web service clients and endpoints. Clients create a local
proxy to represent a service, then invoke methods on the proxy. The JAX-WS runtime system
converts API calls and matching responses to and from SOAP messages to shield the
developer from that complexity.
6.2 Web services tooling
WebSphere Application Server provides two main command line tools for working with
JAX-WS to develop Web services. The wsimport command is a top-down development tool
that will create the necessary beans, service client, service endpoint interface, and wrappers
from a provided WSDL file that describes where the Web service is deployed and what
operations this service provides. The wsgen command does the reverse for bottom-up
development. It will create a WSDL document and wrappers when needed from Java code
with the proper Web service annotations.
The Web services tooling in Rational Application Developer builds on the wsimport and wsgen
commands provided by the WebSphere JAX-WS runtime environment. It allows you to create
either a service client or a skeleton bean. The skeleton bean contains a set of methods that
correspond to the operations described in the WSDL document. When the bean is created,
each method has a trivial implementation that you replace by editing the bean. This bean is
not created if you use the wsimport command, so you have to create it yourself.
6.3 CEA WSDL files
The CEA feature pack includes two main machine-readable descriptions of the operations
offered by the CEA Web service written in WSDL.
ControllerService WSDL file
The ControllerService.wsdl file contains the description of the operations offered by the
CEA Web service. It can be used to generate the Web services client code needed to
communicate with the CEA Web service. Generated Java classes include OpenSession,
CloseSession, MakeCall, and EndCall. As a result, an application developer need only call
the correct methods on the generated classes to manage telephone calls in an application.
52
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
The CeaNotificationConsumer.wsdl follows the WS-Notification standard that provides a
standards-based framework through which Web service applications can participate in
publish and subscribe messaging patterns. The WS-Notification specification consists of the
following documents:
򐂰 Web Services Base Notification 1.3 (WS-BaseNotification) OASIS Standard
http://docs.oasis-open.org/wsn/wsn-ws_base_notification-1.3-spec-os.pdf
This document defines the basic producer, consumer, and subscriber roles that can be
taken on by applications, and the interactions between them.
򐂰 Web Services Brokered Notification 1.3 (WS-BrokeredNotification) OASIS Standard
http://docs.oasis-open.org/wsn/wsn-ws_brokered_notification-1.3-spec-os.pdf
This document defines the concept of a notification broker, which can act as a middle
man between producer and consumer applications to simplify the programming of
producer applications, or provide value-add services.
򐂰 Web Services Topics 1.3 (WS-Topics) OASIS Standard
http://docs.oasis-open.org/wsn/wsn-ws_topics-1.3-spec-os.pdf
This is a stand-alone specification, which defines syntaxes for classifying events using a
topic, and which can be used by the other two specifications.
CeaNotificationConsumer WSDL file
The CeaNotificationConsumer.wsdl file describes a consumer service. It can be used to
generate a service implementation class, CeaNotificationConsumerSOAPImpl.java as well as
the service interface, NotificationConsumer.java in Rational Application Developer. As a
result, you just need to Implement the notify() method in
CeaNotificationConsumerSOAPImpl.java to receive and process notification messages that
notify you of changes to the call status. The rest is handled by the Web services runtime.
Neither the client code nor the provider code is required to write or parse SOAP messages.
6.4 Architectural flow: Call flow example
Figure 6-1 shows a simple flow describing the implementation steps that take place in order
to establish a call through a Web service request.
Business Application
1
2
6
WebSphere
Application
Server
CEA System
Application
3
5
IP/PBX
Device1
4
Device2
Figure 6-1 Call flow example for Web services
Chapter 6. Using Web services for telephony
53
1. The business application sends a Web service call request.
2. The WebSphere Application Server Web container calls the CEA system application.
The CEA Web service calls the SIP (Session Initiation Protocol) CTI (Computer Telephony
Integration) layer.
3. The CEA system application sends the SIP flow to the IP/PBX (Internet Protocol/Private
Branch Exchange, the telephony integration box).
– The CTI layer contacts the IP/PBX through SIP.
– The CTI layer sends the call request to the IP/PBX.
– The request is a CSTA (Computer-Supported Telecommunications Applications)
message in the SIP body.
4. The IP/PBX establishes a call between the devices.
5. The IP/PBX sends device events to the CEA system application.
The events are sent through CSTA messages.
6. The CEA system application sends device events to the business application
WS-Notification is used for event notification.
6.5 Implementation overview
To access telephony services with Web services follow these steps:
1.
2.
3.
4.
Enable the CEA system application in your WebSphere Application Server.
Configure your application server to support the CEA Web service.
Install and configure your IP-PBX and restart your server.
Develop and deploy your application.
More details about the process to develop a Web service client that invokes the CEA Web
service are available in the CEA feature pack information center:
򐂰 Accessing telephony services with Web services clients
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/topic/com.ibm.websphere.ce
afep.multiplatform.doc/info/ae/ae/tcea_manage_calls_webservice.html
򐂰 One of the steps included in the article includes some example code that shows how each
of the Web service APIs can be used:
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/topic/com.ibm.websphere.ce
afep.multiplatform.doc/info/ae/ae/tcea_manage_calls_webservice_step6.html
6.6 Development process
This section outlines the process that can be used to develop the sample Web services
application that is supplied with the CEA feature pack using Rational Application Developer
7.5.4.
The application is available in the following directory:
app_server_root/feature_packs/cea/webservice.sample/commsvc.ws.sample.ear
There is also information about how to run the application in the README.txt file in the same
directory.
54
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Before you start, you will need an application server profile that was created for the CEA
feature pack. See the following Web page in the information center for more details:
http://publib.boulder.ibm.com/infocenter/wasinfo/fep/topic/com.ibm.websphere.ceafe
p.multiplatform.doc/info/ae/ae/tcea_cea_getstart_step2.html
6.6.1 Create a new application
To create a new application in Rational Application Developer, perform the following steps:
1. Open Rational Application Developer 7.5.4 with a new workspace.
2. Create a new runtime environment for WebSphere Application Server v7.0 with the
installation directory of the install with the CEA feature pack.
3. Create a new Dynamic Web Project called commsvc.ws.sample that uses the new runtime
environment and adds the project to an EAR called commsvc.ws.sampleEAR.
4. Open the Java EE perspective.
6.6.2 Obtain the WSDL files and schema files
To get the WSDL and schema files you will to perform the following tasks.:
1. Open the URL
http://host:port/commsvc.rest/ControllerService?wsdl
In this URL, host is the IP address or host name on which the Web container is listening
and port is the default http port.
When you do this, the WSDL file created in the file system during installation is read by the
Web services infrastructure. The correct host and port are configured in the WSDL file
sent to the browser. If you look at the file you will notice the ControllerService service and
the operations openSession, makeCall, endCall and closeSession.
Save the file as ControllerService.wsdl.
2. Open the URL
http://host:port/commsvc.rest/CeaNotificationConsumer?wsdl
If you look at the file you will notice the CeaNotificationConsumer service with the
CeaNotificationConsumerSOAP binding to the Notify operation of the WS-Notification
NotificationConsumer.
Save the file as CeaNotificationConsumer.wsdl
3. Open the URL
http://host:port/commsvc.rest/ControllerService/WEB-INF/wsdl/ControllerService_
schema1.xsd
Save the file as ControllerServiceschema1.xsd.
Chapter 6. Using Web services for telephony
55
6.6.3 Generate the Web services client code
The next step is to generate the Web services client code needed to communicate with the
CEA Web service:
1. Create a new folder called wsdl under commsvc.ws.sample/WebContent/WEB-INF and
import the WSDL and schema files into it. (See 6.6.2, “Obtain the WSDL files and schema
files” on page 55)
2. Right-click the ControllerService.wsdl file and select Web Services  Generate Client,
as shown in Figure 6-2.
Figure 6-2 Generate a client from the WSDL file
56
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
3. On the Web Services page, set the configuration slider to Develop client, as shown in
Figure 6-3.
Figure 6-3 Set the configuration type in the Web service client wizard
This tells the wizard to create the WSDL definition and implementation of the Web service.
This includes such tasks as creating the modules that contain the generated code, the
WSDL files, the deployment descriptors, and the Java files when appropriate. Use the
links on this page to verify your server, runtime, service project, and EAR project
configurations.
When done, click Finish.
Chapter 6. Using Web services for telephony
57
4. Look through the newly generated files located in Java
Resources/src/com.ibm.ws.commsvc.webservice.impl. Notice that classes have been
generated for the OpenSession, CloseSession, MakeCall, and EndCall operations
available on the CEA Web service. See Figure 6-4.
Figure 6-4 New classses
5. Open the ControllerService.java file. You see the JAX-WS annotations. See Example 6-1.
The @WebServiceClient is used to annotate a generated service interface. The
information specified in this annotation is sufficient to uniquely identify a wsdl:service
element inside a WSDL document. This wsdl:service element represents the Web service
for which the generated service interface provides a client view.
Example 6-1 WebServiceClient annotation
@WebServiceClient(name = "ControllerService",
targetNamespace = "http://impl.webservice.commsvc.ws.ibm.com/",
wsdlLocation = "WEB-INF/wsdl/ControllerService.wsdl")
public class ControllerService
extends Service
The @WebEndpoint annotations are used to annotate the getPortName() methods of a
generated service interface. The information specified in this annotation is sufficient to
uniquely identify a wsdl:port element inside a wsdl:service. See Example 6-2 and
Example 6-3.
Example 6-2 @WebEndpoint annotation
@WebEndpoint(name = "ControllerPort")
public Controller getControllerPort() {
Example 6-3 @WebEndpoint annotation
@WebEndpoint(name = "ControllerPort")
public Controller getControllerPort(WebServiceFeature... features) {
58
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
6.6.4 Create the servlet
Next, create the front-end servlet through the following procedure:
1. Create a new servlet called CommWebServiceServlet in the commsvc.ws.sample project
with the com.ibm.ws.commsvc.webservice Java package.
2. Open commsvc.ws.sample/commsvc.ws.sample/Servlets/CommWebServiceServlet.
3. Add a new URL pattern for the servlet.
a. In the Design view, on the left panel, select Servlet Mapping
CommWebServiceServlet. In the Details section select Add. See Figure 6-5.
Figure 6-5 Update the servlet mapping
b. Click the new item that shows in the URL Pattern box and enter
/CommWebServiceServlet/*. See Figure 6-6.
Figure 6-6 Add the URL pattern
4. On the left panel select Welcome File List and select Remove.
5. Save the file and close.
Write the client side code
Next, write the client side code to call methods against the Web service client with the
following procedure:
1. Create two classes called CommWebServiceServlet.java and PhoneSession.java in
commsvc.ws.sample\Java Resources\src\com.ibm.ws.commsvc.webservice. Copy the
code for these classes from Appendix A, “Sample code for the Web services example” on
page 89.
2. Open the CommWebServiceServlet.java file. This class allows the browser/user to control
a device by making use of the CEA Web service interface. The Java code starts by
opening a session with that device, where the status can be refreshed, a call can be made
or ended, or the monitoring session can be closed. This file is heavily commented, so take
some time to look through the code.
Chapter 6. Using Web services for telephony
59
3. Open the PhoneSession.java file. The purpose of this file is to control the state and actions
taken related to a specific phone. A reference to this object is kept in the HttpSession and
a HashMap in the servlet code so it can be found in other contexts (servlet requests and
WS-Notifications). The PhoneSession.java code contains the accessWebService()
method that gets access to the Web service client.
The openSession() method is called in order to start monitoring a telephone. In this
method you first build the Web service request object, access the Web service, and call
the Web service to open the session. You will use the endpoint reference (EPR) to create
a new object to make Web service calls on. The EPR includes information that allows the
Web service to map requests to this session. The EPR must be used in all other APIs
called related to the session monitoring that phone. The EPR is critical for several
reasons. First, it allows the Web service interface to be simpler, eliminating the need to
pass a state object as a parameter in all follow-up requests. The EPR itself has enough
information for the Web service to track it. It is also used in a clustered environment to
ensure follow-on requests go back to the same container monitoring the phone.
Notice that notifyCallback is also set in the openSession() method, this is the URL needed
to contact to trigger a call notification (WS-Notification). For the URL, the host and port
must be where the Web service client resides. The context root much match that of the
WAR, including this Web services client. The name at the end must match the service
name in the CeaNotificationConsumer.wsdl.
Look through the code to make a call, end a call, and close a session. In the code the
callee is the person being called. Note the use of the EPR in each of the methods. Also,
the updateState() method is already created for you. This method will update the
softphone session with the new call status information that arrived in a WS-Notification.
60
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
6.6.5 Generate the WS-Notification consumer service
Generate the WS-Notification consumer service and code the notify() method:
1. Right-click the CeaNotificationConsumer.wsdl file and select Web Services  Generate
Java bean skeleton. See Figure 6-7.
Figure 6-7 Generate the Java bean skeleton
Chapter 6. Using Web services for telephony
61
2. On the Web Services page set the configuration slider to Develop service. See
Figure 6-8.
Figure 6-8 Set the configuration for the Web Service wizard to “Develop Service”
62
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Verify your server, runtime, service project, and EAR project configurations. Click Finish.
If you look through the newly generated files, you will notice the Java service
implementation class, CeaNotificationConsumerSOAPImpl.java, as well as the service
interface, NotificationConsumer.java. Also notice the associated Oasis files that were
generated. See Figure 6-9.
Figure 6-9 New files
3. Open the Java service implementation class, CeaNotificationConsumerSOAPImpl.java in
Java Resources/src/com.ibm.ws.commsvc.webservice.ceanotificationconsumer.
Notice the @WebService annotation (Example 6-4). This is used to specify that the class
is a Web service or that the interface defines a Web service.
Example 6-4 @WebService annotation
@javax.jws.WebService(
endpointInterface=
"com.ibm.ws.commsvc.webservice.ceanotificationconsumer.NotificationConsumer",
targetNamespace=
"http://webservice.commsvc.ws.ibm.com/CeaNotificationConsumer/",
serviceName="CeaNotificationConsumer",
portName="CeaNotificationConsumerSOAP")
public class CeaNotificationConsumerSOAPImpl{
Also, notice the notify() method that you will have to implement next to receive and
process notification messages. The notify() method is called automatically by the server's
notification broker when a notification takes place. See Example 6-5
Example 6-5 notify() method
public void notify(Notify notify) {
// TODO Auto-generated method stub
return;
}
Chapter 6. Using Web services for telephony
63
4. Replace the imports with Example 6-6.
Example 6-6 Replace the import statements
import java.util.List;
import
import
import
import
import
import
org.oasis_open.docs.wsn.b_2.NotificationMessageHolderType;
org.oasis_open.docs.wsn.b_2.Notify;
org.oasis_open.docs.wsn.b_2.NotificationMessageHolderType.Message;
org.w3c.dom.Element;
org.w3c.dom.Node;
org.w3c.dom.NodeList;
import com.ibm.ws.commsvc.webservice.CommWebServiceServlet;
import com.ibm.ws.commsvc.webservice.impl.CallState;
import com.ibm.ws.commsvc.webservice.impl.CallStatus;
5. Replace the notify() method with Example 6-7.
The notify method first extracts the list of notification messages. Next, it loops through the
messages and gets the message content as a DOM Element. Then it builds a CallStatus
object out of the notification by looping through and matching the text to a member of the
CallStatus object and setting it. Finally, it updates the status of the associated client state
object.
Example 6-7 notify() method
public void notify(Notify notify) {
CallStatus callStatus = null;
// Extract the list of notification messages.
List<NotificationMessageHolderType> notificationMessages = null;
notificationMessages = notify.getNotificationMessage();
// Loop through the messages.
for (int i=0; i< notificationMessages.size(); i++) {
NotificationMessageHolderType notificationMessage =
notificationMessages.get(i);
// Get the message content as a DOM Element.
Message message = notificationMessage.getMessage();
// Build a CallStatus object out of the notification.
Element messageContents = (Element) (message.getAny());
NodeList nodeList = messageContents.getChildNodes();
int numNodes = nodeList.getLength();
callStatus = new CallStatus();
for (int j=0; j<numNodes; j++) {
Node node = nodeList.item(j);
String nodeText = node.getTextContent();
String nodeName = node.getNodeName();
// Match the text to a member of the CallStatus object and set it.
if ("callStatus".equals(nodeName)) {
callStatus.setCallStatus(CallState.valueOf(nodeText));
} else if ("addressOfRecord".equals(nodeName)) {
callStatus.setAddressOfRecord(nodeText);
} else if ("callerAddressOfRecord".equals(nodeName)) {
callStatus.setCallerAddressOfRecord(nodeText);
} else if ("calleeAddressOfRecord".equals(nodeName)) {
64
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
callStatus.setCalleeAddressOfRecord(nodeText);
} else if ("callId".equals(nodeName)) {
callStatus.setCallId(nodeText);
} else if ("callFailureReason".equals(nodeName)) {
callStatus.setCallFailureReason(nodeText);
}
}
// Update the status of the associated PhoneSession state object.
CommWebServiceServlet.updatePhoneSession(callStatus);
}
}
6. Save your file and close it.
6.6.6 Install the application
To install the new application, perform the following steps:
1. From Rational Application Developer, export the commsvc.ws.sampleEAR project as an EAR
File. The EAR file will include the JAX-WS annotated classes, WSDL files, XSD schema,
and client side code you created.
2. Using the WebSphere administrative console, ensure the application server is started.
3. Ensure the communications service is enabled using the administrative console. Navigate
to Servers  Server Types  WebSphere application servers  server_name. On
the right, under Communications, select Communications Enabled Applications (CEA),
as shown in Figure 6-10.
Figure 6-10 Link to CEA configuration from the server configuration panel
Make sure the Enable communications service option is selected (Figure 6-11).
Figure 6-11 Enable CEA
4. Configure your application server to support the CEA Web service. Because the CEA Web
service support is built on WS-Notification, infrastructure in the base application server
must be created to enable this support. To simplify this, a script is provided in the CEA
installation.
The script applies changes to the base application server configuration. It creates a
service integration bus, creates a WS-Notification service, creates a service point
associated with the previously-created service, and starts the deployed service point
enterprise application.
a. Open a command prompt.
Chapter 6. Using Web services for telephony
65
b. Change directories to app_server_root\profiles\<CEA_PROFILE_NAME>\bin.
c. Issue the following command:
wsadmin -f app_server_root/feature_packs\cea\scripts\CEA_WSN_JAXWS_Setup.py
d. After the script has run successfully close your command prompt window.
5. Restart your application server.
6. Install and start your application through the administrative console.
6.6.7 Test the application
To test the application, perform the following steps:
1. Start two softphones, for example: sip:CSR@localhost and sip:Customer@localhost.
2. Open a browser window and point it to:
http://host:port/commsvc.ws.sample/CommWebServiceServlet
The CEA Web Service Sample page displays. This page includes a form to Open a
session to monitor a phone. In the Phone address of record text box, enter the address
of the softphone to be monitored. It must match the address of record that the softphone
used to register with the PBX. For example, the address might be a SIP URI of the form
sip:user1@domain where user1 represents the user name associated with the softphone
and domain represents the phone's domain.
3. Enter sip:CSR@localhost in the Phone address of record text box. See Figure 6-12.
Figure 6-12 Enter the phone address
4. Select Open session. When this button is pressed, a request is sent to the sample's
servlet, which calls the openSession Web service API. It can take a few seconds to set up
the session with the phone. At this point a Phone Status page is presented. Notice how
the address of record is set to what you entered on the first panel and that the call status
states CALL_STATUS_CLEARED. See Figure 6-13.
66
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Figure 6-13 Open the session
If a call is not active, the Peer address of record text box can be filled in with another
phone's address. Similar to the monitored phone, this address must be registered with the
PBX. For example, the address might be another SIP URI of the form sip:user2@domain
where user2 represents the user name associated with the phone and domain represents
the phone's domain. Pressing Make call causes the monitored softphone to call the newly
entered peer softphone with the makeCall Web service API.
5. Enter sip:Customer@localhost in the Peer address of record text box, and select Make a
call.
6. The CSR softphone rings. When the call gets delivered the status will update. See
Figure 6-14.
Figure 6-14 Updated call status
7. Answer both phones and select Refresh call status. This button can be pressed to fetch
any status updates that the application servlet has received through WS-Notification.
Notice how the status now states CALL_STATUS_ESTABLISHED. See Figure 6-15.
Chapter 6. Using Web services for telephony
67
Figure 6-15 The call is established
8. Select End the call. This triggers the endCall Web service API to end the call and the call
status goes back to CALL_STATUS_CLEARED.
9. Select Close the session. This triggers the closeSession Web service API and
terminates the monitoring session for the phone. The CEA Web Service Sample page
displays again.
68
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
7
Chapter 7.
External Web services support
When the CEA Web service is invoked, it interacts with an IP/PBX (Internet Protocol/Private
Branch Exchange) to monitor and control phones. The CEA Web service interface is
described by the ControllerService.wsdl file. If an external provider creates a Web service
that implements this WSDL, then CEA can be configured to use that provider instead of the
CEA Web service. This allows vendors to customize interactions with their IP/PBX.
This configuration disables the existing CEA Web service, but the REST interface is still
available. As REST requests are received, CEA uses a Web services client to communicate
with the external Web service provider. The external Web service provider is responsible for
all communication with the IP/PBX to provide third party call control.
To use an external Web service provider, it must be deployed and running on a server
accessible from the CEA server. The location of the WSDL file for the external service must
be known and accessible by using an HTTP request. Like the setup required when using the
Web service provided by CEA, you must start and configure an IP/PBX as well.
© Copyright IBM Corp. 2010. All rights reserved.
69
7.1 Call flow example
Figure 7-1 a simple flow describing the implementation steps that take place to establish a
call through a request to an external Web service provider.
Client
1
2
WebSphere
Application
Server
CEA System
Application
3
6
External Web
Service Provider
4
IP/PBX
Device1
5
Device2
Figure 7-1 External Web service flow
1. The client sends an HTTP REST request.
2. The WebSphere Application Server Web container calls the CEA system application.
– The CEA servlet interprets the REST request.
– The CEA servlet uses a Web services client.
3. The CEA system application sends the Web service request to the external Web service
provider.
4. The external Web service interacts with the IP/PBX.
Interaction can be proprietary.
5. The IP/PBX establishes a call between devices.
6. The external Web service sends device events to CEA.
WS-Notification is used for event notification.
7.2 Implementation overview
To use an external Web service provider, follow these steps.
1.
2.
3.
4.
5.
6.
70
Enable the CEA system application in your WebSphere Application Server.
Install and configure your IP-PBX and restart your server.
Install and configure the external Web service.
Configure the location of the third-party Web service WSDL.
Develop a new application that calls the REST interface.
Install and start the new application.
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
7.2.1 Configuring the location of the third-party Web service WSDL
Perform the following steps to configure the location of the third-party Web service WSDL:
1. In the administrative console, click Servers  Server Types  WebSphere application
servers  server_name. On the right side, under Communications, select
Communications Enabled Applications (CEA).
2. Under Telephony access method, select the Use a third-party Web services provider
for telephony access option, as shown in Figure 7-2.
Figure 7-2 Configure the third party provider
3. Enter the HTTP URL of the third-party WSDL in the third-party Web services provider's
WSDL field.
4. Save the settings and restart the server so that the new changes are applied to the run
time.
More details about the process to configure external Web service providers to use CEA are
available in the CEA feature pack information center:
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.web
sphere.ceafep.multiplatform.doc/info/ae/ae/tcea_third_party_web_service.html
This includes some example code that shows how to develop a new application that calls the
REST interface:
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.ceaf
ep.multiplatform.doc/info/ae/ae/tcea_third_party_web_service_step7.html
Chapter 7. External Web services support
71
72
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
8
Chapter 8.
Working with SIP applications
This chapter provides a high level overview of SIP applications. It is intended to provide you
with an idea of what SIP applications are and the basics of how they work.
© Copyright IBM Corp. 2010. All rights reserved.
73
8.1 SIP application structure
A SIP application might consist of the following items:
򐂰
򐂰
򐂰
򐂰
Servlets
Utility classes
Static resources and content
Descriptive meta information which ties all of the previous elements together.
By default, an instance of a SIP application runs on one virtual machine, but can be made to
run on more than one if the application is marked as distributable in the deployment
descriptor or by using the @Sipapplication(distributable) annotation. SIP applications that run
on multiple virtual machines must follow additional rules.
A SIP application exists as a structured hierarchy of directories. The directory structure used
in a SIP application is similar to the structure defined for HTTP servlets. A SIP servlet exists
under the WEB-INF/ directory. The following list details the contents of WEB-INF directory:
򐂰 The sip.xml deployment descriptor file
򐂰 The classes folder containing servlet and utility classes.
򐂰 The JAR folder for Java Archive files.
With the exception of the sip.xml deployment descriptor, these contents are the same that you
find in a standard HTTP servlet application.
8.1.1 Creating SIP applications
Rational Application Developer provides wizards to create SIP projects and servlets. To
create a new SIP project and EAR file in the Rational Application Developer workspace,
perform the following steps:
1. Select File  New  Other  SIP  SIP Project.
2. Add a SIP servlet to this new project by selecting File  New  Other  SIP  SIP
Servlet.
Figure 8-1 on page 75 shows a new SIP project and servlet.
74
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Figure 8-1 SIP project and servlet structure
8.1.2 Metadata for deployment
Metadata provides deployment information for an application. This metadata has been
included in SIP applications using the sip.xml deployment descriptor in previous SIP
releases. In SIP 1.1, this descriptor is still available with minor changes. In addition, SIP 1.1
adds support for annotations in SIP servlets and listeners, allowing you to embed metadata
directly in the application and to inject resources, such as an enterprise bean, into an
application.
SIP annotations
The four annotations supported in SIP 1.1 are:
򐂰
򐂰
򐂰
򐂰
@SipServlet
@SipApplication
@SipListener
@SipApplicationKey
SIP deployment descriptor
The following are values defined in the SIP application deployment descriptor.
򐂰 ServletContext Init Parameters
These configuration parameters are similar to used in HTTP Servlet configuration and
used for configuring container during initalization of the servlet.
򐂰 Session Configuration
These parameters give information to the container to initialize SIP session with specific
properties.
򐂰 Servlet Definitions
This section maps servlet name with actual classes to be used.
Chapter 8. Working with SIP applications
75
A sample deployment descriptor is shown in Example 8-1.
Example 8-1 Deployment descriptor
<sip-app>
<app-name>com.ibm.sipservlet.app.ibmapp</app-name>
...
<servlet>
<servlet-name>IBMSipServlet</servlet-name>
<servlet-class>com.ibm.sipservlet.app.ibmsipservlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>IBMSipServlet</servlet-name>
<pattern>
<equal>
<var>request.uri.user</var>
<value>IBMSIPSampleProxy</value>
</equal>
</pattern>
</servlet-mapping>
<proxy-config>
<sequential-search-timeout>1000</sequential-search-timeout>
</proxy-config>
<session-config>
<session-timeout>12</session-timeout>
</session-config>
</sip-app>
Deployment descriptor to mappings annotations
Table 8-1 shows how deployment descriptor attributes map to the @SipApplication and
@SipServlet annotations for SIP 1.1.
Table 8-1 Deployment Descriptor to Mappings annotation for @SipApplication
76
Display name
display-name
@SipApplication
displayName
Application name
Icons
small-icon or
large-icon
@SipApplication
smallicon or
@SipApplication
largeicon
Empty string
Description
description
@SipApplication
description
Empty string
Distributable
destributable
@SipApplication
distributable
False
Proxy timeouts
proxy-timeout
@SipApplication
proxyTimeout
Three minutes, in
seconds
Session timeouts
session-timeout
@SipApplication
sessionTimeout
Three minutes, in
seconds
Main servlet
main-servlet
@SipApplication
mainServlet
Empty string
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Deployment Descriptor to Mappings annotation for @SipServlet
Table 8-2 shows how deployment descriptor attributes map to the @SipServlet annotation for
SIP 1.1.
Table 8-2 Deployment Descriptor to Mappings annotation for @SipServlet
Servlet name
servlet-name
@SipServlet name
Short name of the
annotated class
Application name
app-name
@SipServlet
application name
Optional; check the
deployment descriptor
or the package for
@SipApplicationName
Startup order
load-on-startup
@SipServlet
loadOnStartup
Negative number
(container chooses
when to start this
servlet)
Initialization
parameters
init-param
(Not applicable; use
constants.)
(Not applicable)
8.2 SIP application packaging
Session Initiation Protocol (SIP) modules (containing SIP servlets) are typically packaged as
SAR files. A converged application is a combination of SIP servlets and HTTP servlets or
Java EE components (like EJBs). Converged applications are packaged as follows:
򐂰 A converged application with SIP and non-HTTP Java EE components is packaged as a
single EAR (Enterprise Archive) file.
򐂰 A converged application with SIP and Web components is packaged as a single SAR or
WAR archive, either stand-alone or as part of an EAR archive. The SIP and Web
applications can be packaged into a single EAR file with individual SAR or WAR files.
8.2.1 Using Rational Application Developer to package (export) a SIP project:
If you export an Enterprise project that contains a SIP module, the default result is an EAR file
with the SIP servlet packaged as a WAR file. If you export a SIP project, the default selection
is a WAR file. However, you can opt to export as a SAR file instead. Right-click the project and
select Export  Export  SIP  SAR file.
8.2.2 SIP and Java EE converged application
If the application.xml deployment descriptor is used to specify the modules included in the
application archive, the deployment descriptor's <web> element must be used for SIP Servlet
applications. See Example 8-2.
Example 8-2 SIP servlet module in the application.xml
<module>
<web>
<web-uri>mysipapp.war</web-uri>
</web>
</module>
Chapter 8. Working with SIP applications
77
If the application.xml deployment descriptor is not present, all files in the application
package with a filename extension of .war or .sar and that contain the sip.xml deployment
descriptor are considered converged SIP components.
8.2.3 SIP and HTTP converged application
For a converged SIP and Web application, the packaging must follows these rules:
򐂰 The archive must have the packaging directory structure standard deployment hierarchies.
򐂰 The SIP and HTTP servlets must have the same view of the application, which includes:
–
–
–
–
–
–
Context parameters
Context attributes
Context-listeners and context-attribute listeners
Accessing SIP Factory
Application class-loader
Application scoped JNDI, which can be looked up against java:comp/env on the
InitialContext
8.2.4 Accessing a SIP application
There are two approaches to accessing a SIP application within a Java or JEE application.
First approach: Accessing a SIP factory
Access to SipFactory instances is available to applications through a ServletContext attribute
with the name javax.servlet.sip.SipFactory, as shown in Example 8-3.
Example 8-3 Accessing the SipFactory through a ServletContext attribute
SipFactory sf = (SipFactory)
getServletContext().getAttribute("javax.servlet.sip.SipFactory");
Alternatively, access to the SipFactory instance can be made by the servlet applications
through annotation-based dependency injection, as shown in Example 8-4.
Example 8-4 Accessing the SipFactory using annotations
@Resource
private SipFactory sf;
Second approach: Accessing SIPApplicationSession by ID
A SipApplicationSession instance is identified by a container-specific ID. Applications are
frequently required to access the SipApplicationSession given its ID. Converged application
containers provide a SipSessionsUtil lookup object that applications can use to access the
SipApplicationSession instance by its ID. The reference to this lookup utility can be obtained
from the ServletContext attribute javax.servlet.sip.SipSessionsUtil, or by using the
@Resource annotation, that is, the annotations-based dependency injection.
78
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
8.2.5 Runtime structure for converged applications
A SIP container is an application server component that invokes the SIP action servlet and
interacts with the action servlet to process SIP requests. Some of the important functions of
SIP container are:
򐂰 Contain and manage servlets through their life cycle.
򐂰 Provide the network services over which requests and responses are received and sent.
򐂰 Decides which applications to invoke and in what order.
The SIP container has its own stack and sockets to listen to incoming calls. It is defined as a
separated OSGI component in WebSphere with its own class loader. However, the SIP
container and Web container use a common set of functions, like security, session
management, and other attributes. This common container code is referred to as a converged
container.
As shown in Figure 8-2, an application that includes SIP servlets, HTTP servlets, and portlets
can seamlessly interact, regardless of the protocol.
A listener point is a combination of transport protocol, IP address, and port number. The SIP
container supports the transport protocols UDP, TCP, and TLS over TCP.
Others
Portlets
Servlets
Presence
Before processing a request to interact on a particular protocol, a set of pre-processing
activities are performed to comply with a particular protocol requirement at the pre-processor
sub component.
Converged Container
HTTP Container
Pre-processor
HTTP
SIP Container
Pre-processor
SSL
SIP
TCP
UDP
Figure 8-2 Runtime structure for converged applications
8.3 SIP session flow
Figure 8-3 on page 80 shows the flow of a SIP session. The User Agents can be a Web client,
VOIP call, or a normal telephone connection., In Figure 8-3 on page 80, the User Agent on
the left initiates the call. The request is sent to the SIP server. The server will send a trying
response to the initiator when it is attempting to invite the second user agent (on the right).
When the SIP server is able to locate the responding user agent, it sends a similar response
back to the initiating user agent.
Chapter 8. Working with SIP applications
79
The responding user agent accepts the request and an “OK" signal is sent back to the SIP
server. The “OK" signal is passed on to the initiating user agent. The initalting user agent
sends an ackowledgement to the responding user agent through the SIP server, and a call is
established. At that point, a media session (for example, voice) is initiated.
To finishing the call, a similar process flow is followed. The initiating user agent sends a "Bye"
signal to the responding agent through the SIP server. The responding user agent confirms
with an “OK" signal, which results in termination of call.
1. Invite
2. Trying
3. Invite
5. Ringing
5. Ringing
User
Agent
Initiating
7. OK
SIP
Server
6. OK
User
Agent
Responding
8. ACK
9. ACK
Media Session
10. BYE
13. OK
11. BYE
12. OK
Figure 8-3 SIP flow diagram
8.4 Session objects
A SipApplicationSession object represents an application instance. It can contain a number of
protocol sessions and is used as a container for application data. A SipApplicationSession
serves two purposes. It provides storage for application data and correlates the number of the
protocol sessions.
Because containers manage session data, they need a mechanism for knowing when
SipApplicationSession objects are no longer in use and are therefore eligible for garbage
collection. The mechanism provided is known as SipApplicationSession invalidation. An
application session becomes invalidated in one of three ways:
򐂰 The SipApplicationSession expires and the container subsequently invalidates it.
򐂰 A servlet explicitly invalidates it by invoking the invalidate() method.
򐂰 A servlet marks the SipApplicationSession to be invalidated and the container invalidates
it when the SipApplicationSession is in the ready-to-invalid
80
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
A SipSession object represents a point-to-point SIP relationship between two user agents,
either as an established dialog or in the stage before a dialog is actually established. The
SipSession object can be obtained from a SipServletMessage by calling the getSession
method. The SipSession object cannot be explicitly created by the application. This is done by
container.
SipSession objects do not have a timeout value of their own, separate from that of the parent
SipApplicationSession. Rather, when the parent session times out, all child protocol sessions
time out with it.
In general, the lifetime of a SipSession object can be controlled in the following ways:
򐂰 The parent SipApplicationSession times out or is invalidated explicitly. This invalidates all
child protocol sessions.
򐂰 The application explicitly invalidates the SipSession using the invalidate() API.
򐂰 The application marks the SipSession to be invalidated
8.5 Dialogs and SIP session
A dialog is a form of SIP session that establishes a point-to-point relationship between two
user agents. It provides a context that faciliates the sequencing of messages between user
agents and the proper routing of requests between them. SIP session have four states:
򐂰
򐂰
򐂰
򐂰
INITIAL
EARLY
CONFIRMED
TERMINATED
8.6 SIP application development overview
This section will use an example to illustrate the steps required to build a simple SIP
application. We will create an application that allows the initiation and control of calls from a
Web interface. A call can be placed from a softphone on the user's system to a phone
controlled by an external VOIP network as shown in Figure 8-4 on page 82.
򐂰 A user with a Web browser is presented with a form where they enter a phone number
(toSipAddress) and port (toSipPort). A softphone is installed on the same system as the
browser. By entering the phone number and port, the user of this softphone is asking to
place a call to another number. The first user agent in Figure 8-4 on page 82 represents
the softphone code running on the user's system.
򐂰 The second user agent represents a VOIP system.
򐂰 A SIP server is running both the HTTP servlet and SIP servlet. This server is logically
between the two user agents in the diagram.
򐂰 When the Web user enters the form parameters, the call is established between the two
user agents.
Chapter 8. Working with SIP applications
81
SoftPhone
User
Agent
Web
Browser
VOIP
User
Agent
SIP
Server
HTTP GET
200 OK
SIP INVITE
SIP INVITE
HTTP GET
200 OK
200 OK
ACK
200 OK
ACK
HTTP GET
200 OK
BYE
200 OK
BYE
200 OK
Figure 8-4 SIP example
We will proceed in a sequential manner to create an application, using the following steps:
1. Create the SIP Application Project. To do this, create a J2EE Project that contains a SIP
module and a Java module. Configure the context root to include the servlet path, for
example:
http://application.server.example.com:9080/CEA/MyServlet
2. Create the SIP Servlet and HTTP Servlet. Create a SIP servlet by extending
javax.servlet.sip.SipServlet and overriding the parameters that you want to use. Create a
normal HTTP servlet by extending javax.servlet.Servlet. The HTTP servlet interacts with
the front-end and invokes the SIP services.
3. Write business logic for HTTP Servlet. When the HTTP servlet skeleton is ready, write the
code to initiate calls to a third-party application or PSTN.
a. Start with the HTTP servlet service code, as shown in Example 8-5. This code will
create a form with inputs that include the "to" host name and port. The form inputs are
toSipAddress and toSipPort. This is the number the SIP servlet will eventually establish
a call with.
Example 8-5 HTTP servlet service code
resp.setContentType("text/html");
resp.getWriter().print("CEA Sample Application <BR><hr>");
resp.getWriter().print("Call: <BR>");
resp.getWriter().print("<form>");
resp.getWriter().print("From (host): <input type=\"text\"
name=\"toSipAddress\">");
resp.getWriter().print(" Port: <input type=\"text\" name=\"toSipPort\">");
resp.getWriter().print("<input type=\"submit\" value=\"create call\">");
resp.getWriter().print("</form>");
82
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
b. Set up the SIP factory for further operations. The javax.servlet.sip.SipFactory interface
API provides access to create SIP requests and sessions from within the application.
This is done in the init() method of HTTP Servlet, as shown in Example 8-6.
Example 8-6 Set up the SIP factory
import javax.servlet.sip.SipFactory;
...
private SipFactory _sipFactory = null;
public void init() throws ServletException {
_sipFactory = (SipFactory)
getServletContext().getAttribute(SipServlet.SIP_FACTORY);
if (_sipFactory == null) {
System.out.println("HTTPCallHTTP: Error no SipFactory in context");
}
}
c. To initiate a call, you need access to a SipApplicationSession. WebSphere Application
Server enables access to the SipApplicationSession from the HttpSession. The
HttpSession can be cast to IBMSession. From IBMSession, you can get to
IBMApplicationSession, which can be cast to SipApplicationSession. See
Example 8-7.
Example 8-7 Access the SipApplicationSession
HttpSession httpSession=req.getSession();
IBMSession extSession = (IBMSession)httpSession;
IBMApplicationSession ibmAppSession = extSession.getIBMApplicationSession();
SipApplicationSession appSession = (SipApplicationSession)ibmAppSession ;
All application-related information that requires reuse between the HTTP Session and
the SIP Session needs to be stored in the HTTPApplicationSession,
(IBMApplicationSession in this case).
d. When the user initiates a call, the servlet takes the parameters input by the user and
creates the SIP URI's. When the port is ready, the SIP request is initiated. The "To"
address is the information obtained from the user input while the "From" address is
information obtained from the sytem of the originator. See Example 8-8.
Example 8-8 Servlet sends the invite request
SipServletRequest invite =
_sipFactory.createRequest(appSession,"INVITE",from,to);
SipURI requestUri = _sipFactory.createSipURI("user1",toAddressStr);
if (toPortStr != null)
requestUri.setPort(Integer.parseInt(toPortStr));
invite.setRequestURI(requestUri);
invite.send();
Chapter 8. Working with SIP applications
83
e. Add a display with the call information and an option to terminate the call, as shown in
Example 8-9.
Example 8-9 Add call information and option to terminate
resp.getWriter().print("Call to: ["+to.toString()+"] in Session. Click to
terminate" );
resp.getWriter().print("<form>");
resp.getWriter().print("<input type=\"hidden\" name=\"appid\" value=\"");
resp.getWriter().print(appSession.getId());
resp.getWriter().print("\">");
resp.getWriter().print("<input type=\"submit\" value=\"terminate\">");
resp.getWriter().print("</form>");
f. When a request to terminate the call is submitted, the SIP session for each UAS needs
to be terminated. See Example 8-10.
Example 8-10 Terminate the sessions
for (Iterator iter = appSession.getSessions("SIP"); iter.hasNext();) {
SipSession session = (SipSession) iter.next();
session.createRequest("BYE").send();
}
4. Write business logic for SIP Servlet. Prepare the SIP servlet. The SIP Servlet has multiple
calls. We will be dealing with doInvite and doBye.
a. Update the SIP deployment descriptor and map the SIP Servlet to the doInvite method
by making the changes shown in Example 8-11 to deployment descriptor.
Example 8-11 SIP deployment descriptor
<sip-app>
<app-name>com.ibm.sipservlet.app.ibmapp</app-name>
...
<servlet>
<servlet-name>IBMSipServlet</servlet-name>
<servlet-class>com.ibm.sipservlet.app.ibmsipservlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>IBMSipServlet</servlet-name>
<pattern>
<equal>
<var>request.method</var>
<value>INVITE</value>
</equal>
</pattern>
</servlet-mapping>
</sip-app>
84
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
b. Start with application initialization in the init() method. See Example 8-12.
Example 8-12 init() method
private SipFactory _sipFactory;
public void init() throws ServletException {
_sipFactory = (SipFactory) getServletContext().getAttribute(SIP_FACTORY);
if (_sipFactory == null) {
throw new ServletException("No SipFactory in context");
}
}
c. When initialization is done, the invite request can be sent. To do that, fetch all the
required parameters and get the applicationSession (SIP SipApplicationSession). See
Example 8-13.
Example 8-13 Send the invite request
SipURI to = (SipURI) req.getTo().getURI();
SipApplicationSession appSession =
resp.getSession().getApplicationSession();
SipServletRequest invite =
_sipFactory.createRequest(resp.getApplicationSession(),"INVITE",to,from);
SipURI requestUri = _sipFactory.createSipURI("user2",fromAddress);
if (fromPort != null)
requestUri.setPort(Integer.parseInt(fromPort));
invite.setRequestURI(requestUri);
d. In most SIP applications you have to establish two or more session contexts to manage
the corresponding dialog interaction. For that to happen, the content of one SIP
message has to be carried over to another. This is achieved using utility methods like
the one in Example 8-14.
Example 8-14 Copy the SIP message
void copyContent(SipServletMessage msg1, SipServletMessage msg2) {
try {
if (msg1.getContentType() != null) {
msg2.setContent(msg1.getRawContent(), msg1.getContentType());
}
} catch (IOException ex) {
log("Error: " + ex);
}
}
Chapter 8. Working with SIP applications
85
e. Set the corresponding parameters in the dialog. By setting the generated request, req,
of the invite object we have established the request association. As mentioned in step
d on page 85, you have to establish the dialog sessions so that content is copied from
one message to another. In addition, subsequent dialogs have to be informed about
where the request is coming from and its context so additional parameters like
"peer.req" are set. See Example 8-15.
Example 8-15 Set the dialog parameters
invite.setAttribute("peer.req", req);
SipSession dialog2 = invite.getSession();
dialog2.setAttribute("peer", dialog);
f. Send an invite to the UAS, as in Example 8-16.
Example 8-16 Send the invite
invite.send();
A similar process can be used to create and send the "BYE" request.
5. Deploy and run the application. To deploy SIP 1.1 applications to WebSphere Application
Server, the server must have the CEA feature pack installed. The server profile must be
augmented to be compatible with the CEA feature pack.
Deploying a SIP application is as easy as deploying a WAR application. From the IDE use
the application export feature to package the application as a SAR.
To export a SIP project into a SAR file from Rational Application Developer, perform the
following steps:
a. Right-click a SIP project folder and select Export from the pop-up menu.
b. Select SAR file in the Export window and click Next.
c. Complete the fields and click Finish.
With the application package ready, perform the following steps:
a. Launch the administrative console for the WebSphere application server and log in.
b. Select Application  Install new application.
c. Specify the context of the application, for example, CEACallapplication.
d. Upload the SAR file and go through the installation wizard.
Now that application is deployed to run the application, access application using a
standard URL in the browser:
http://host:port/CEACallapplication/CEACallapplication
To simplify this task use the WebSphere Application Server Toolkit (AST) or IBM Rational
Application Developer. In this example, Rational Application Developer is used.
86
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
8.7 Proxying SIP requests
Proxing is the process of acting on behalf of a proxied object or process. The two most
important reasons for employing a proxy are to offload tasks and to simplify the
implementation of end points. A SIP Proxy only participates in SIP message transmission.
After a session is established between two ends, subsequent transmission is between the two
end points only, without involving the proxy server. A proxy can be stateless or stateful. A
stateful proxy will have call context, can maintain transaction state, and can replicate a user
agent server request and response. A stateful proxy is used mainly to enhance service
requirements. A stateless proxy provides client anonymity, allows easier replication, and
provides high processing capacity.
8.7.1 ProxyBranch objects
While there are similarities between the HTTP servlet with the SIP servlet, there are many
differences in the way they are applied. Primary differences include where they are located
and how they are initialized. HTTP servlets execute on origin servers only and are concerned
only with responding to incoming requests. SIP servlets are typically located on proxy servers
and must be able to proxy incoming requests as well as respond to them directly.
Proxying is initiated and controlled through a Proxy object obtained from an incoming
SipServletRequest and its associated ProxyBranch object. There is at most one Proxy object
per SIP transaction, meaning that SipServletRequest.getProxy() will return the same Proxy
instance whenever invoked on the original request object or on any other message belonging
to that transaction.
The "Proxy" operation is controlled in the following ways :
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
recurse
recordRoute
parallel
supervised
proxyTimeout
addToPath
There are two ways in which an application can perform a proxying operation using the Proxy
object obtained from an incoming SipServletRequest:
򐂰 By calling proxyTo() method on the Proxy object and passing the URI(s) to proxy the
request to.
򐂰 By creating ProxyBranch object(s) from the Proxy and invoking startProxy() method on the
Proxy. Figure 8-5 on page 88 depicts the SIP proxy functionality of WebSphere Application
Server's converged container. As shown, the SIP container and HTTP Container share
session management, security, and other attributes. An application that includes SIP
servlets, HTTP servlets, and portlets can seamlessly interact with each other regardless
of the protocol. Tight integration in a converged container allows seamless failover and
traffic management. The Proxy Server is a stateless SIP proxy and HTTP reverse proxy
together. The Proxy server also can act as a standalone stateless SIP proxy in front of the
SIP container in the application server when no HTTP traffic is present. With the
converged proxy and converged container, session failover is done with affinity to the
application, enabling the HTTP and SIP sessions to be tied together automatically using
Proxy Filter Manager.
Chapter 8. Working with SIP applications
87
l te
rs
lte
rs
Fi
Fi
Pr
ox
y
xy
Pr
o
P
SI
P
H
TT
Proxy Filter Manager
HTTP Proxy
Pre-processor
HTTP
SIP Proxy
Pre-processor
SSL
TCP
SIP
UDP
Figure 8-5 Structure of SIP Proxy and HTTP handling in IBM WebSphere Application Server
88
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
A
Appendix A.
Sample code for the Web
services example
This appendix provides the sample code used in 6.6, “Development process” on page 54.
Example A-1 shows the code for CommWebServiceServlet.java.
Example A-1 CommWebServiceServlet.java
package com.ibm.ws.commsvc.webservice;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.HashMap;
import
import
import
import
import
import
import
javax.servlet.Servlet;
javax.servlet.ServletConfig;
javax.servlet.ServletException;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;
javax.servlet.http.HttpSession;
import com.ibm.ws.commsvc.webservice.impl.CallState;
import com.ibm.ws.commsvc.webservice.impl.CallStatus;
/**
* This class provides a front end that allows the browser/user to control
* a device by leveraging the CEA Web service interface. It starts with
* opening a session with that device where the status can be refreshed, a
* call can be made or ended, or the monitoring session can be closed.
*
* Once this application is installed on the same server where CEA is
* installed, the initial request to get the app running is as follows.
*
* http://cea_host:http_port/commsvc.ws.sample/CommWebServiceServlet
© Copyright IBM Corp. 2010. All rights reserved.
89
*/
public class CommWebServiceServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
// Name of the attribute to add to the HttpSession to track state.
// Storing a state object in the HttpSession is key to this application
// as it allows follow on requests in the same HttpSession to track
// down the status of the phone that is being monitored.
private static final String ATTRIBUTE_PHONE_SESSION = "PhoneSession";
// URI path info included in GET / PUT requests
// The servlet interaction is a bit REST-like, but only as a means
// to make the servlet simple and easy to understand.
private static final String PATH_MAKE_CALL
= "/makeCall";
private static final String PATH_END_CALL
= "/endCall";
private static final String PATH_GET_CALL_STATUS
= "/callStatus";
private static final String PATH_OPEN_SESSION
= "/openSession";
private static final String PATH_CLOSE_SESSION
= "/closeSession";
// Name of the Servlet and context root included in requests.
private static final String SERVLET_NAME = "CommWebServiceServlet";
public static final String CONTEXT_ROOT = "commsvc.ws.sample";
// Names of input form data presented in this application
public static final String PEER_ADDRESS_OF_RECORD = "peerAddressOfRecord";
public static final String ADDRESS_OF_RECORD = "addressOfRecord";
// HashMap of all PhoneSession objects keyed by the address of record.
// This is used to track down state when a notification arrives.
// While follow on browser requests can leverage the HttpSession to track
// down the correct PhoneSession object stored as an attribute, that same
// option isn't available when the WS-Notification arrives with an event
// that occurred on a phone. That's where this HashMap is useful. The
// notification includes the address of record of the phone, so that is used
// to track down the associated PhoneSession state object.
public static HashMap<String,PhoneSession> hmPhoneSessions = new
HashMap<String,PhoneSession>();
/**
* @see HttpServlet#HttpServlet()
*/
public CommWebServiceServlet() {
super();
}
/**
* @see Servlet#init(ServletConfig)
*/
public void init(ServletConfig config) throws ServletException {
}
/**
* This method is called when a GET request arrives. The path information is
* pulled off the URL and matched to the type of request being made so that
* the appropriate page can be returned.
90
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
* @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
response)
*/
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
PhoneSession phoneSession = null;
// Get the specific request from the path.
String pathInfo = request.getPathInfo();
if (pathInfo == null) {
pathInfo = "";
}
// The result text that will be sent back to the calling browser.
String result = null;
try {
// Match the request path to the available functions.
if (pathInfo.startsWith(PATH_END_CALL)) {
// The endCall button was pressed on the browser FORM.
// Get the HttpSession from the request.
HttpSession httpSession = request.getSession();
// Look for the PhoneSession object as an attribute of the
HttpSession.
phoneSession =
(PhoneSession)httpSession.getAttribute(ATTRIBUTE_PHONE_SESSION);
// End the call.
phoneSession.endCall();
// Sleep a bit to get the call ended so that the response includes
// status of the call having been shut down. It might not be done yet
in which
// case the refresh button on the resulting form can be used to try
again.
Thread.sleep(2000);
result = getStatusPage(phoneSession);
} else if (pathInfo.startsWith(PATH_GET_CALL_STATUS)) {
// The refresh button was pressed on the browser FORM.
// Get the HttpSession from the request.
HttpSession httpSession = request.getSession();
// Look for the PhoneSession object as an attribute of the
HttpSession.
phoneSession =
(PhoneSession)httpSession.getAttribute(ATTRIBUTE_PHONE_SESSION);
// Get the latest call status via the web service.
result = getStatusPage(phoneSession);
} else if (pathInfo.startsWith(PATH_CLOSE_SESSION)) {
// The closeSession button was pressed on the browser FORM.
// Get the HttpSession from the request.
HttpSession httpSession = request.getSession();
// Look for the PhoneSession object as an attribute of the
HttpSession.
phoneSession =
(PhoneSession)httpSession.getAttribute(ATTRIBUTE_PHONE_SESSION);
// Close the session.
phoneSession.closeSession();
// Clean out the session attribute so a follow on request starts
fresh.
Appendix A. Sample code for the Web services example
91
httpSession.removeAttribute(ATTRIBUTE_PHONE_SESSION);
// Present the initial page to open a new session.
result = getOpenSessionPage();
// Remove this PhoneSession from the hashMap
hmPhoneSessions.remove(phoneSession);
} else {
// Initial request to servlet with no path info. Offer to open a
monitoring session.
result = getOpenSessionPage();
}
} catch (Exception e) {
result = getErrorPage("Exception caught: " + e);
e.printStackTrace();
}
PrintWriter out = response.getWriter();
out.println(result);
}
/**
* This method is called when a POST is made from one of the web pages /
* forms returned from calling doGet(). This is where the requested action
* takes place.
* @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse
response)
*/
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
PhoneSession phoneSession = null;
// Get the specific request from the path.
String pathInfo = request.getPathInfo();
if (pathInfo == null) {
pathInfo = "";
}
// The result text that will be sent back to the calling browser.
String result = null;
try {
// Match the request path to the available functions.
if (pathInfo.startsWith(PATH_MAKE_CALL)) {
// The makeCall button was pressed on the browser FORM.
// Extract the target phone number (peer address of record)
String peerAddressOfRecord =
request.getParameter(PEER_ADDRESS_OF_RECORD);
// Ensure non null and non empty inputs.
if (peerAddressOfRecord == null ||
peerAddressOfRecord.trim().equals("")) {
result = getErrorPage("Invalid inputs: peerAddressOfRecord=" +
peerAddressOfRecord);
} else {
// Get the HttpSession from the request.
HttpSession httpSession = request.getSession();
// Get the PhoneSession object formerly saved as an attribute of
the HttpSession.
92
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
phoneSession =
(PhoneSession)httpSession.getAttribute(ATTRIBUTE_PHONE_SESSION);
// Make the call via the web service.
phoneSession.makeCall(peerAddressOfRecord);
// Sleep a bit to get the call set up so that the response includes
// status of the call having been set up. It might not be done yet
in which
// case the refresh button on the resulting form can be used to try
again.
Thread.sleep(2000);
// Return the latest status of the call.
result = getStatusPage(phoneSession);
}
} else if (pathInfo.startsWith(PATH_OPEN_SESSION)) {
// The openSession button was pressed on the browser FORM.
// Extract the address of record passed in on the form.
String addressOfRecord = request.getParameter(ADDRESS_OF_RECORD);
// Ensure non null and non empty inputs.
if (addressOfRecord == null || addressOfRecord.trim().equals("")) {
result = getErrorPage("Invalid inputs: addressOfRecord=" +
addressOfRecord);
// Fetch the initial page to open a session.
result = getOpenSessionPage();
} else {
// Extract the host and port of this servlet.
String localAddr = request.getLocalAddr();
int localPort = request.getLocalPort();
// Create an instance of the PhoneSession.
phoneSession = new PhoneSession(addressOfRecord, localAddr,
localPort, request.isSecure());
// Add this new PhoneSession to the array.
hmPhoneSessions.put(addressOfRecord, phoneSession);
// Make the call via the web service.
phoneSession.openSession();
// Get the HttpSession from the request.
HttpSession httpSession = request.getSession();
// Store the PhoneSession object as an attribute of the
HttpSession.
httpSession.setAttribute(ATTRIBUTE_PHONE_SESSION, phoneSession);
// Return the latest status.
result = getStatusPage(phoneSession);
}
} else {
// Unexpected request. Present initial page to open a session.
result = getOpenSessionPage();
}
} catch (Exception e) {
result = getErrorPage("Exception caught: " + e);
e.printStackTrace();
}
PrintWriter out = response.getWriter();
out.println(result);
}
Appendix A. Sample code for the Web services example
93
/**
* Update the static map of PhoneSession state objects based on a notification
* that was received.
* @param callStatus
*/
public static void updatePhoneSession(CallStatus callStatus) {
// Extract the address of record representing the phone associated with this
notification.
String addressOfRecord = callStatus.getAddressOfRecord();
// Search the static HashMap for the PhoneSession.
PhoneSession phoneSession = hmPhoneSessions.get(addressOfRecord);
if (phoneSession != null) {
// Found it. Update the object with the information in the notification.
phoneSession.updateState(callStatus);
} else {
throw new RuntimeException("Unable to find PhoneSession for " +
addressOfRecord);
}
}
/**
* Return a web page that provides status on a session monitoring a phone.
* Depending on the state of the phone, options are provided to make a new
* call, end an existing call, or close the monitoring session altogether.
* @param phoneSession - phone session state object for which status is
requested
* @return - String data that should be sent back to the browser
*/
private String getStatusPage(PhoneSession phoneSession) {
StringBuffer sbResult = new StringBuffer("");
if (null != phoneSession) {
// Found call information in the session.
sbResult.append("<HTML>\n");
sbResult.append("<BODY>\n");
sbResult.append("<H1>Phone Status</H1>\n");
sbResult.append("<UL>\n");
sbResult.append("<LI><B>Address of record:</B> " +
phoneSession.getAddressOfRecord() + "<BR>\n");
sbResult.append("<LI><B>Call status:</B> " + phoneSession.getCallState()
+ "<BR>\n");
sbResult.append("<LI><B>Caller:</B> " +
phoneSession.getCallerAddressOfRecord() + "<BR>\n");
sbResult.append("<LI><B>Callee:</B> " +
phoneSession.getCalleeAddressOfRecord() + "<BR>\n");
sbResult.append("<LI><B>Call ID:</B> " + phoneSession.getCallID() +
"<BR>\n");
sbResult.append("</UL>\n");
// Expose a button to get a call status update.
sbResult.append(createGetForm(PATH_GET_CALL_STATUS, "Refresh call
status"));
sbResult.append("<HR>\n");
// Expose a button to make a call if the phone is inactive
94
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
if
(phoneSession.getCallState().equals(CallState.CALL_STATUS_CLEARED.value())) {
sbResult.append("<FORM action=\"/" + CONTEXT_ROOT + "/" + SERVLET_NAME
+ PATH_MAKE_CALL + "\" method=\"post\">\n");
sbResult.append("Peer address of record: <INPUT type=\"text\" name=\""
+ PEER_ADDRESS_OF_RECORD + "\">\n");
sbResult.append("<INPUT type=\"submit\" value=\"Make call\">\n");
sbResult.append("</FORM>\n");
}
// Expose a button to end the call, if the call is active.
else if
(phoneSession.getCallState().equals(CallState.CALL_STATUS_ESTABLISHED.value())) {
sbResult.append(createGetForm(PATH_END_CALL, "End the call"));
}
// Expose a button to close the session.
sbResult.append(createGetForm(PATH_CLOSE_SESSION, "Close the session"));
sbResult.append("</BODY></HTML>");
} else {
sbResult.append("<HTML><BODY>\n");
sbResult.append("No session information found.\n");
sbResult.append("</BODY></HTML>");
}
return sbResult.toString();
}
/**
* Return a web page that presents a form to open a session. This has the
affect
* of registering for call notification.
* @return - String data that should be sent back to the browser
*/
private String getOpenSessionPage() {
StringBuffer sbResult = new StringBuffer("");
sbResult.append("<HTML>\n");
sbResult.append("<BODY>\n");
sbResult.append("<FORM action=\"/" + CONTEXT_ROOT + "/" + SERVLET_NAME +
PATH_OPEN_SESSION + "\" method=\"post\">\n");
sbResult.append("<H1>CEA Web Service Sample</H1><HR>\n");
sbResult.append("<H1>Open a session to monitor a phone</H1>\n");
sbResult.append("Phone address of record: <INPUT type=\"text\" name=\"" +
ADDRESS_OF_RECORD + "\"><BR>\n");
sbResult.append("<P>\n");
sbResult.append("<INPUT type=\"submit\" value=\"Open session\">\n");
sbResult.append("</FORM></BODY></HTML>");
return sbResult.toString();
}
/**
* Return a web page that shows an error occurred.
* @param error - String to be used in the error page returned
* @return - String data that should be sent back to the browser
*/
Appendix A. Sample code for the Web services example
95
private String getErrorPage(String error) {
StringBuffer sbResult = new StringBuffer("");
sbResult.append("<HTML>\n");
sbResult.append("<BODY>\n");
sbResult.append("<H1>Error</H1>\n");
sbResult.append("Details: " + error + "<BR>\n");
sbResult.append("Available options:\n");
sbResult.append(createGetForm(PATH_OPEN_SESSION, "Open a session"));
sbResult.append("</BODY></HTML>");
return sbResult.toString();
}
/**
* Utility method to create a form with the given action and description
* @param action - the path that will be added to the URL to determine the
action
* @param description - the label on the button of the form.
* @return - text that makes up a form
*/
private String createGetForm(String action, String description) {
StringBuffer sbResult = new StringBuffer("");
sbResult.append("<FORM action=\"/" + CONTEXT_ROOT + "/" + SERVLET_NAME +
action + "\" method=\"get\">\n");
sbResult.append("<INPUT type=\"submit\" value=\"" + description + "\">\n");
sbResult.append("</FORM>\n");
return sbResult.toString();
}
}
96
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Example A-2 shows the code for PhoneSession.java.
Example A-2 PhoneSession.java
package com.ibm.ws.commsvc.webservice;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.soap.AddressingFeature;
import javax.xml.ws.wsaddressing.W3CEndpointReference;
import
import
import
import
import
com.ibm.ws.commsvc.webservice.impl.CallState;
com.ibm.ws.commsvc.webservice.impl.CallStatus;
com.ibm.ws.commsvc.webservice.impl.CommWsRequest;
com.ibm.ws.commsvc.webservice.impl.Controller;
com.ibm.ws.commsvc.webservice.impl.ControllerService;
/**
* The purpose of this class is to control the state and actions taken related
* to a specific phone. A reference to this object is kept in the HttpSession
* and also a HashMap in the servlet code so it can be found in different
* contexts (servlet requests and WS-Notifications).
*/
public class PhoneSession {
// Reference to the web service.
private static Controller webService = null;
// This phone's address of record.
private String addressOfRecord = null;
// URL to contact in order to trigger a call notification (WS-Notification)
// - the host and port must be where the web service client resides
// - the context root much match that of the WAR including this web services
client
// - the name at the end must match the service name found in the associated
WSDL.
private String notifyCallback = null;
// While the openSession method must be called with the webService reference,
// follow up calls related to the same session need to use this. It allows
// for the web services calls to include a reference to an EPR (endpoint
// reference). This is critical for multiple reasons. First, it allows for
// web service interface to be simpler eliminating the need to pass a state
// object as a parameter in all follow up requests. The EPR itself has enough
// information for the web service to track it. It is also leveraged in a
clustered
// environment to ensure follow on requests go back to the same container
// monitoring the phone.
private Controller webServiceWithEPR = null;
// The current state of the call / phone.
private String callState = CallState.CALL_STATUS_CLEARED.value();
// When a call is active, the address of record for the party being called.
Appendix A. Sample code for the Web services example
97
private String calleeAddressOfRecord = null;
// When a call is active, the address of record for the party that made the
call.
private String callerAddressOfRecord = null;
// When a call is active, The call ID being used by this phone.
private String callID = null;
// The location of the web service.
private String webServiceLocation = null;
// Accessor methods
public String getAddressOfRecord() { return addressOfRecord; }
public String getCalleeAddressOfRecord() { return calleeAddressOfRecord; }
public String getCallerAddressOfRecord() { return callerAddressOfRecord; }
public String getCallState() { return callState; }
public String getCallID() { return callID; }
/**
* Get access to the web service. To prevent from doing this for each instance
* of this object, save the reference as a singleton.
* @param wsdlLocation - the location of the web service, a URL string
* @return the web service interface upon which methods may be called
* @throws Exception
*/
public static Controller accessWebService(String wsdlLocation) throws
Exception {
if (null == webService) {
// Access the web service client
URL url = new URL(wsdlLocation);
QName serviceName = new
QName("http://impl.webservice.commsvc.ws.ibm.com/", "ControllerService");
ControllerService service = new ControllerService(url, serviceName);
if (service != null) {
webService = service.getControllerPort();
}
}
return webService;
}
/**
* Constructor.
* @param addressOfRecord
*/
public PhoneSession(String addressOfRecord, String localAddr, int localPort,
boolean isSecure) {
// Set up the protocol string to use in the URLs.
String protocol = (isSecure) ? "https" : "http";
// Save the address of record representing the phone to be monitored.
this.addressOfRecord = addressOfRecord;
// Build the URL to be used for the WS-Notification callback.
this.notifyCallback = protocol + "://" + localAddr + ":" + localPort
+ "/" + CommWebServiceServlet.CONTEXT_ROOT
+ "/CeaNotificationConsumer";
98
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
// Build the URL to the local WSDL of the web service.
webServiceLocation = protocol + "://" + localAddr + ":" + localPort
+ "/commsvc.rest/ControllerService?wsdl";
}
/**
* This is called in order to start monitoring a phone
*/
public void openSession() throws Exception {
// Build the web service request object.
CommWsRequest wsRequest = new CommWsRequest();
wsRequest.setAddressOfRecord(addressOfRecord);
wsRequest.setNotifyCallback(notifyCallback);
// Access the web service.
webService = accessWebService(webServiceLocation);
// Call the web service to open the session.
W3CEndpointReference EPR = webService.openSession(wsRequest);
// Use the endpoint reference to create a new object to make web
// service calls on. The EPR includes information that allows the
// web service to map future requests to this session.
webServiceWithEPR = EPR.getPort(Controller.class, new
AddressingFeature(true));
}
/**
* This is called from doPost() in order to make a call given the
* form data that was posted.
* @param peerAddressOfRecord - the address of record of the device to receive
the call
*/
public void makeCall(String peerAddressOfRecord) throws Exception {
// Build the web service request object.
CommWsRequest wsRequest = new CommWsRequest();
wsRequest.setPeerAddressOfRecord(peerAddressOfRecord);
// Call the web service to make the call.
webServiceWithEPR.makeCall(wsRequest);
}
/**
* End a call via the web service.
*/
public void endCall() throws Exception {
// Call the web service to end the call.
webServiceWithEPR.endCall();
}
/**
* This is called from doGet() in order to stop monitoring a phone.
*/
public void closeSession() throws Exception {
// Call the web service to close the session.
webServiceWithEPR.closeSession();
}
Appendix A. Sample code for the Web services example
99
/**
* Update this phone session with new CallStatus information that arrived
* in a WS-Notification.
* @param callStatus
*/
public void updateState(CallStatus callStatus) {
callState = callStatus.getCallStatus().value();
// If the call state is cleared, null out any current call data.
if (callState.equals(CallState.CALL_STATUS_CLEARED.value())) {
calleeAddressOfRecord = null;
callerAddressOfRecord = null;
callID = null;
} else {
// Update this object with the latest call data.
calleeAddressOfRecord = callStatus.getCalleeAddressOfRecord();
callerAddressOfRecord = callStatus.getCallerAddressOfRecord();
callID = callStatus.getCallId();
}
}
}
100
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Related publications
The publications listed in this section are considered particularly suitable for a more detailed
discussion of the topics covered in this paper.
Online resources
These Web sites are also relevant as further information sources:
򐂰 WebSphere Application Server V7 Feature Pack for Communications Enabled
Applications home page
http://www-01.ibm.com/software/webservers/appserv/was/featurepacks/cea/
򐂰 WebSphere Application Server information center
http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.c
eafep.multiplatform.doc/info/welcome_nd.html
򐂰 Communications Enabled Applications blog
http://ibmcea.blogspot.com/
򐂰 SIP: Creating next-generation telecom applications:
http://www.ibm.com/developerworks/library/wi-sip.html
򐂰 IBM WebSphere Developer Technical Journal: Session Initiation Protocol in WebSphere
Application Server V6.1 - Part 1:
http://www.ibm.com/developerworks/websphere/techjournal/0606_burckart/0606_burc
kart.html
򐂰 IBM WebSphere Developer Technical Journal: Session Initiation Protocol in WebSphere
Application Server V6.1 - Part 2:
http://www.ibm.com/developerworks/websphere/techjournal/0608burckart/0608burc
kart.html#stepd
How to get Redbooks
You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications
and Additional materials, as well as order hardcopy Redbooks publications, at this Web site:
ibm.com/redbooks
Help from IBM
IBM Support and downloads
ibm.com/support
IBM Global Services
ibm.com/services
© Copyright IBM Corp. 2010. All rights reserved.
101
102
Getting Started with the WebSphere Application Server Feature Pack for CEA V1.0
Back cover
Getting Started with the
WebSphere Application Server
Feature Pack for Communications
Enabled Applications V1.0
Access
communication
systems from
business applications
Use widgets to add
telephony and Web
collaboration features
This IBM Redpaper provides information about the architecture and
implementation of the features in the IBM WebSphere Application
Server Feature Pack for Communications Enabled Applications,
V1.0 (referred to as the CEA feature pack). This paper is considered
an entry point into the information. Use this paper to learn what the
feature pack is, how you might use it to improve your customer's
experience on a Web site, and to get an idea of how it is
implemented.
®
Redpaper
™
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
Access
communication
services using Web
services
IBM Redbooks are developed
by the IBM International
Technical Support
Organization. Experts from
IBM, Customers and Partners
from around the world create
timely technical information
based on realistic scenarios.
Specific recommendations
are provided to help you
implement IT solutions more
effectively in your
environment.
For more information:
ibm.com/redbooks
REDP-4613-00