This how-to illustrates using the Serviceability AXL SOAP service with Apache Axis to generate a simple HTML-based report of phones/devices in the Unified Communications Manager cluster, listing IP address, logged-in user and registration status.

Unified Communications Manager version: 7.0(1)
Application Server/Development Environment:

Operating System: Ubuntu Linux 8.10 (Desktop)
Web Server: Tomcat 6 (tomcat6-admin)
Java SDK: Sun Java 1.6 JDK (sun-java6-jdk)
IDE: Sun Netbeans 6.1 (netbeans)
Web-services Library: Apache Axis 1.2 (libaxis-java)

Note: Serviceability AXL is a standards-compliant API that can be accessed from many different kinds of platforms. Cisco formally supports the interface at the XML/HTTP interaction point (http://developer.cisco.com). Specific OS/server/library/platform configuration or implementation issues are outside the scope of Cisco support. This how-to is provided as-is...community help and feedback may be available via the developer.cisco.com forums.

Tomcat Server Setup

From a fresh install of the OS, the following configuration tasks were performed. Note that several of these settings effect security, and may not be appropriate or optimal for production systems. Many of the paths and files shown are specific to Ubuntu 8.10 and may vary according to the specifics of a given system's OS/JVM/config.

• Verify the Tomcat manager/admin components (tomcat6-admin) are installed. This allows Netbeans to auto-deploy the JSP project.
• A Tomcat user with the custom roles "manager" and "admin" needs to be created. On Ubuntu this file is /etc/tomcat6/tomcat-users.xml:

<role rolename="manager"/>
<role rolename="admin"/>
<user username="tomcat_user" password="secret" roles="manager,admin"/>

• Restart Tomcat and use Firefox to verify the Tomcat user can access the "manager webapp" link at http://<Tomcat-IP>:8080
• The self-signed certificate present on the UCM Publisher needs to be imported into the Sun Java certificate key store in order for Tomcat to connect to AXL via SSL
  • Download the UCM cert file
    • Check Firefox Edit/Preferences/Advanced/Encryption/View Certificates and remove any certificate that may already be present for the UCM server: e.g. <UCM701-IP>:8443
    • Reopen Firefox and navigate to https://<UCM701-IP>/ccmadmin, a certificate warning should appear
    • Export the certificate file: Add Exception/Get Certificate/View/Details/Export - leave format as (PEM) and note the filename and download location
  • Import the UCM certificate into the key store using keytool. "-file" is the certificate file downloaded above, for example 'UCM701-IP'. The default Sun Java keystore password is "changeit":

sudo keytool -import -alias UCM701-IP -file <path/to/UCM701-IP> -storepass changeit -keystore /usr/lib/jvm/java-6-sun/jre/lib/security/cacerts

• Grant Tomcat webapps permission to connect to outside servers via Java sockets. On Ubuntu this policy file is /etc/tomcat6/policy.d/04webapps.policy:

permission java.net.SocketPermission "*","connect";

Note, this gives the "connect" permission to all Tomcat webapps for any target server. You may want to tighten this down: http://tomcat.apache.org/tomcat-6.0-doc/security-manager-howto.html.

• Be sure to restart Tomcat.

Netbeans Setup

Configure the Netbeans Tomcat server settings, so Netbeans can auto-deploy

• Install the Netbeans Tomcat plugin: Tools/Plugins/Available
• Add the server: Tools/Servers/Add Server/Tomcat 6.0/
  • Catalina Home: /usr/share/tomcat6
  • Private Configuration Folder (yes)
  • Catalina Base: /var/lib/tomcat6
  • Username/password should be the Tomcat user created above. "Create user" unchecked.

JSP Project Code

The first step in creating the project code is to use Axis to automaticaly generate Java classes which encapsulate all the backend tasks associated with using the RisPort SOAP service.

• Download the RisPort.wsdl from UCM via browser: https://<UCM701-IP>/realtimeservice/services/RisPort?wsdl
• Generate the java stubs with WSDL2Java:

java -cp /usr/share/java/axis.jar:/usr/share/java/commons-logging.jar:\
/usr/share/java/commons-discovery.jar:/usr/share/java/jaxrpc.jar:/usr/share/java/wsdl4j.jar \
org.apache.axis.wsdl.WSDL2Java <path/to/RisPort.wsdl>

The output (ignore any warnings) will be a package folder tree 'com' in the current directory - i.e. ./com/cisco/schemas/ast/soap/

We are now ready to create the Netbeans project.

• Create a new web/web application project, for example 'JSPServiceability'. The default settings are fine, just make sure the server is the Tomcat 6.0 set up earlier. If Netbeans and Tomcat are working, you should be able to run the empty project, and see Firefox open to a 'Hello World' index.jsp page.
• Place the RisPort package folder tree in the src/java folder of the project: i.e. ~/NetbeansProjects/JSPServiceability/src/java/com/cisco/schemas/ast/soap.
• In the Projects panel, add the following Axis libraries from /usr/share/java: axis.jar, jaxrpc.jar, commons-logging.jar, commons-discovery.jar, wsdl4j.jar

• Replace the contents of index.jsp with the following code:

Download index.jsp

<%--
    Document   : index
    Created on : Feb 22, 2009, 1:34:02 PM
    Author     : dstaudt
--%>
<%@ page contentType="text/html" pageEncoding="UTF-8" %>
<%@ page import="com.cisco.schemas.ast.soap.*,org.apache.axis.client.*" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>Serviceability AXL - RisPort: All Devices</title>
    </head><%
        // CHANGE the following three strings for your UCM environment
        String risURL = "https://<CM701-IP>/realtimeservice/services/RisPort";
        String axlUser = "Administrator";
        String axlPassword = "cisco!123";

        RISService service = new RISServiceLocator(); // Instantiate the Axis Service object
        RisPortType rport = service.getRisPort(new java.net.URL(risURL)); // get the binding for RisPort

        ((Stub) rport)._setProperty(Call.USERNAME_PROPERTY, axlUser); // If we cast rport as an Axis Stub class
        ((Stub) rport)._setProperty(Call.PASSWORD_PROPERTY, axlPassword); // we can set the HTTP basic auth credentials

        //The following single element array of SelectItem '*' matches all devices
        //To search for specific devices, fill this array with device names
        //Note selectCmDevice will only return max 200 devices.  In a real deployment
        //an app might use Admin AXL to get a list of device names
        //then execute selectCmDevice multiple times querying up to 200 devices at a time.
        //Additional note, unique devicenames can be returned more than once if they have registered
        //to more than one node in the past
        SelectItem[] items = {new SelectItem("*")};

        //The general selection criteria goes in a CmSelectionCriteria object
        CmSelectionCriteria cmSelectionCriteria = new CmSelectionCriteria(
                new org.apache.axis.types.UnsignedInt(200), //Max returned devices
                "Any", //Class of device e.g. "Phone"
                new org.apache.axis.types.UnsignedInt(255), //Model 255=Unknown, see typemodel in the AXL DataDict
                "Any", //Status, e.g. "Registered"
                "", //UCM node server name
                "Name", //CmSelectionCriteria items are device names
                items);
        SelectCmDeviceResult cmselectresult = null;
        try {
            // Make the AXL request
            cmselectresult = rport.selectCmDevice(new javax.xml.rpc.holders.StringHolder(""), cmSelectionCriteria);
        } catch (Exception e) {
            out.println("Error: " + e.getMessage());
        }
        if (cmselectresult != null) {
            int devicesFound = cmselectresult.getTotalDevicesFound().intValue(); //Find out how many devices found
%>
    <body>
        Total Devices Found:  <%= devicesFound%>
        <table border="1" align="left" cellspacing="1" cellpadding="1">
            <tr>
                <td>Name</td>
                <td>IP Address</td>
                <td>Model</td>
                <td>E/M User</td>
                <td>Status</td>
            </tr><%
        if (devicesFound > 0) {
            //If some devices are found, output them in an HTML table
            CmNode[] nodes = cmselectresult.getCmNodes(); // Get the array of UCM nodes
            for (int i = 0; i < nodes.length; i++) {
                CmDevice[] devices = nodes[i].getCmDevices(); //Get the array of devices for this node
                for (int j = 0; j < devices.length; j++) {%>
            <tr>
                <td><%= devices[j].getName()%></td>
                <td><%= devices[j].getIpAddress()%></td>
                <td><%= devices[j].getModel()%></td>
                <td><%= devices[j].getLoginUserId()%></td>
                <td><%= devices[j].getStatus()%></td>
            </tr><%
                }
            }
        }%>
        </table>
    </body><% }%>
</html>

• Be sure to update the strings at the beginning of index.jsp with your actual UCM URL and user credentials. The credentials should be a UCM application user, with role 'Standard AXL API Access'

At this point you should be able to successfully run the project. Netbeans will automatically package the project .war file, deploy it to Tomcat, and open a Firefox instance with the project URL.

Download the full Netbeans project files: JSPServiceability.zip