Log collection API - Call Detail Records on Demand SOAP Service API Developer Guide

Call Detail Records on Demand SOAP Service API Developer Guide

The Log Collection service provides an API for querying and transferring server and system log files to a SSH-FTP server for troubleshooting purposes.

Use the Log Collection WSDL:

Code Snippet

Copyhttps://<cucm_server>:8443/logcollectionservice2/services/LogCollectionPortTypeService?wsdl

Replace <cucm_server> with the Cisco Unified Communications Manager (Unified CM) server name or IP address.

listNodeServiceLogs

The listNodeServiceLogs method returns the node names with their available service names:

listNodeServiceLogs Sample Request/Response

Request

Response

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:listNodeServiceLogs>
         <soap:ListRequest></soap:ListRequest>
      </soap:listNodeServiceLogs>
   </soapenv:Body>
</soapenv:Envelope>

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:listNodeServiceLogsResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:listNodeServiceLogsReturn>
            <ns1:name>cucm3</ns1:name>
            <ns1:ServiceLog>
               <ns1:item>Cisco Trust Verification Service</ns1:item>
               <ns1:item>Cisco CallManager Cisco IP Phone Services</ns1:item>
               <ns1:item>Cisco CTIManager</ns1:item>
               <ns1:item>Cisco License Manager</ns1:item>
               <ns1:item>Cisco CDR files on Publisher Processed</ns1:item>
               <ns1:item>SOAP - Diagnostic Portal Database Service</ns1:item>
               <ns1:item>Cisco CDR Agent</ns1:item>
               <ns1:item>Cisco Bulk Provisioning Service</ns1:item>
               <ns1:item>Cisco Messaging Interface</ns1:item>
               <ns1:item>Cisco CallManager</ns1:item>
               ...
               <ns1:item>Cisco Audit Logs</ns1:item>
               <ns1:item>Kerneldump Logs</ns1:item>
               <ns1:item>Cisco ControlCenter CLI</ns1:item>
               <ns1:item>SELinux logs</ns1:item>
               <ns1:item>Cisco Discovery Responder Service</ns1:item>
               <ns1:item>Cisco SSO</ns1:item>
            </ns1:ServiceLog>
            <ns1:SystemLog xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
         </ns1:listNodeServiceLogsReturn>
      </ns1:listNodeServiceLogsResponse>
   </soapenv:Body>
</soapenv:Envelope>

Request Format

The input is a ListRequest element.

Parameter	Description
`ListRequest`	The value should be left empty.

Response Format

The response is an array of type NodeServiceLogList consisting of:

Parameter	Description
`name`	The server name of the node.
`ServiceLog`	list of all service logs available for each node
`SystemLog`	List of all system log files available for each node (can vary based on the activated services)

selectLogFiles

The selectLogFiles method lists available log files based on specified selection criteria, and optionally requests SSH-FTP 'push' delivery of the files.

If the JobType element is set to DownloadtoClient, then the service will simply retrieve a list of matching available log files (no files are actually downloaded.)

If the JobType element is set to PushtoSFTPServer, then the system will attempt to connect to the SSH-FTP server with the provided credentials and deliver the log files. Before using the PushtoSFTPServer option, make sure the target SSH-FTP server is running and accessible.

Note: As of CUCM 14, SSH-FTP delivery is attempted using SSH-RSA host key exchange, which may cause transfers to fail if the target SFTP server has this algorithm disabled.

The file collection time range can specified by providing the FromDate,ToDate and TimeZone elements. If those elements are empty, then all available logs are selected.

Note: Relative time range filtering is not currently supported - RelText and RelTime are ignored - however the elements must be present, with valid values, i.e. None and 0.

SelectLogFiles Sample Request/Response

Request(List All)

Request(Push by Date Range)

Response

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:selectLogFiles>
         <soap:FileSelectionCriteria>
            <soap:ServiceLogs>
               <soap:item>Cisco Audit Logs</soap:item>
            </soap:ServiceLogs>
            <soap:SystemLogs/>
            <soap:SearchStr></soap:SearchStr>
            <soap:Frequency>OnDemand</soap:Frequency>
            <soap:JobType>DownloadtoClient</soap:JobType>
            <soap:ToDate></soap:ToDate>
            <soap:FromDate></soap:FromDate>
            <soap:TimeZone></soap:TimeZone>
            <soap:RelText>None</soap:RelText>
            <soap:RelTime>0</soap:RelTime>
            <soap:Port></soap:Port>
            <soap:IPAddress></soap:IPAddress>
            <soap:UserName></soap:UserName>
            <soap:Password></soap:Password>
            <soap:ZipInfo>false</soap:ZipInfo>
            <soap:RemoteFolder></soap:RemoteFolder>
         </soap:FileSelectionCriteria>
      </soap:selectLogFiles>
   </soapenv:Body>
