CUCM RIS

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 (18 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

By default RisPort70 accepts up to 18 requests per minute, combined across all RisPort70 applications. Configure this maximum via the Cisco Unified CM Enterprise Parameter Allowed Device Queries Per Minute (default = 15, up to a limit of 18 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.

Note - this query can contain wildcards unlike selectCMDeviceExt, but can also contain duplicates.

<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>5</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>SEP*</soap:Item>
               </soap:item>
            </soap:SelectItems>
            <soap:Protocol>Any</soap:Protocol>
            <soap:DownloadStatus>Any</soap:DownloadStatus>
         </soap:CmSelectionCriteria>
      </soap:selectCmDevice>
   </soapenv:Body>
</soapenv:Envelope>

<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>5</soap:MaxReturnedDevices>
            <soap:DeviceClass>Gateway</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>ATA*</soap:Item>
               </soap:item>
            </soap:SelectItems>
            <soap:Protocol>Any</soap:Protocol>
            <soap:DownloadStatus>Any</soap:DownloadStatus>
         </soap:CmSelectionCriteria>
      </soap:selectCmDevice>
   </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.

The selectCmDeviceExt**

<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>Phone</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>SEP001BD433741F</soap:Item></soap:item>
               <soap:item><soap:Item>SEP001C58D68B6A</soap:Item></soap:item>
            </soap:SelectItems>
            <soap:Protocol>Any</soap:Protocol>
            <soap:DownloadStatus>Any</soap:DownloadStatus>
         </soap:CmSelectionCriteria>
      </soap:selectCmDeviceExt>
   </soapenv:Body>
</soapenv:Envelope>

<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>Phone</soap:DeviceClass>
            <soap:Model>255</soap:Model>
            <soap:Status>Any</soap:Status>
            <soap:NodeName></soap:NodeName>
            <soap:SelectBy>Description</soap:SelectBy>
            <soap:SelectItems>
               <!--Zero or more repetitions:-->
               <soap:item>
                  <soap:Item>Test Desc</soap:Item>
               </soap:item>
            </soap:SelectItems>
            <soap:Protocol>Any</soap:Protocol>
            <soap:DownloadStatus>Any</soap:DownloadStatus>
         </soap:CmSelectionCriteria>
      </soap:selectCmDeviceExt>
   </soapenv:Body>
</soapenv:Envelope>