Overview

The RisPort70 (Real-Time Information Port) service provides an API for querying the current connection status of phones, devices, and applications connected to Cisco Unified Communications Manager (Unified CM). Details provided by RisPort70 include last known connection and registration state, IP address, and model information. The API provides queries, for example by name, for single device or application instances, and wildcard queries which return the status of multiple devices at once.

The RisPort70 API allows clients to:

• Query Cisco Unified CM for the status and details of phones and other telephony devices
• Query Cisco Unified CM for the status and details of CTI applications

Use the RisPort70 WSDL:

https://<server>:8443/realtimeservice2/services/RISService70?wsdl

Deprecated Methods

The RisPort WSDL is deprecated. Use the RisPort70 WSDL.

RisPort70 SelectCmDevice

This method allows clients to perform Cisco Unified CM device-related queries. The method returns a snapshot of real-time device registration status from each Cisco Unified CM node. The data includes registration status, IP address, model info, and CTI application connections to the device. A single device may appear in multiple elements if the device has registered to multiple nodes. Devices may be requested by wildcard using an asterisk, *.

SelectCmDevice Request Format

<!--RisPort70 API - SelectCmDevice - Request-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:selectCmDevice>
         <soap:StateInfo></soap:StateInfo>
         <soap:CmSelectionCriteria>
            <soap:MaxReturnedDevices>1000</soap:MaxReturnedDevices>
            <soap:DeviceClass>Any</soap:DeviceClass>
            <soap:Model>255</soap:Model>
            <soap:Status>Any</soap:Status>
            <soap:NodeName></soap:NodeName>
            <soap:SelectBy>DirNumber</soap:SelectBy>
            <soap:SelectItems>
               <!--Zero or more repetitions:-->
               <soap:item>
                  <soap:Item>6961</soap:Item>
               </soap:item>
            </soap:SelectItems>
            <soap:Protocol>Any</soap:Protocol>
            <soap:DownloadStatus>Any</soap:DownloadStatus>
         </soap:CmSelectionCriteria>
      </soap:selectCmDevice>
   </soapenv:Body>
</soapenv:Envelope>

Model Table

StateInfo Usage

<!-- Example:  -->
<ns1:StateInfo>&lt;StateInfo ClusterWide="1">&lt;Node Name="DS-UCM105" SubsystemStartTime="1412580217" StateId="61" TotalItemsFound="1" TotalItemsReturned="1"/>&lt;/StateInfo></ns1:StateInfo>

<!-- Example:  -->        
 <ns1:SelectCmDeviceResult>
               <ns1:TotalDevicesFound>0</ns1:TotalDevicesFound>
               <ns1:CmNodes>
                  <ns1:item>
                     <ns1:ReturnCode>Ok</ns1:ReturnCode>
                     <ns1:Name>DS-UCM105</ns1:Name>
                     <ns1:NoChange>true</ns1:NoChange>
                     <ns1:CmDevices xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                  </ns1:item>
               </ns1:CmNodes>
            </ns1:SelectCmDeviceResult>

The StateInfo feature is an optional mechanism for applications to receive full RisPort70 data updates only if the state of one or more devices returned by a previous, identical query changed. This can reduce RisPort70 and application-side processing impact when queries are large and device state changes are infrequent. Benefits are improved performance and request latency which allows applications to poll for state changes more frequently.

How It Works

As part of each successful RisPort70 response, the StateInfo field is populated with a string value representing an internal RisPort70 state. This StateInfo value is specific to the parameters and timestamp of the query, and is a snapshot of the device state of all devices queried at the time of the request.

If an application performs a RisPort70 query identical to a previously executed query, it may provide the associated StateInfo string in the request. RisPort70 will then compare the previous RisPort70 state snapshot with the current device states, and determine if they exactly match. If the state of all devices is unchanged, RisPort70 returns a response with TotalDevicesFound= 0 and NoChange= true.

If any of the devices have changed state, then the standard RisPort70 response will be provided, including full state data for all queried devices. An updated StateInfo value represents the new state snapshot.

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.

SelectCMDevice Response Format