</soapenv:Envelope>

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:selectLogFiles>
         <soap:FileSelectionCriteria>
            <soap:ServiceLogs>
               <soap:item>Cisco Audit Logs</soap:item>
            </soap:ServiceLogs>
            <soap:SystemLogs/>
            <soap:SearchStr></soap:SearchStr>
            <soap:Frequency>OnDemand</soap:Frequency>
            <soap:JobType>PushtoSFTPServer</soap:JobType>
            <soap:ToDate>12/31/23 11:59 PM</soap:ToDate>
            <soap:FromDate>01/02/23 00:00 AM</soap:FromDate>
            <soap:TimeZone>Client: (GMT+0:0)Greenwich Mean Time-Europe/London</soap:TimeZone>
            <soap:RelText>None</soap:RelText>
            <soap:RelTime>0</soap:RelTime>
            <soap:Port>22</soap:Port>
            <soap:IPAddress>192.168.0.203</soap:IPAddress>
            <soap:UserName>root</soap:UserName>
            <soap:Password>ciscopsdt</soap:Password>
            <soap:ZipInfo>false</soap:ZipInfo>
            <soap:RemoteFolder>backups</soap:RemoteFolder>
         </soap:FileSelectionCriteria>
      </soap:selectLogFiles>
   </soapenv:Body>
</soapenv:Envelope>

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:selectLogFilesResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:ResultSet>
            <ns1:SchemaFileSelectionResult>
               <ns1:Node>
                  <ns1:name/>
                  <ns1:ServiceList>
                     <ns1:ServiceLogs>
                        <ns1:name xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                        <ns1:SetOfFiles>
                           <ns1:File>
                              <ns1:name>Audit00000001.log</ns1:name>
                              <ns1:absolutepath>/var/log/active/audit/AuditApp/Audit00000001.log</ns1:absolutepath>
                              <ns1:filesize>2097096</ns1:filesize>
                              <ns1:modifiedDate>Fri Jul 22 15:11:52 PDT 2022</ns1:modifiedDate>
                           </ns1:File>
...
                        </ns1:SetOfFiles>
                     </ns1:ServiceLogs>
                  </ns1:ServiceList>
               </ns1:Node>
            </ns1:SchemaFileSelectionResult>
         </ns1:ResultSet>
      </ns1:selectLogFilesResponse>
   </soapenv:Body>
</soapenv:Envelope>

Request Format

The selectLogFiles request takes a FileSelectionCriteria element as input.

FileSelectionCriteria consists of the following (all elements are required, though some can be empty).

Parameter	Description
`ServiceLogs`	The names of the service logs. A list of values can be found by using `listNodeServiceLogs`
`SystemLogs`	The names of system logs. A list of values can be found by using `listNodeServiceLogs`
`SearchStr`	No text search options are supported; must be present and empty
`Frequency`	The log collection frequency: OnDemand Daily Weekly Monthly Note: Only the `OnDemand` option is currently supported
`JobType`	The collection type: `DownloadtoClient` - retrieve (only) the list of matching logs `PushtoSFTPServer` - deliver the logs to the specified SSH-FTP server. The following elements must have valid values: `Port` `IPAddress` `UserName` `Password` `ZipInfo` `RemoteFolder`
`ToDate`	The end timestamp for log collection, adjusted to GMT. The format is: mm/ddyy hh:mm AM/PM
`FromDate`	The start timestamp for file collection, adjusted to GMT, required if absolute time range is used. The format is: mm/dd/yy hh:mm AM/PM
`TimeZone`	The time zone applicable to the `ToDate`/`FromDate` timestamps. Only Greenwich Mean Time time zone is documented. This field should always be the string: `Client: (GMT+0:0)Greenwich Mean Time-Europe/London`
`RelText`	Only `None` is currently documented. Note: relative time filtering is not currently supported
`RelTime`	Only `0` is currently documented Note: relative time filtering is not currently supported
`Port`	The port number of the SSH-FTP server, e.g.: `22`
`IPAddress`	The IP address of the SSH-FTP server
`UserName`	The username to use when accessing the SSH-FTP server
`Password`	The password to use when accessing the SSH-FTP server
`ZipInfo`	Indicates whether to compress the files (using GZip) during collection, applicable only with `PushtoSFTPServer`. The available options are: true / false Note: only false is currently supported. However as CUCM will normally archive/compress logs as they age, log files may be delivered as compressed or uncompressed, as indicated by the file name extension.
`RemoteFolder`	The remote SSH-FTP server directory where the files will be uploaded

Response Format

The selectLogFiles method returns a FileSelectionResult element containing the list of matching file names and their location on the server. The FileSelectionResult element consists of:

Parameter	Description
`name`	The name of the node
`SetOfFiles`	Log files available

