Is it possible using AXL API query to get all the endpoints IP addresses registered on CUCM?

snikamvyopta · ‎02-02-2017

Hello,

We are already using AXL API to get the Devices, Users data etc.

However, I am not able to find any AXL API which will give all the IP addresses for all the devices / endpoints registered to the call manager.

Is it possible?

If not, which API should we use to achieve this? For example: RisPort, JTAPI etc.

Thanks,

Seema

dstaudt · ‎02-02-2017

RisPort is the API to look at for this.

Also via SNMP, if you prefer to go old school...

snikamvyopta · ‎02-03-2017

Thank you.

But, I cannot get it working for some reason using RisPort70.wsdl in SoapUI.

Receiving the following error:

Error: This request requires HTTP authentication.

https://<>:8443/realtimeservice2/services/RISService70

The API request and response are as below:

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">

<soapenv:Header>

</AstHeader>

</soapenv:Header>

<soapenv:Body>

<soap:SelectCmDevice soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<NodeName xsi:nil="true"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

</CmSelectionCriteria>

</soap:SelectCmDevice>

</soapenv:Body>

</soapenv:Envelope>

API response:

<html>

<head>

<title>Cisco System - Error report</title>

</head>

<body>

</div>

<div id="content-header">HTTP Status 401 -</div>

<p>

Status report

</p>

<p>

<b>message:</b>

</p>

<p>

<b>description:</b>

This request requires HTTP authentication.

</p>

</div>

</body>

</html>

dstaudt · ‎02-03-2017

Make sure the CUCM user whose credentials are being used has the correct access permissions, as shown here: https://developer.cisco.com/site/sxml/learn/getting-started/risport/

Also make sure you have configured soapUI to send Basic Authentication credentials for the request:

snikamvyopta · ‎02-06-2017

Thank you, it didn't work because the required roles were removed for the application user. The roles are re-added and I am able to get the valid response.

I have few additional questions which I could not find the answers for, in the documentation.

Q. What if the organization has more than 1000 devices registered on the call manager? I do not see any way to do the paging to get all the devices.

