Administrative XML Web Service (AXL)

Java/JAX-WS Quickstart

Introduction

This sample application demonstrates how to create an Administrative XML (AXL) web service consumer client using the wsimport command that is part of Java 6. You can download the project and open it directly in Eclipse.  The following article walks through how to generate the consumer classes and call the AXL getPhone API.

This sample application performs the following:

  • prompts the user for the Cisco Unified Communications Manager host url or IP address
  • prompts the user for the admin user name and password
  • prompts the user to enter the device name for a device registered on the Cisco Unified Communications Manager.
  • calls the AXL getPhone method
  • displays the value of the product field that is returned in the getPhone response.

AXL Sample Application

brush:
Copy    $  Welcome to the Cisco AXL Sample APP.
    Host: cucm.test.com
    OS dmin Account: adminuser
    OS Admin Password: adminpassword

    Enter the name of the phone you want to retrieve information about.
    Phone Name: SEPE8B7480316D6
    Product=Cisco 6961
    $

Before You Begin

To complete this exercise, you will need access to the following tools.

  • Eclipse
  • Access to a Cisco Unified Communications Manager installation
  • Admin username and password for Cisco Unified Communications Manager
  • The name of a device registered with Cisco Unified Communications Manager
  • Java 6

Generating the Consumer Classes

AXL provides an extensive WSDL describing the requests and details of the web service, which can be consumed via wsimport to create native Java classes for making AXL requests.

Get the AXL WSDL

The AXL WSDL is included in the AXL SQL Toolkit download that is available in Cisco Unified CM.

  1. Log into the Cisco Unified CM Administration application.
  2. Go to Application | Plugins
  3. Click on the Download link by the Cisco CallManager AXL SQL Toolkit Plugin.
  4. The axlsqltoolkit.zip file contains the complete schema definition for different versions of Cisco Unified CM. The important files for each version are:
    • AXLAPI.wsdl
    • AXLEnums.xsd
    • axlmessage.xsd
    • axlsoap.xsd
    • axl.xsd

Create a Java Project in Eclipse

Next, we will create a new Java in Eclipse. This project will contain the classes that are generated by the wsimport command and our code that calls the AXL getPhone API.

  1. In Eclipse go to, File | New | Java Project

  2. Give your project a name. For this sample, we will use axl-demo.

  3. In the package explorer, you should see your new project, and there should be a src folder inside of your new project.

  4. Copy the schema folder from the axlsqltoolkit folder into your project at the same level as the src folder.

  5. You should now see the AXLAPI.wsdl and AXLSoap.xsd in your project in the schema/current folder inside of your new project.

  6. From the command line, cd to the directory of your project (axl-demo).

  7. Run the following command to generate the consumer classes.

    brush
    Copy    $ wsimport -keep -b schema/current/AXLSOAP.xsd -Xnocompile  -s src -d bin -verbose schema/current/AXLAPI.wsdl

    The parameters are as follows:

    • -keep keeps the generated files
    • -b specifies the location of the schema file
    • -Xnocompile specifies to NOT compile the generated sources. If you do not specify this option, you may run out of memory during the wsimport command.
    • -s specifies where to put the source files
    • -d where to place generated output files
    • -verbose Output messages about what the compiler is doing The last parameter is the location of the wsdl file.

  8. After running this command, you will see messages about parsing the wdsl and generating the classes.

  9. This will take a few minutes to complete.

  10. Now you should see two new generated packages (com.cisco.axl.api._8 and com.cisco.axlapiservice) in the src folder of your project.

  11. The generated consumer classes are in these packages.

We will create code in the next section that calls the generated classes and access the AXL getPhone API.

Demo.java

Next, we need to the code that will interact with the user and call the AXL getPhone API.

  1. Click on the src folder, and choose New | Package
  2. Name the new package com.cisco.axl.demo
  3. Right Click on the com.cisco.axl.demo package and choose New | Class
  4. Name the new class Demo.java
  5. Put the code from attached Demo.java into your class.