Log file information includes:

Paramter	Description
`name`	Name of the log file
`absolutepath`	The absolute path to the log file on the CUCM system, such as `/var/log/active/syslog/AlternateSyslog`
`filesize`	The size of the log file (bytes)
`modifiedDate`	Date the log file was last modified. This is a non-standard date/time format, e.g.: `Sun Jul 03 19:29:07 PDT 2022`

GetOneFile

The GetOneFile request is used to retrieve either a server or system log file through the standard Direct Internet Message Encapsulation (DIME) protocol.

Note: The RTMT (Real Time Management Tool) is another method to enable and gather logs. See the RTMT Administration Guide

DIME is a specification that allows retrieval of files via HTTP. The GetOneFile request specifies a single file to retrieve. The response includes the entire file in DIME encapsulation, as binary data (Content-Type: application/octet-stream, Content-Type-Encoding: binary).

Request

Response

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:FileName>/var/log/active/audit/AuditApp/Audit00000001.log</soap:FileName>
   </soapenv:Body>
</soapenv:Envelope>

CopyContent-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_79A8D1E5F06245C6A61701117497090; type="application/xop+xml"; start="<0.urn:uuid:79A8D1E5F06245C6A61701117497091@apache.org>"; start-info="text/xml"
Transfer-Encoding: chunked
Date: Mon, 27 Nov 2023 20:38:16 GMT
Server: 

--MIMEBoundaryurn_uuid_79A8D1E5F06245C6A61701117497090
Content-Type: application/xop+xml; charset=UTF-8; type="text/xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:79A8D1E5F06245C6A61701117497091@apache.org>

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:GetOneFileReturn xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <xop:Include href="cid:1.urn:uuid:79A8D1E5F06245C6A61701117497093@apache.org" xmlns:xop="http://www.w3.org/2004/08/xop/include" />
      </ns1:GetOneFileReturn>
   </soapenv:Body>
</soapenv:Envelope>
--MIMEBoundaryurn_uuid_79A8D1E5F06245C6A61701117497090
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-ID: <1.urn:uuid:79A8D1E5F06245C6A61701117497093@apache.org>

11:22:06.993 HDR|08/05/2021 AuditLog,StandAloneCluster,SJDS-CUCM14,Detailed,14.0.1.10000-20
11:22:06.993 |LogMessage   UserID : Administrator  ClientAddress : 10.118.89.228  Severity : 6  EventType : UserLogging  ResourceAccessed: Cisco CallManager Administration  EventStatus : Success  CompulsoryEvent : No  AuditCategory : AdministrativeEvent  ComponentID : Cisco CallManager Administration  CorrelationID :   AuditDetails : Successfully Logged into Cisco Unified CM Admin Webpages App ID: Cisco Tomcat Cluster ID:  Node ID: SJDS-CUCM14
11:23:33.215 |LogMessage   UserID : Administrator  ClientAddress : 10.118.89.228  Severity : 5  EventType : GeneralConfigurationUpdate  ResourceAccessed: CUCMAdmin  EventStatus : Success  CompulsoryEvent : No  AuditCategory : AdministrativeEvent  ComponentID : Cisco CUCM Administration  CorrelationID :   AuditDetails :  record in table processnode with key field name = SJDS-CIMP14.cisco.com added  App ID: Cisco Tomcat Cluster ID:  Node ID: SJDS-CUCM14
11:23:41.760 |LogMessage   UserID : Administrator  ClientAddress : 10.118.89.228  Severity : 5  EventType : GeneralConfigurationUpdate  ResourceAccessed: CUCMAdmin  EventStatus : Success  CompulsoryEvent : No  AuditCategory : AdministrativeEvent  ComponentID : Cisco CUCM Administration  CorrelationID :   AuditDetails :  record in table processnode with key field name = SJDS-CIMP14.cisco.com updated  App ID: Cisco Tomcat Cluster ID:  Node ID: SJDS-CUCM14
11:24:14.272 |LogMessage   UserID : Administrator  ClientAddress : 10.118.89.228  Severity : 6  EventType : UserLogging  ResourceAccessed: CUCMAdmin  EventStatus : Success  CompulsoryEvent : No  AuditCategory : CriticalEvent  ComponentID : Cisco CUCM Administration  CorrelationID :   AuditDetails : Successfully Logged out Cisco Unified Administration Web Pages App ID: Cisco Tomcat Cluster ID:  Node ID: SJDS-CUCM14

Request Format

Parameter	Description
`FileName`	The absolute file name of the file to be collected from the server. For example, `/var/log/active/audit/AuditApp/Audit00000001.log`. See selectLogFiles for determining log file path/filename.

Response Format

The return value specifies the Content-Id of the requested file.

Parameter	Description
`DataHandler`	The Content-Id of the multi-part message containing the file data