The documentation link I am referring to: Cisco Unified Communications Manager XML Developers Guide, Release 9.0(1) - Serviceability XML API [Cisco Unified Commu…

Maximum Devices Specification

Specifies the maximum number of devices for which information can be returned in a search. In Unified CM release 9.0(1) t he maximum number is 1000. Prior to Unified CM release 9.0(1) the maximum number was 200.

<MaxReturnedDevices xsi:type="xsd:unsignedInt">1000</MaxReturnedDevices>

Q. Is the IP returned for any device which has the status as UnRegistered, is the last known IP address of that device?

Are there any other conditions where an IP returned is not the current IP address for that device?

dstaudt · ‎02-06-2017

If a record shows UnRegistered, then the IP shown is the IP in effect when the registration occurred. If there is only one record and it shows UnRegistered, then yes: that would be the last known IP of the device. However, note multiple records can be returned if the device registered with more than one CUCM node. Check the record timestamps to make sure you are considering the latest record.

Re accessing bulk results, see the section "Using RisPort70 With Bulk Requests" in the developer guide:

Using RisPort70 With Bulk Requests

Applications using RisPort70 to perform queries on large numbers of devices, for example in order to update a devicename to IP address lookup table, need to balance:

Request rate throttle (15 requests per minute maximum)
The number of devices per request (up to 1000)
The possibility of duplicate records (from selectCmDevice)
Truncated results if more than 1000 results returned
Keeping device state information as up-to-date as possible

Obtain the right balance by testing and observation of Cisco Unified CM system performance, for example via the RTMT tool.

<!-- Example: Multiple `item` elements --> <soap:SelectBy>Name</soap:SelectBy> <soap:SelectItems> <soap:item> <soap:Item>IPCMRAEU5UCM5X7</soap:Item> </soap:item> <soap:item> <soap:Item>IPCXYZAU4UCM4X3</soap:Item> </soap:item> </soap:SelectItems>

Applications can perform bulk query operations by providing multiple Item elements in the SelectItems list, see the XML code sample.

<!-- Example: wildcard, partial Name match --> <soap:SelectBy>Name</soap:SelectBy> <soap:SelectItems> <soap:item> <soap:Item>IPC*</soap:Item> </soap:item> </soap:SelectItems>  <!-- Example: wildcard, "all" Name match --> <soap:SelectBy>Name</soap:SelectBy> <soap:SelectItems> <soap:item> <soap:Item>*</soap:Item> </soap:item> </soap:SelectItems>

Or use the * wildcard to return partial SelectItems matches or “all” devices (not supported with selectCmDeviceExt). See the XML code sample.

The application can specify the maximum number of results it is able to accept with MaxReturnedDevices. However, the upper limit on returned results for RisPort70 itself is 1000. If the number of devices found by the query exceeds 1000, only the first 1000 results are returned.

Note: The RisPort70 response does not indicate if results greater than 1000 have been truncated.

In practice, wildcard queries should be used with care, as systems with greater than 1000 devices are common, and results truncation can occur. Applications may want to consider results with exactly 1000 results as truncated.

One approach to retrieving bulk RisPort70 data is to submit requests specifying multiple individual Item elements in the request (see the XML example.) In this way an application can gather large collections of device names, for example 500 devices at a time, with good assurance of getting complete results.

Note: selectCmDevice can return multiple results per unique device if a device has registered on more than one Cisco Unified CM node at some point, for example due to failover. selectCmDeviceExt returns only the most recent result.

Applications can obtain device names individually or in bulk via the Cisco Unified CM AXL SOAP API, for example getPhone and listPhone.

RisPort70 Request Throttling

By default RisPort70 accepts up to 15 requests per minute, combined across all RisPort70 applications. Configure this maximum via the Cisco Unified CM Enterprise Parameter Allowed Device Queries Per Minute, up to a limit of 15 requests per minute. If RisPort70 receives more requests in a minute than the current maximum, requests may fail with a SOAP fault error. It is recommend that applications pace requests, especially large ones, to correspond to a rate of approximately 15 per minute or the configured maximum value.

snikamvyopta · ‎02-07-2017

I am confused due to the following:

From the information you provided above, I understood that we can send 15 requests per minute maximum for the same API call.

But if the organization has >1000 devices registered then after the first request, how do I provide the offset to retrieve the remaining list of the devices that is not received in the first API call?

In other words, how do I specify paging in subsequent API calls to fetch the next batch of 1000 devices in the next API call, and so on?

Unfortunately, I have an organization data with devices <200, so I can not test this >1000 case.

If you could provide the request sample, it would be a great help.

snikamvyopta · ‎02-09-2017

Hi dstaudt,

Could you please confirm on the issue I asked in above comment?

I am stuck on the development due to this limitation and cannot proceed as I don't have an access to the organization with CUCM that has >1000 devices.

An API example on paging would be a great help.

Thanks,
Seema

dstaudt · ‎02-09-2017

Unfortunately there is no 'paging' capability built in to the API - the application will need to manage this. Typically the application will compile a list of phone device names (e.g.' SEP123456789012') that it is interested in getting status on - i.e. via the AXL interface. The application then creates a <selectCmDevice> request by specifying (for example) the first 500 device names in the <SelectItems> array (this becomes a relatively large SOAP request!) - CUCM will return the status on those 500 devices (note, you may be more than 500 results back if devices if registered to multiple CUCM nodes, or less if the devices have never registered). The application would store those results and create a second request with the next 500 device names from its compiled list, and so on...

Note, the behaviour of the API is exactly the same whether you specify a max returned devices of 1000 or something smaller - you can test your app's 'paging' capability by just artificially restricting the max returned devices.