Setting up and using the communications enabled application samples

You can set up a single-server environment to use the computer telephony integration (CTI) and web collaboration capabilities of IBM® WebSphere® Application Server Version 8.5.

About this task

Set up your environment to demonstrate the communication-enabling capabilities of WebSphere Application Server.

Procedure

Install WebSphere Application Server.
1. Install WebSphere Application Server.
  See the installation topics in the documentation for additional information about installing WebSphere Application Server in your environment.
  Important: The setup procedure for the PlantsByWebSphere Ajax Edition for CEA application requires the EJBDeploy tool for pre-EJB 3.0 modules. When installing WebSphere Application Server, be sure to include this optional feature. If you are using an existing installation that does not include the EJBDeploy tool, use IBM Installation Manager to modify the installation to include the tool before proceeding. The samples were tested with WebSphere Application Server Version 8.0 and Version 8.5.
Download and extract the communications enabled application samples.
1. Download the CEASamples.zip file to a directory on your workstation: HTTPS or FTP (ftp://public.dhe.ibm.com/software/websphere/appserv/library/v80/samples/CEASamples.zip). You might create the /samples/cea directory path on your workstation and download CEA sample files to that directory path.
2. Extract the files into the directory of your choice.
Use the setup scripts to create an application server profile and set up the sample applications.
The samples package includes a set of scripts that you can use to create an application server profile and set up the applications on distributed platforms. You can also use the scripts to customize an existing application server profile. If you want to perform these tasks manually, proceed to the step to manually create an application server profile to host the sample applications.

Important: The setup procedure for the PlantsByWebSphere Ajax Edition for CEA application requires the EJBDeploy tool for pre-EJB 3.0 modules. When installing WebSphere Application Server, be sure to include this optional feature. If you are using an existing installation that does not include the EJBDeploy tool, use IBM Installation Manager to modify the installation to include the tool before proceeding.
1. Find the setupCEA.bat file that is located in the scripts directory of the CEA samples package. Complete the following steps to customize and run setupCEA.bat.
  1. In the setupCEA.bat file, customize the variables for your application server environment. See the comments included in the setupCEA.bat file for more information.
  2. At a command prompt, change to the scripts directory of the CEA samples package and run setupCEA.bat.
  3. Proceed to the step to verify that the CEA configuration settings are appropriate.
2. Find the setupCEA.sh file that is located in the scripts directory of the CEA samples package. Complete the following steps to customize and run setupCEA.sh.
  1. In the setupCEA.sh file, customize the variables for your application server environment. See the comments included in the setupCEA.sh file for more information.
  2. Run setupCEA.sh.
  3. Proceed to the step to verify that the CEA configuration settings are appropriate.
Manually create an application server profile to host the sample applications.
1. If necessary, start the Profile Management Tool.
2. After the Profile Management Tool window opens, click Launch Profile Management Tool.
3. Click Create.
4. After the Profile Creation wizard opens, define the following settings:
  1. Environment Type: Application server
  2. Profile Creation Option: Advanced profile creation
  3. Application Deployment: Deploy the administrative console and the default application. If you want, you can deploy the sample applications.
  4. Profile name and Location
    - Profile name: AppSrvCEA
    - Profile directory: Accept the value provided, or change the directory path if you use a different convention.
  5. Host and Node names
    - Node name: AppSrvCEANode01
    - Server name: server1
    - Host name: Your_host_name
  6. Administrative security: Define settings appropriate for your environment
  7. Security Certificate (Part 1): Accept the default settings
  8. Security Certificate (Part 2): Accept the default settings
  9. Port Values Assignment: Accept the values provided
    Attention: The SIP_DEFAULTHOST port is required when performing the following steps:
    
    Verify that the CEA configuration settings are appropriate
    
    Download, install, and configure the free Express Talk Basic softphone
    
    Download, install, and configure the free X-Lite softphone
    
    The WC_defaulthost port is required when performing the following exploration scenarios:
    
    Simulate customer service interactions to verify the setup and explore the basic features of the CEA widgets
    
    Simulate cobrowsing interactions to further explore the features of the CEA widgets
    
    Explore the CEA web service sample application
    
    Be sure to record these port values before proceeding.
  10. Windows Service Definition: Define settings appropriate for your environment
  11. Web Server Definition: Accept the default settings
  12. Profile Creation Summary: Click Create
5. After the profile is created, close the Profile Management Tool.
Manually install and start the sample IP PBX enterprise application.
The sample application is suitable for light testing only.
1. Start the application server.
2. Launch the WebSphere Application Server administrative console for your installation. Use the administrative console to install the application (commsvc.pbx.ear) that is located in the installableApps directory of the CEA samples package.
  1. Display the following page in the administrative console: Applications > New Application.
  2. Click New Enterprise Application.
  3. Specify the location of the EAR file, commsvc.pbx.ear.
  4. Click Next.
  5. Select the Fast Path option.
  6. Click Next.
  7. On the remaining pages, accept the default values, and click Next.
  8. On the summary page, click Finish to save the changes to the local configuration. Then click Save to save the changes directly to the master configuration.
3. Start the sample IP PBX application.
  1. Display the following page in the administrative console: Applications > Application Types > WebSphere enterprise applications.
  2. Select the commsvc.pbx application, and click Start.
  3. Verify that the sample IP PBX application is running.
Manually install and start the PlantsByWebSphereAjax for CEA sample application.
Important: The setup procedure for the PlantsByWebSphere Ajax Edition for CEA application requires the EJBDeploy tool for pre-EJB 3.0 modules. When installing WebSphere Application Server, be sure to include this optional feature. If you are using an existing installation that does not include the EJBDeploy tool, use IBM Installation Manager to modify the installation to include the tool before proceeding.
1. Using the WebSphere Application Server administrative console, define a Derby XA Provider.
  1. Display the following administrative console page: Resources > JDBC > JDBC Providers.
  2. Set the scope to Node=AppSrvCEANode01,server=server1.
  3. Click New.
  4. Specify the following properties:
    - Database type: Derby
    - Provider type: Derby JDBC Provider
    - Implementation type: XA Data source
    - Name: Derby Provider for PlantsByWebSphereAjax (XA)
  5. Click Next.
  6. On the summary page, click Finish to save the changes to the local configuration.
  7. Click Save to save the changes directly to the master configuration.
2. Using the WebSphere Application Server administrative console, create a data source and associate it with the new provider.
  1. Display the following administrative console page: Resources > JDBC > Data sources.
  2. Set the scope to Node=AppSrvCEANode01,server=server1.
  3. Click New.
  4. Specify the following properties:
    - Data source name: PLANTSDB
    - JNDI name: jdbc/PlantsByWebSphereAjaxDataSource
  5. Click Next.
  6. Choose Select an existing JDBC Provider.
  7. Choose Derby Provider for PlantsByWebSphereAjax (XA).
  8. Click Next.
  9. For the Database name, enter (exactly) ${APP_INSTALL_ROOT}/${CELL}/PlantsByWebSphereAjax.ear/Database/PLANTSDB
  10. Use this data source in container managed persistence (CMP).
  11. Click Next.
  12. On the remaining pages, accept the default values and click Next.
  13. On the summary page, click Finish to save the changes to the local configuration.
  14. Click Save to save the changes directly to the master configuration.
3. Prepare, install, and start the CEA PlantsByWebSphereAjax sample application
  1. Open a command window and change to the installableApps directory of the CEA samples package.
  2. Generate EJB deployment bindings (and a new EAR file); for example:
    - C:\Program Files\IBM\WebSphere\AppServer\bin\ejbdeploy.bat PlantsByWebSphere.ear C:\temp PlantsByWebSphere_Deployed.ear -dbvendor DERBY_V10
    - /opt/IBM/WebSphere/AppServer/bin/ejbdeploy.sh PlantsByWebSphere.ear /tmp PlantsByWebSphere_Deployed.ear -dbvendor DERBY_V10
  3. Using the WebSphere Application Server administrative console, install the application.
    1. Display the following administrative console page: Applications > New Application.
    2. Click New Enterprise Application.
    3. Specify the location of the new EAR file, PlantsByWebSphere_Deployed.ear.
    4. Click Next.
    5. Select the Fast Path option.
    6. Click Next.
    7. On the remaining pages, accept the default values and click Next.
    8. On the summary page, click Finish to save the changes to the local configuration.
    9. Click Save to save the changes directly to the master configuration.
  4. Using the WebSphere Application Server administrative console, start the application.
    1. Display the following administrative console page: Applications > Application Types > WebSphere enterprise applications
    2. Select the PlantsByWebSphereAjax application and click Start.
    3. Verify that the application started.
Manually install and start the web service sample application (commsvc.ws.sample.ear) that is located in the installableApps directory of the CEA samples package.
1. Using the WebSphere Application Server administrative console, install the web service sample application.
  1. Display the following page in the administrative console: Applications > New Application.
  2. Click New Enterprise Application.
  3. Specify the location of the web service sample EAR file, commsvc.ws.sample.ear.
  4. Click Next.
  5. Select the Fast Path option.
  6. Click Next.
  7. On the remaining pages, accept the default values and click Next.
  8. On the summary page, click Finish to save the changes to the local configuration. Then click Save to save the changes directly to the master configuration.
2. Using the WebSphere Application Server administrative console, start the application.
  1. Display the following page in the administrative console: Applications > Application Types > WebSphere enterprise applications.
  2. Select the commsvc.ws.sample application, and click Start.
  3. Verify that the application started.
Verify that the CEA and virtual host configuration settings are appropriate.
1. Display the following WebSphere Application Server administrative console page: Servers > Server Types > WebSphere application servers > server1 > Communications Enabled Applications (CEA). Then, verify that the following settings are appropriate, paying particular attention to the settings, Enable communications service and Port.
  - Communications Enabled Applications services
    - Enable communications service: Selected
  - REST interface
    - Context root: /commsvc.rest
    - Virtual host: default_host
    - Maximum hold time: 30 seconds
  - Telephony access method
    - Use SIP CTI (ECMA TR/87) gateway for telephony access: Selected
      
      Host name or IP address: localhost
      
      Port: Specify the SIP_DEFAULTHOST port of the application server. To determine the correct value, visit the following administrative console page: Servers > Server Types > WebSphere application servers > server1. Then display the Ports table that is located in the Communications category of settings.
      
      Protocol: TCP
      
      Extract user name from request: Cleared
      
      Superuser name: ceauser
2. Configure the virtual host default_host.
  Display the following administrative console page: Environment > Virtual hosts. Click the virtual host default_host. Next, click Host Aliases. Finally, ensure that appropriate host aliases exist for each of the following application server ports:
  - WC_defaulthost
  - WC_defaulthost_secure
  - SIP_DEFAULTHOST
  - SIP_DEFAULTHOST_SECURE
  To determine the correct value (number) for each port, display the following administrative console page: Servers > Server Types > WebSphere application servers. Click the name of the appropriate application server. Finally, display the Ports table that is located in the Communications category of settings.
3. If you modified any of the configuration settings, complete the following actions:
  1. Click OK to save the changes to the local configuration.
  2. Click Save to save the changes to the master configuration.
4. Restart (stop and start) the application server.
Download, install, and configure the free Express Talk Basic softphone.
To complete this set of tasks, you must know the host name or address and SIP_DEFAULTHOST port of the application server that is running the sample IP PBX application.
To view the port numbers assigned to a given server, first visit the following WebSphere Application Server administrative console page: Servers > Application servers > server_name, where server_name is the name of the application server; for example: server1. Then display the Ports table that is located in the Communications category of settings.
1. Download Express Talk Basic using the NCH Software site, https://www.nch.com.au/talk/be.html.
2. Run the Express Talk Basic setup file, talksetup.exe. Then accept the default installation settings.
3. After the installation completes, a Setup wizard opens. Use the first several pages of the setup wizard to define appropriate speaker and microphone settings. (In many cases, you can simply accept the default settings.)
4. On the SIP Details page of the Setup wizard, use the following account information to configure Express Talk Basic to serve as a phone for a customer.
  1. Full Friendly Display Name: Customer
  2. Server (SIP Proxy or Virtual PBX): host name or address of the application server; for example: localhost
  3. SIP Number (or User Name): Customer
  4. Password: Leave this field blank
5. Click Finish to save the settings.
6. If the application server is not using the default SIP_DEFAULTHOST port (5060), complete the following actions:
  1. On the main Express Talk Basic window, click the Options button.
  2. After the Options window opens, click the Lines tab.
  3. After the Lines page opens, click the Advanced Line Settings button.
  4. After the Advanced SIP Server window opens, select Use a different outbound server.
  5. In the Outbound Server field, enter hostname:port, where hostname is the host name or address of the application server, and port is the SIP_DEFAULTHOST port of the application server; for example: localhost:5061.
  6. Click OK to save the settings, and close the Advanced SIP Server Settings window.
  7. Click OK to save the settings, and close the Options window.
  Avoid trouble: If the softphone does not register with the IP PBX, ensure that the application server and the sample IP PBX application (commsvc.pbx) are running. Additionally, ensure that the SIP_DEFAULTHOST port is not being used by another application, such as an email application.
Download, install, and configure the free X-Lite softphone.
To complete this set of tasks, you must know the host name or address and SIP_DEFAULTHOST port of the application server that is running the sample IP PBX application.
To view the port numbers assigned to a given server, first visit the following WebSphere Application Server administrative console page: Servers > Application servers > server_name, where server_name is the name of the application server; for example: server1. Then, display the Ports table that is located in the Communications category of settings.
1. Download X-Lite from the CounterPath site, https://www.counterpath.com/x-lite.html.
2. Run the X-Lite setup file. Then accept the default installation settings (including the option to start X-Lite after the installation completes).
3. If you are using X-Lite 4.0, click Softphone > Account Settings. If you are using X-Lite 3.0, click menu in the softphone. In the menu that opens, select SIP Account Settings.
4. To configure X-Lite to serve as a phone for a customer service representative, add a new account with the following settings:
  1. User name: CSR
  2. Domain: Host name or address of the application server that is running the sample IP PBX application; for example: localhost
  3. Display name: CSR
  4. Register with domain and receive incoming calls: Selected
  5. If the application server is using the default SIP_DEFAULTHOST port (5060):
    1. Send outbound using the domain: Selected
  6. If the application server is not using the default SIP_DEFAULTHOST port (5060):
    1. Send outbound using the proxy: Selected
    2. Address: hostname:port, where hostname is the host name or address of the application server, and port is the SIP_DEFAULTHOST port of the application server; for example: localhost:5061.
  Avoid trouble: If the softphone does not register with the IP PBX, ensure that the application server and the sample IP PBX application (commsvc.pbx) are running. Additionally, ensure that the SIP_DEFAULTHOST port is not being used by another application, such as an email application.
Verify that the telephony system is functioning correctly.
1. Using the customer softphone, Express Talk Basic, enter sip:CSR@hostname,where hostname is the host name or address of the application server that is running the sample IP PBX application; for example: sip:CSR@localhost.
2. Click Dial.
3. After the customer service representative softphone (X-Lite) rings, click the green Answer button (on the customer service representative softphone).
4. After verifying that a connection is present, click the red Hang Up button on the customer phone or the End button on the customer service representative phone.
Simulate customer service interactions to verify the setup and explore the basic features of the CEA widgets.
- To complete this set of tasks, you must know the WC_defaulthost port of the application server that is running the PlantsByWebSphereAjax application.
  To view the port numbers assigned to a given server, first visit the following WebSphere Application Server administrative console page: Servers > Server Types > WebSphere application servers > server_name, where server_name is the name of the application server; for example: server1. Then display the Ports table that is located in the Communications category of settings.
- Before testing customer service interactions, you must verify that the ClickToCall widget is configured appropriately for your environment. First open the contactus.html file that is located in the following directory: profile_root/installedApps/<cellName>/PlantsByWebSphereAjax.ear/PlantsByWebSphere.war.
  Next, within contactus.html, locate the widgetNumber attribute (widgetNumber="sip:CSR@localhost"). If necessary, replace CSR@localhost with the SIP number (address) to be contacted when a click-to-call request is initiated. SIP phone numbers must be specified in the format sip:userName@hostName, where hostName is the host name or IP address of the IP PBX.
1. Start the customer and customer service representative softphones.
2. Acting as a customer service representative, register the CallNotification widget with the communications infrastructure.
  1. Start a new web browser instance and load the PlantsByWebSphereAjax for CEA home page, http://hostname:port/PlantsByWebSphereAjax/, where hostname is the host name or address of the application server, and port is the WC_defaulthost port of the appropriate application server; for example: http://localhost:9080/PlantsByWebSphereAjax/
  2. Click the Call Notification link.
  3. Within the CallNotification widget, enter sip:CSR@hostname, where hostname is the host name or address of the application server that is running the sample IP PBX application; for example: sip:CSR@localhost.
  4. Click the Start Call Notification button.
3. Acting as a customer, use the ClickToCall widget to call (contact) the customer service representative.
  1. Start a new web browser instance and load the PlantsByWebSphereAjax for CEA home page, http://hostname:port/PlantsByWebSphereAjax/, where hostname is the host name or address of the application server, andport is the WC_defaulthost port of the appropriate application server; for example: http://localhost:9080/PlantsByWebSphereAjax/
    Best practice: When completing this task on a single machine, you must use two separate web browsers from different vendors; otherwise, results are unpredictable. For example, do not attempt to use two tabs within the same instance of a given browser, or even two separate instances of the same browser; for example, Firefox. Always use two separate browsers from different vendors; for example, Firefox and Chrome, Firefox and Safari, or Safari and Chrome.
  2. Click the Contact Us link.
  3. Within the ClickToCall widget, enter sip:Customer@hostname, where hostname is the host name or address of the application server that is running the sample IP PBX application; for example: sip:Customer@localhost.
  4. Click the Call Me button.
4. Acting as the customer service representative, use the X-Lite softphone to answer the call.
5. Acting as the customer, use the Express Talk Basic softphone to answer the call.
6. Acting as the customer service representative, use the CallNotification widget to start a web collaboration session with the customer.
  1. Within the CallNotification widget, click Cobrowse.
7. Acting as the customer service representative, send a web page to the customer. Then verify that the customer received the page.
  1. Navigate to an appropriate page, and click Send Page.
  2. Verify that the page is displayed in customer's browser.
8. Acting as the customer service representative, set up the Collaboration Dialog to automatically send the customer each new web page that is viewed. Then verify that the customer automatically receives new pages.
  1. Within the Collaboration Dialog, click Follow Me and view several different pages in the site.
  2. Verify that the final page is displayed in the customer's browser.
9. Acting as the customer service representative, highlight an area of a page for the customer. Then verify that the area was highlighted correctly in the customer's view.
  1. Within the Collaboration Dialog, click Highlight.
  2. Move your mouse pointer across the page to view the areas of the page that can be highlighted.
  3. Click the area of the page that you want to highlight in the customer's browser.
  4. Verify that the same area of the page is highlighted in the customer's browser.
10. To end the collaboration session, complete the following steps in the web browser of the customer or the customer service representative:
  1. Click the Close icon that is located in the Collaboration Dialog.
  2. In the Cobrowse widget, click End Collaboration Session.
For more information about the sample application, see the supporting documentation that is provided in the PlantsByWebSphere directory of the CEA samples package in the CEASamples.zip file that you can download to a directory on your workstation from: HTTPS or FTP (ftp://public.dhe.ibm.com/software/websphere/appserv/library/v80/samples/CEASamples.zip).
Simulate cobrowsing interactions to further explore the features of the CEA widgets.
To complete this set of tasks, you must know the WC_defaulthost port of the application server that is running the PlantsByWebSphereAjax application.
To view the port numbers assigned to a given server, first visit the following WebSphere Application Server administrative console page: Servers > Server Types > WebSphere application servers > server_name, where server_name is the name of the application server; for example: server1. Then display the Ports table that is located in the Communications category of settings.
1. Using the Cobrowse widget, invite a second party to participate in a cobrowsing session.
  1. Start a new web browser instance and load the PlantsByWebSphereAjax for CEA home page, http://hostname:port/PlantsByWebSphereAjax/, where hostname is the host name or address of the application server, and port is the WC_defaulthost port of the application server; for example: http://localhost:9080/PlantsByWebSphereAjax/.
  2. Click the Cobrowse link.
  3. Within the Cobrowse widget, click Create.
  4. Copy the invitation link to the operating system clipboard.
2. Acting as the second party, join the cobrowsing session.
  1. Start a new web browser instance and load the invitation link.
    Best practice: When completing this task on a single machine, you must use two separate web browsers from different vendors; otherwise, results are unpredictable. For example, do not attempt to use two tabs within the same instance of a given browser, or even two separate instances of the same browser; for example, Firefox. Always use two separate browsers from different vendors; for example, Firefox and Chrome, or Chrome and Safari.
3. Acting as the first party, send a web page to the second party. Then verify that the second party received the page.
  1. Within the Collaboration Dialog, click Send Page.
  2. Verify that the page is displayed in the second party's browser.
4. Acting as the first party, grant control of page navigation to the second party.
  1. Within the Collaboration Dialog, click Grant Control.
5. Acting as the second party, set up the Collaboration Dialog to automatically send the first party each new web page that is viewed. Then verify that the second party automatically receives new pages.
  1. Within the Collaboration Dialog, click Follow Me and view several different pages in the site.
  2. Verify that the final page is displayed in the first party's browser.
6. Acting as the second party, highlight an area of a page for the first party. Then verify that the area was highlighted correctly in the first party's view.
  1. Within the Collaboration Dialog, click Highlight.
  2. Move your mouse pointer across the page to view the areas of the page that can be highlighted.
  3. Click the area of the page that you want to highlight in the first party's browser.
  4. Verify that the same area of the page is highlighted in the first party's browser.
7. To end the collaboration session and the call, complete the following steps in the web browser of either party:
  1. Click the Close icon that is located in the Collaboration Dialog.
  2. In the Call Notification or Click-To-Call widget, click End Call.
For more information about the sample application, see the supporting documentation that is provided in the PlantsByWebSphere directory of the CEA samples package in the CEASamples.zip file that you can download to a directory on your workstation from: HTTPS or FTP (ftp://public.dhe.ibm.com/software/websphere/appserv/library/v80/samples/CEASamples.zip).
Explore the CEA web service sample application.
To complete this set of tasks, you must know the WC_defaulthost port of the application server that is running the commsvc.ws.sample application.
To view the port numbers assigned to a given server, first visit the following WebSphere Application Server administrative console page: Servers > Server Types > WebSphere application servers > server_name, where server_name is the name of the application server; for example: server1. Then display the Ports table that is located in the Communications category of settings.
1. Start the customer and customer service representative softphones.
2. Start a new web browser instance and load the CEA web service sample page, http://hostname:port/commsvc.ws.sample/CommWebServiceServlet, where hostname is the host name or address of the application server, and port is the WC_defaulthost port of the application server; for example: http://localhost:9080/commsvc.ws.sample/CommWebServiceServlet.
3. After the CEA web service Sample page opens, enter sip:CSR@hostname in the Phone address of record entry-field, where hostname is the host name or address of the application server that is running the sample IP PBX application; for example: sip:CSR@localhost.
4. Click the Open session button to obtain control of the phone. A request is sent to the sample servlet, which calls the openSession web service API. It might take a few seconds to set up the session with the phone. A Phone Status page opens, presenting the following fields for monitoring and managing the phone: Address of record, Call status, Caller, Callee, and Call ID. You can click the Refresh call status button to obtain status updates that the sample servlet has received by way of WS-Notification.
5. In the Peer address of record entry-field, enter sip:Customer@hostname, where hostname is the host name or address of the application server that is running the sample IP PBX application; for example: sip:Customer@localhost.
6. Click the Make call button. The sample servlet invokes the makeCall web service API to create a call between the customer (sip:Customer@hostname) and the customer service representative (sip:CSR@hostname).
7. After the customer service representative (X-Lite) softphone rings, answer the call.
8. After the customer (Express Talk Basic) softphone rings, answer the call.
9. Click the Refresh call status button to view details about the call that is in progress.
10. Click the End call button.
  The sample servlet invokes the endCall web service API to end the call.
11. Finally, click the Close session button.
  The sample servlet invokes the closeSession web service API to terminate the phone monitoring session.

Results

You have successfully set up an environment to demonstrate the communication-enabling capabilities of this product.