<!--RisPort70 API - SelectCmDevice - Response-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:selectCmDeviceResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:selectCmDeviceReturn>
            <ns1:SelectCmDeviceResult>
               <ns1:TotalDevicesFound>1</ns1:TotalDevicesFound>
               <ns1:CmNodes>
                  <ns1:item>
                     <ns1:ReturnCode>Ok</ns1:ReturnCode>
                     <ns1:Name>cucm3</ns1:Name>
                     <ns1:NoChange>false</ns1:NoChange>
                     <ns1:CmDevices>
                        <ns1:item>
                           <ns1:Name>SEPE8B7480316D6</ns1:Name>
                           <ns1:DirNumber>6961-Registered</ns1:DirNumber>
                           <ns1:DeviceClass>Phone</ns1:DeviceClass>
                           <ns1:Model>497</ns1:Model>
                           <ns1:Product>384</ns1:Product>
                           <ns1:BoxProduct>0</ns1:BoxProduct>
                           <ns1:Httpd>Yes</ns1:Httpd>
                           <ns1:RegistrationAttempts>0</ns1:RegistrationAttempts>
                           <ns1:IsCtiControllable>true</ns1:IsCtiControllable>
                           <ns1:LoginUserId xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:Status>Registered</ns1:Status>
                           <ns1:StatusReason>0</ns1:StatusReason>
                           <ns1:PerfMonObject>2</ns1:PerfMonObject>
                           <ns1:DChannel>0</ns1:DChannel>
                           <ns1:Description>SEPE8B7480316D6</ns1:Description>
                           <ns1:H323Trunk>
                              <ns1:ConfigName xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:TechPrefix xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:Zone xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RemoteCmServer1 xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RemoteCmServer2 xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RemoteCmServer3 xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:AltGkList xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:ActiveGk xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:CallSignalAddr xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RasAddr xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           </ns1:H323Trunk>
                           <ns1:TimeStamp>1411595208</ns1:TimeStamp>
                           <ns1:Protocol>SCCP</ns1:Protocol>
                           <ns1:NumOfLines>1</ns1:NumOfLines>
                           <ns1:LinesStatus>
                              <ns1:item>
                                 <ns1:DirectoryNumber>6961</ns1:DirectoryNumber>
                                 <ns1:Status>Registered</ns1:Status>
                              </ns1:item>
                           </ns1:LinesStatus>
                           <ns1:ActiveLoadID>SCCP69xx.9-4-1-3SR1</ns1:ActiveLoadID>
                           <ns1:InactiveLoadID xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:DownloadStatus>Unknown</ns1:DownloadStatus>
                           <ns1:DownloadFailureReason xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:DownloadServer xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:IPAddress>
                              <ns1:item>
                                 <ns1:IP>192.168.168.186</ns1:IP>
                                 <ns1:IPAddrType>ipv4</ns1:IPAddrType>
                                 <ns1:Attribute>AdministrativeAndSignaling</ns1:Attribute>
                              </ns1:item>
                           </ns1:IPAddress>
                        </ns1:item>
                     </ns1:CmDevices>
                  </ns1:item>
               </ns1:CmNodes>
            </ns1:SelectCmDeviceResult>
            <ns1:StateInfo>&lt;StateInfo ClusterWide="1">&lt;Node Name="cucm3" SubsystemStartTime="1411513436" StateId="84" TotalItemsFound="1" TotalItemsReturned="1"/>&lt;/StateInfo></ns1:StateInfo>
         </ns1:selectCmDeviceReturn>
      </ns1:selectCmDeviceResponse>
   </soapenv:Body>
</soapenv:Envelope>

The response includes information requested using the SelectCmDevice request, and can include information for one or more Cisco Unified CM nodes.

A CmDevice in the CmNode contains the following information:

SelectCmDevice Status Reason Codes

If the device is Registered on the server, the StatusReason is 0. If the device is Unregistered, then one of the following values will be displayed in the response.

RisPort70 SelectCMDeviceExt

<!--RisPort70 API - SelectCmDeviceExt - Request-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:selectCmDeviceExt>
         <soap:StateInfo></soap:StateInfo>
         <soap:CmSelectionCriteria>
            <soap:MaxReturnedDevices>1000</soap:MaxReturnedDevices>
            <soap:DeviceClass>Any</soap:DeviceClass>
            <soap:Model>255</soap:Model>
            <soap:Status>Any</soap:Status>
            <soap:NodeName></soap:NodeName>
            <soap:SelectBy>Name</soap:SelectBy>
            <soap:SelectItems>
               <!--Zero or more repetitions:-->
               <soap:item>
                  <soap:Item>SEPE8B7480316D6</soap:Item>
               </soap:item>
            </soap:SelectItems>
            <soap:Protocol>Any</soap:Protocol>
            <soap:DownloadStatus>Any</soap:DownloadStatus>
         </soap:CmSelectionCriteria>
      </soap:selectCmDeviceExt>
   </soapenv:Body>