Calling the AXL getPhone API

The following code in Demo.java uses the generated classes to connect to the AXL service and make the getPhone request. You can use a similar pattern for calling any of the AXL APIs.

brush:
Copy    /**
   * Makes the getPhone request and displays some of the fields that are returned.
 */
private void getPhone() {

// Instantiate the wsimport generated AXL API Service client --
// see the wsimport comments in the class javadocs above
AXLAPIService axlService = new AXLAPIService();
AXLPort axlPort = axlService.getAXLPort();


// Set the URL, user, and password on the JAX-WS client
String validatorUrl = "https://"
    + Demo.ucHost
    + ":8443/axl/";


((BindingProvider) axlPort).getRequestContext().put(
    BindingProvider.ENDPOINT_ADDRESS_PROPERTY, validatorUrl);
((BindingProvider) axlPort).getRequestContext().put(
    BindingProvider.USERNAME_PROPERTY, Demo.ucAdmin);
((BindingProvider) axlPort).getRequestContext().put(
    BindingProvider.PASSWORD_PROPERTY, Demo.ucPswd);

// Create a GetPhoneReq object to represent the getPhone request and set the name of the device
//to name entered by user
GetPhoneReq axlParams = new GetPhoneReq();
axlParams.setName(phoneName);

//Make a call to the AXL Service and pass the getPhone request
GetPhoneRes getPhoneResponse = axlPort.getPhone(axlParams);

//display information returned in the response to the user
Demo.informUser("Product=" + getPhoneResponse.getReturn().getPhone().getProduct() + "%n"
        + getPhoneResponse.getReturn().getPhone().getLoadInformation().getValue() + "%n");
}

Running the Sample Project

After you have generated the classes and added the code to Demo.java in your project, you are ready to run the sample and connect to your Cisco Unified CM.

You will need to have the following information:

  • The IP address or hostname for your Cisco Unified CM
  • The admin user id and password.
  • The device name for a phone registered with the Cisco Unified CM.

Adding the Cisco Unified CM SSL certificate to your keystore

Administrative XML (AXL) uses HTTPS, so you need to install the UC applications SSL certificate into your local keystore in order to run the sample app.

Download the Cisco Unified CM SSL Certificate

You can download the certificate from the UC manager using your browser. Here are the steps to do so using Firefox.

  1. In Firefox, go to https://<cucm-host>:8443/axl/
  2. Login with the Unified CM admin credentials.
  3. In your browser address window, you will see a small lock icon
  4. Click on the lock.
  5. Click more information.
  6. Click View Certificate
  7. Click Details
  8. Click Export.
  9. Save the certificate into a known place on your local machine.

Add the certificate to your java keystore

You can run the following command from the command line to add the certificate file to your local keystore.

brush:
Copy    $ JAVA_HOME/bin/keytool -import -alias <some descriptive name> -file <certificate file> -keystore <path to keystore>

For Windows/Linux

The keystore is located here:  $JAVA_HOME/jre/lib/security/jssecacerts

For Mac OS

The keystore is located here: $JAVA_HOME/lib/security/jssecacerts

and JAVA_HOME is located here: /System/Library/Frameworks/JavaVM.framework/Versions/<your version>/Home

Run the Sample Project

From the command line:

  1. Change to the directory that you created for this project (axl-demo)

  2. Run the following command:  

    brush:
    Copy    $ java -cp .  com.cisco.axl.demo.Demo

  3. Enter the IP or host name for your Cisco Unified CM.

  4. Enter the Admin user id.

  5. Enter the Admin password.

  6. Enter the device name of the registered phone.

  7. The program will display the Product information for that registered device.

If you encounter issues running the sample project, you may want to examine the AXL logs from Cisco Unified Communications Manager.

Next Steps

  • You can expand the sample and experiment by calling additional Administrative XML APIs.
  • To explore the AXL APIs that are available, view the AXL Schema specification.
  • Also, take a look at some common AXL API Examples Request/Response pairs.
Next