Perform Web GUI Administration and Configuration with the AXL API

The AXL Philosophy and Purpose

We, as programmers, often look at an API with wild dreams about building dazzling user-facing applications that inspire jaw-dropping amazement. That’s just how we’re built. And the AXL API has the power to let you do that.

One word… DON’T.

AXL is not an API for user-facing applications. It’s an administration and configuration API. You don’t want to push an end-user application built on AXL to 1,000 users. And if you do, you’re going to have a bad time.

Think of AXL as a programmatic way to perform web GUI administration and configuration tasks. For example, in the web GUI, you add an end user this way.

1. Select the User Management menu

2. Select End User

3. Click on +Add New

4. Fill out the form

5. Save.

Now, programming that might seem silly and more work than using the web GUI. But think of it this way. You have a text file with a list of names, email addresses, phone numbers, assigned company phone extension and other personal data of new employees. Now you can write an application that reads the file and creates and configures an end-user account for each of the persons and creates and configures lines and phones entries for them. That’s automating an administration and configuration task in a way that makes your life as an administrator easier.

The Basics

AXL is a SOAP-based API. There’s no REST for the wicked here.

The most often used AXL APIs fall into the following groups:

1. addSomething (e.g., add a phone)

2. getSomething (e.g., get a phone’s info and settings)

3. updateSomething (e.g., change a phone’s info and settings)

4. applySomething (e.g., apply the changes you made for the phone)

5. removeSomething (e.g., remove a phone)

6. listSomething (e.g., list all phones)

There are a few other AXL APIs not in those groups that you’ll need at times, but those are the most frequently used operations.

Getting Started: Preparation

The best way to get familiar with AXL is to use a free, open-source tool called SoapUI. SoapUI makes it easy to experiment with the AXL API. But first, you need to download the files you’ll use with SoapUI.

Log into Call Manager as an administrator. Under the Application menu, select Plugins.

Click the Find button (not shown in this screen shot). The first item is the Cisco AXL Toolkit. Click on Download and save it somewhere.

The saved file should look like this:

Open the zip file to see its contents

Open the schema directory.

Pick the version of Call Manager you are using. In this sample, we’ll pick current.

Copy the three files above to a working directory. I chose C:\SOAP.

Download and install the open-source SoapUI from this page. You’re done with preparation. Now, it’s time to create an AXL project to play with the API.

Set Up a SoapUI AXL Project

Click on the File menu and choose New SOAP Project.

Pick a name for your project. Set the Initial WSDL to point to the AXLAPI.wsdl file you saved to a working directory earlier. Click OK.

In the left column, you should see this (assuming you used the name New AXL Test, otherwise look for the name you chose).

Right click on AXLAPIBinding and select Show Interface Viewer. You should see this Dialog Box.

Click on the Service Endpoints tab and you’ll see where you can enter information for AXLAPI binding.

Type what you see in the Endpoint field, except point to your server where it says YOURSERVER. Assuming it’s safe for your work environment to do, enter your Administrator username and password in the appropriate fields. You can create an Administrator account in Call Manager specifically for use with the AXL API, or you can use your primary Administrator account.

You can close this dialog box now.

Now let’s play with one of the requests. In the left column, find listPhone and click on its plus sign. Then double-click on Request 1. You should see all the XML for this request pop up in a new dialog.

The listPhone request has a few potential hangups that are good to learn how to avoid. Any listSomething request is going to return, well, a list of things. Scroll down to the bottom of the request XML and you’ll see these options. These give you the option to skip a number of results, or define the starting point. We don’t want to mess with those options right now, so select them and delete them.

At the top, look for what I have selected here, select it and delete it. This attribute can be useful, and you don’t always have to delete it, but in this case, you’ll need to remove the ‘sequence=”?”’ for the request to work properly.

There’s one more thing. Get rid of what you see selected in this screen shot. Select it and delete it.

There are way too many values to specify, so let’s chop down the request to look like this. Make sure to put a percent sign in the <name></name> tag. This is a wild card, which means it will list ALL the phones. You want to start simple, so this is a simplified listPhone operation.

Now’s the time to try it out. Click on the green “run” icon in the upper left. You should see the right side of the request change to this:

This is an unfortunate bug in the current version of SoapUI. It should show you the XML response by default, but it instead shows you raw information. Until the app is fixed, you’ll have to click on the upper left XML tab to view the response.

The response might look something like this:

With that, you now have enough basic knowledge to experiment with any of the AXL APIs. Hey now, you’re an all-star, get your game on, go play.

Programming Tip

And if you really want to run with the big boys, here’s a tip for running multiple AXL request sequentially. Every time you make an AXL request, Call Manager launches a Tomcat session. When you make many requests in a row, Call Manager will launch multiple Tomcat sessions, which use up CPU and RAM.

Here’s a way around that. At the bottom of the response, open up the headers and you’ll see a cookie named JSESSIONID and its value.

If you set the JSESSIONID cookie and use the same value for your next AXL request, Call Manager will re-use the Tomcat session instead of launching a new one.

What to Avoid and Common Mistakes

Many requests have a list of optional search parameter tags, commonly <name> and <uuid>. You will usually have to choose one and delete the others.

As logical as it may seem, you can’t perform a getPhone, change some values, and then copy and paste the modified XML into an updatePhone request. getPhone and updatePhone XML tags are not mirror images.

Be careful when using APIs that give you direct access to the Call Manager database, like executeSqlQuery. Complicated joins may be clever, but they can also suck up CPU and memory the size of a spy balloon, and that eats into the performance of every other operation.

Source: cisco.com