</soapenv:Envelope>

<!--RisPort70 API - SelectCmDeviceExt - Response-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:selectCmDeviceResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:selectCmDeviceReturn>
            <ns1:SelectCmDeviceResult>
               <ns1:TotalDevicesFound>1</ns1:TotalDevicesFound>
               <ns1:CmNodes>
                  <ns1:item>
                     <ns1:ReturnCode>Ok</ns1:ReturnCode>
                     <ns1:Name>cucm3</ns1:Name>
                     <ns1:NoChange>false</ns1:NoChange>
                     <ns1:CmDevices>
                        <ns1:item>
                           <ns1:Name>SEPE8B7480316D6</ns1:Name>
                           <ns1:DirNumber>6961-Registered</ns1:DirNumber>
                           <ns1:DeviceClass>Phone</ns1:DeviceClass>
                           <ns1:Model>497</ns1:Model>
                           <ns1:Product>384</ns1:Product>
                           <ns1:BoxProduct>0</ns1:BoxProduct>
                           <ns1:Httpd>Yes</ns1:Httpd>
                           <ns1:RegistrationAttempts>0</ns1:RegistrationAttempts>
                           <ns1:IsCtiControllable>true</ns1:IsCtiControllable>
                           <ns1:LoginUserId xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:Status>Registered</ns1:Status>
                           <ns1:StatusReason>0</ns1:StatusReason>
                           <ns1:PerfMonObject>2</ns1:PerfMonObject>
                           <ns1:DChannel>0</ns1:DChannel>
                           <ns1:Description>SEPE8B7480316D6</ns1:Description>
                           <ns1:H323Trunk>
                              <ns1:ConfigName xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:TechPrefix xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:Zone xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RemoteCmServer1 xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RemoteCmServer2 xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RemoteCmServer3 xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:AltGkList xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:ActiveGk xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:CallSignalAddr xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:RasAddr xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           </ns1:H323Trunk>
                           <ns1:TimeStamp>1411595208</ns1:TimeStamp>
                           <ns1:Protocol>SCCP</ns1:Protocol>
                           <ns1:NumOfLines>1</ns1:NumOfLines>
                           <ns1:LinesStatus>
                              <ns1:item>
                                 <ns1:DirectoryNumber>6961</ns1:DirectoryNumber>
                                 <ns1:Status>Registered</ns1:Status>
                              </ns1:item>
                           </ns1:LinesStatus>
                           <ns1:ActiveLoadID>SCCP69xx.9-4-1-3SR1</ns1:ActiveLoadID>
                           <ns1:InactiveLoadID xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:DownloadStatus>Unknown</ns1:DownloadStatus>
                           <ns1:DownloadFailureReason xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:DownloadServer xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:IPAddress>
                              <ns1:item>
                                 <ns1:IP>192.168.168.186</ns1:IP>
                                 <ns1:IPAddrType>ipv4</ns1:IPAddrType>
                                 <ns1:Attribute>AdministrativeAndSignaling</ns1:Attribute>
                              </ns1:item>
                           </ns1:IPAddress>
                        </ns1:item>
                     </ns1:CmDevices>
                  </ns1:item>
               </ns1:CmNodes>
            </ns1:SelectCmDeviceResult>
            <ns1:StateInfo>&lt;StateInfo ClusterWide="1">&lt;Node Name="cucm3" SubsystemStartTime="1411513436" StateId="84" TotalItemsFound="1" TotalItemsReturned="1"/>&lt;/StateInfo></ns1:StateInfo>
         </ns1:selectCmDeviceReturn>
      </ns1:selectCmDeviceResponse>
   </soapenv:Body>
</soapenv:Envelope>

The request and response schema format for SelectCmDevice and SelectCmDeviceExt are identical, with the exception of the base request name. See SelectCmDevice for usage and parameter values.

The difference is in functionality. SelectCmDeviceExt collates device status records across nodes, eliminating any duplicates.

This API returns a snapshot of the real-time device state from each Cisco Unified CM node. This data includes registration status, IP address, and model info. This request consolidates device records across nodes, returning only the device info for the latest registration.

