How to Execute Serviceability Requests with cURL
cURL is a an open source, cross-platform tool able to perform URL-based network requests from the command line: https://curl.haxx.se/
One use of cURL is to make HTTP requests, including SOAP requests.
For this example, the SelectCmDeviceExt API of the RisPort70 service is used. This API allows clients to perform Cisco Unified Communications Manager (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.
Setup
cURL executes from the command line. Locate curl.exe and request.xml in the same directory.
Note the following, dependent on the operating system used:
- Mac and Linux systems include cURL and do not need cURL installed.
- For Windows systems, ensure a SSL version of cURL is downloaded and installed. Installation of the SSL dependencies (OpenSSL and Visual C++ redistributables) is also needed.
- i. Create a new working directory. An example of a directory is C:\Users\<username>\curl.
- ii. Copy curl.exe to the new working directory.
Initial setup to test with cURL in Windows:
Test
- i. Open the command prompt/terminal and navigate to the working directory: cd C:\Users\<username>\curl
- ii. Create a new file named request.xml containing the full XML of the SelectCmDeviceExt SOAP request and save it in the working directory C:\Users\<username>\curl.
- iii. Use the following command to execute the cURL request:
- iv. The SelectCmDeviceExt API returns a response similar to the following:
The contents of a sample SelectCmDeviceExt SOAP request.xml file follows:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
<soapenv:Envelope
xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap="https://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><soap:item><soap:Item>*</soap:Item></soap:item></soap:SelectItems><soap:Protocol>Any</soap:Protocol><soap:DownloadStatus>Any</soap:DownloadStatus></soap:CmSelectionCriteria></soap:selectCmDeviceExt></soapenv:Body></soapenv:Envelope> |
C:\Users\<username>\curl> curl -k -u username -H "Content-type: text/xml" -d @request.xml https://<ServerName>:8443/realtimeservice2/services/RISService70
Note: Replace <ServerName> with the Cisco Unified CM server name or IP address.
The parameters are:
| k | Disable SSL key authentication of the Cisco UC Manager server. |
| u | The user name for UC Manager authentication. The user name is a CUCM user with the Standard CCM Admin Users and the Standard SERVICEABILITY access roles. |
| H | Header, overrides cURL's default Content-type. |
| d | Specifies the data file where the request data to be sent is stored. |
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
<?xml version="1.0"
encoding="UTF-8"?><soapenv:Body><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: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:H323Trunk><ns1:TimeStamp>1415364521</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:DownloadStatus>Unknown</ns1:DownloadStatus><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><StateInfo
ClusterWide="1"><Node
Name="cucm3" SubsystemStartTime="1415364441"
StateId="34"
TotalItemsFound="1"
TotalItemsReturned="1"/></StateInfo></ns1:StateInfo></ns1:selectCmDeviceReturn></ns1:selectCmDeviceResponse></soapenv:Body></soapenv:Envelope> |
Cisco Unified Communications Manager (Unified CM) and Serviceability Version tested: 10.0