Installation Notes for Java Server Pages

Installation Notes for Java Server Pages (JSP) Sample Applications

IMPORTANT!!! This SDK and these sample applications CANNOT be installed on a Cisco Unified Communications Manager server. They must be installed on a separate Web Application Server.

Cisco Unified Communications Manager Server Requirements:

1. Cisco Unified Communications Manager version 7.1(1) or later, although most apps will work with little or no modifications on older versions.

Java Application Server Requirements:

    1. Sun Java 2 Standard Edition (J2SE) Runtime or JDK
        Tested with version 1.4.2 - 1.3 versions should work, but they won't support HTTPS connections.

        The Sun JRE or JDK can be downloaded at: http://java.sun.com/j2se/1.4.2/download.html

    2. Java Server Pages (JSP) server meeting Servlet 2.3 and JSP 1.2 specifications
        Tested with Tomcat 4.1.24, but other Tomcat versions and other JSP servers meeting the above
        minimum requirements should work fine.

        Tomcat can be downloaded from: http://java.sun.com/products/jsp/tomcat/

    3. Sun Java Xerces2 XML Parser and Sun Java Networking and Directory (JNDI) extensions for J2SE
        Included in 4.1 Tomcat installation, but may need to be installed separately for other JSP servers

    4. CiscoIPPhoneSDK.jar must be in the CLASSPATH of the JSP server
        For example, if you're using Tomcat, %tomcat%\shared\lib\ is the best location, where %tomcat%
        is the Tomcat install directory.

For more information on how Tomcat loads Java classes, see:
http://jakarta.apache.org/tomcat/tomcat-4.1-doc/class-loader-howto.html

Installing the JSP sample applications:

You'll need to create a new JSP web application which uses the desired .jsp script.
The process of doing this is specific to your JSP server, but here are the steps for doing it on Tomcat:

Creating a new Tomcat JSP Application:

    - Copy the entire sample app directory (including subfolders) to the %tomcat%\webapps\ directory.
        This will place the JSP file(s) for the sample application into the web path of Tomcat.

        Example: Copy c:\CiscoIPServices\JSP\mconference to %tomcat%\webapps\mconference

Configuring the JSP sample applications:

1. Edit each individual .jsp file to customize any settings for your environment. If customization is required, it
will be clearly documented in the beginning of the .jsp file.

2. Read the requirements and caveats notes, if present, at the beginning of each .jsp file for detailed setup
instructions specific to the individual sample application.
This is an *IMPORTANT* step because many applications require specific Cisco Unified Communications Manager configuration !!!

Creating new Phone Services for the JSP sample applications:

In order to get these services to work with your Cisco IP Phone, open the Cisco Unified Communications Manager (CUCM) Web Administration page.
Click the "Feature" link and choose the "Cisco IP Phone Services" option.

Repeat the following steps for each service you want installed:

1. Service Name (ex. MConference)
2. Description (ex. MConference sample application)
3. URL (ex. http://<server ip>:8080/mconference/mconference.jsp)
4. Press the insert button
5. If Service Parameters are required for the Service, add those Parameters as specified by the individual application.

Open the CCMUser admin page on the CUCM and add the the services to that users
phone. Reset the phone when finished installing the services.

Press the "Services" button on the Cisco IP Phone to use the newly installed services.

Setting up secure HTTPS connections to the CUCM APIs:

Cisco Unified Communications Manager 4.1 and later supports HTTPS connections to some APIs.
Depending on CUCM version, some APIs require HTTPS and will not accept unencrypted connections.
See the CUCM API documentation for more details: http://developer.cisco.com

In an effort to simplify setup and configuration of this SDK, the HttpInitializer.java class disables authentication of the server certificate when making HTTPS connections.
This allows the SDK JVM to connect to secure CUCM APIs without requiring the CUCM's certificate to be installed in the VM's certificate store.

NOTE: Disabling server certificate validation is NOT recommended for production application deployments due to the inherent security risks involved – this should only be done for demo purposes.

Some Java application environments (such as WebSphere) may not allow the HttpInitializer class to disable server certificate verification (or security policy my require server certificate verification), so you may need to do one of the following:

1. Change the platform configuration to allow HttpInitializer to change the HTTPS defaults.
2. Change the source code for the Provider classes such that they only modify the behavior of specific HttpURLConnections, not the defaults.
3. Install the CUCM's certificate onto your application server (instructions below).

See the Javadocs for the HttpInitializer.java class for more detailed information.

Installing the CUCM certificate into the Sun JVM certificate store:

In order to create HTTPS connections to the CUCM server, the JVM must have the CUCM's certificate
in it's certificate store. The exact procedure of how to do that varies by JVM manufacturer and version, but here's an example
of how to obtain the certificate using Microsoft Internet Explorer and how to load the certificate into Sun's 1.4.2 JDK:

1. Open Internet Explorer and point your browser to the secure URL that your application is accessing – for example:
      https://yourCUCM/ccmadmin/reports/DeviceListX.asp
2. Internet Explorer will likely ask you if you want to trust the certificate, answer "Yes". It's possible that you may need to modify
    your browsers security settings to allow certificates from companies which aren't in the "trusted" list.
    You'll also be prompted to enter administrator accounts credentials to access the API.
3. Once you've connected (and you should see the XML response in the browser), double-click the secure "lock" icon in the
    bottom status bar of IE - this will open the Certificate information window.
4. Select the "Details" tab and click the "Copy to File" button and an export wizard will start.
5. Click "Next", select the "DER encoded binaryX.509" format and click next.
6. Enter the destination filename - you should save it into the JDKs security directory for convenience, for example:
          D:\jdk1.4.2\jre\lib\security\CUCM.cer
7. Open a 'cmd' window and change directories to the \jre\lib\security directory.
    Assuming \jre\bin is in your PATH, run the following command to insert the certificate into the JDK's 'cacerts' keystore:
          keytool -import -keystore cacerts -file CUCM.cer -alias CUCM
8. Keytool will prompt for the password for the 'cacerts' keystore - the default password is 'changeit'.
9. Keytool should show the details of the certificate and ask you to confirm the import - type "yes" and enter.
10. The certificate should now be added and this JDK should now allow https connections to CUCM.

ADDITIONAL NOTES:

- When creating a new Phone Service in CUCM for the JSP applications, the default Tomcat root path will be
%tomcat%\webapps. So your Phone Service URL will include the application directory and the script name.
The default web port number for Tomcat is 8080.

Example: http://yourappserver:8080/mconference/mconference.jsp

- Some sample apps will require the special #DEVICENAME# querystring parameter which tells CUCM to supply
the device name of the requesting phone to the script when it is called. In that case, the URL configured for the
IP Phone Service would look like:

http://yourappserver:8080/speeddials/speeddials.jsp?name=#DEVICENAME#