Note: SelectCMDeviceExt does not support using the * wildcard for SelectItems matching.

RisPort70 SelectCtiItem

This method allows clients to perform CTI manager related queries. The method returns a snapshot of real-time CTI application status from each Cisco Unified CM node. This data includes application name, authenticated user, IP address, controlled CTI devices, and connection status.

SelectCtiItem Request Format

<!--RisPort70 API - SelectCtiItem - Request-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:selectCtiItem>
         <soap:StateInfo></soap:StateInfo>
         <soap:CtiSelectionCriteria>
            <soap:MaxReturnedItems>1000</soap:MaxReturnedItems>
            <soap:CtiMgrClass>Line</soap:CtiMgrClass>
            <soap:Status>Any</soap:Status>
            <soap:NodeName></soap:NodeName>
            <soap:SelectAppBy>AppId</soap:SelectAppBy>
            <soap:AppItems>
               <!--Zero or more repetitions:-->
               <soap:item>
                  <soap:AppItem>cucmuser-192.168.168.169-4963</soap:AppItem>
               </soap:item>
            </soap:AppItems>
            <soap:DevNames>
               <!--Zero or more repetitions:-->
               <soap:item>
                  <soap:DevName>SEPF01FAF38ABC2</soap:DevName>
               </soap:item>
            </soap:DevNames>
            <soap:DirNumbers>
               <!--Zero or more repetitions:-->
               <soap:item>
                  <soap:DirNumber>1002</soap:DirNumber>
               </soap:item>
            </soap:DirNumbers>
         </soap:CtiSelectionCriteria>
      </soap:selectCtiItem>
   </soapenv:Body>
</soapenv:Envelope>

CtiSelectionCriteria includes:

SelectCtiitem Response Format

<!--RisPort70 API - SelectCtiItem - Response-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:selectCtiItemResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:selectCtiItemReturn>
            <ns1:SelectCtiItemResult>
               <ns1:TotalItemsFound>1</ns1:TotalItemsFound>
               <ns1:CtiNodes>
                  <ns1:item>
                     <ns1:ReturnCode>Ok</ns1:ReturnCode>
                     <ns1:Name>cucm3</ns1:Name>
                     <ns1:NoChange>false</ns1:NoChange>
                     <ns1:CtiItems>
                        <ns1:item>
                           <ns1:AppId>cucmuser-192.168.168.169-4963</ns1:AppId>
                           <ns1:UserId>cucmuser</ns1:UserId>
                           <ns1:AppIpAddr>192.168.168.169</ns1:AppIpAddr>
                           <ns1:AppIpv6Addr xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           <ns1:AppStatus>Closed</ns1:AppStatus>
                           <ns1:AppStatusReason>2</ns1:AppStatusReason>
                           <ns1:AppTimeStamp>1412194696</ns1:AppTimeStamp>
                           <ns1:CtiDevice>
                              <ns1:AppControlsMedia>false</ns1:AppControlsMedia>
                              <ns1:DeviceName>SEPF01FAF38ABC2</ns1:DeviceName>
                              <ns1:DeviceStatus>Open</ns1:DeviceStatus>
                              <ns1:DeviceStatusReason xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                              <ns1:DeviceTimeStamp xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                           </ns1:CtiDevice>
                           <ns1:CtiLine>
                              <ns1:DirNumber>1002</ns1:DirNumber>
                              <ns1:LineStatus>Closed</ns1:LineStatus>
                              <ns1:LineStatusReason>0</ns1:LineStatusReason>
                              <ns1:LineTimeStamp>1412194696</ns1:LineTimeStamp>
                           </ns1:CtiLine>
                        </ns1:item>
                     </ns1:CtiItems>
                  </ns1:item>
               </ns1:CtiNodes>
            </ns1:SelectCtiItemResult>
            <ns1:StateInfo>&lt;StateInfo ClusterWide="1">&lt;Node Name="cucm3" SubsystemStartTime="1411513254" StateId="621" TotalItemsFound="1" TotalItemsReturned="1"/>&lt;/StateInfo></ns1:StateInfo>
         </ns1:selectCtiItemReturn>
      </ns1:selectCtiItemResponse>
   </soapenv:Body>
</soapenv:Envelope>

CtiNodes contains the following information:

CtiItems contains the following information:

CtiDevice contains the following information:

CtiLine contains the following information: