Call Detail Records on Demand SOAP Service API Developer Guide

The Call Detail Records on Demand (CDRonDemand) SOAP service is a public SOAP/HTTPS interface exposed to third-party applications to allow queries of the Cisco Unified Communications Manager (Unified CM) Call Detail Records (CDR) Repository Node. The CDRonDemand Service allows applications to obtain CDR files in a two-step process:

  1. The application requests a list of CDR files based on a specific time interval.
  2. The application then requests one CDR file from the CDR file list. The file is returned via a FTP or SSH-FTP session.

To retrieve individual CDR files as needed, use the CDRonDemand API. However, to retrieve all of the CDR files all of the time, it is recommended to use the CDR Repository Manager to directly FTP or SSH-FTP the files to your server.

The Cisco Unified CM CDR Repository service can be configured to transfer CDR files for up to three application servers on a preconfigured schedule, with a default time of once per minute. The files are then deleted per the Unified CM configuration and other criteria. If the CDR application does not receive the CDR files or needs to retrieve specific CDR files again, the application can use the CDRonDemand API.

Refer to CDR Repository Manager for setup information.

The File Manager component of the CDR Repository Manager runs hourly. When the File Manager runs, it deletes files with dates outside the configured preservation duration. It also checks whether disk usage has exceeded the high water mark. If so, the system deletes the processed CDR files until the low water mark is reached, starting with the oldest files. However, if any CDR file to be deleted was not successfully sent to the specified server, the system leaves it in the CDR Repository and raises a notification or alarm. The system creates a flag file during the configured maintenance window, which denies access to the CDR files for the CDRonDemand Service. The system removes the flag file after the maintenance window expires. CDRonDemand applications should avoid making requests at the top of the hour.

Use the CDRonDemand WSDL:

Code Snippet
Copyhttps://<server>/CDRonDemandService2/services/CDRonDemandService?wsdl

get_file_list

The get_file_list operation allows an application to query the CDR Repository Node for a list of all files that match a specified time interval. The time interval of the request cannot exceed one hour. To get a list of files that span more than the one hour interval allowed, multiple requests to the service must be made.

get_file_list returns an array of strings that contain the list of all the filenames that match the specified time interval. If no filenames match the time range, the value returned from the API call is "null." If errors are encountered, an exception message is returned. In addition, logs will be kept detailing the errors. Find these log files in the /var/log/active/tomcat/logs/soap/log4j directory.

A limit of 1300 file names can be returned to the application as a result of a get_file_list API call. If the file list returned contains 1300 file names but does not span the entire requested time interval, make additional requests with the start time of the subsequent request equal to the time of the last file returned in the previous request.

If the error “No file found within the specified time range” is continuously returned, check the following:

  • A file should exist for the specified time range
  • All the appropriate services are running

Restart the Cisco CDR Repository Manager. Allow several minutes for the CDR Repository Manager to restart.

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:get_file_list>
         <soap:in0>202207112200</soap:in0>
         <soap:in1>202207112300</soap:in1>
         <soap:in2>True</soap:in2>
      </soap:get_file_list>
   </soapenv:Body>
</soapenv:Envelope>

Copy<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:get_file_listResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:get_file_listReturn>
            <ns1:FileName>cdr_StandAloneCluster_01_202207112241_0</ns1:FileName>
         </ns1:get_file_listReturn>
      </ns1:get_file_listResponse>
   </soapenv:Body>
</soapenv:Envelope>

Request Format

Parameter Description
in0 Mandatory parameter that specifies the starting time for the search interval. The format is a string: YYYYMMDDHHMM. No default value exists. The time zone utilized in the request is UTC.
in1 Mandatory parameter that specifies the ending time for the search interval. The format is a string: YYYYMMDDHHMM. No default value exists. The time zone utilized in the request is UTC..
in2 Mandatory parameter that tells the service whether to include those files that were successfully sent to the specified server. The format is boolean.
  • True = Include both files that were sent successfully and files that failed to be sent.
  • False = Send only the files that failed to be sent. Do not include files that were sent successfully.
FileName A file name.

get_file

The get_file operation allows customers to request a specific CDR file that matches the specified filename. The matching CDR file is sent to the customer via standard FTP or SSH-FTP, depending on the application preference. The only constraint is the service processes one file per request.

The get_file method returns normally with no value to indicate the file has been successfully sent to the specified server. If the transfer fails for any reason, an exception message is returned. In addition, logs detailing the errors are saved in the /var/log/active/tomcat/logs/soap/log4j directory.

Note: In previous releases, the CDR database stored the CDR records, and third-party applications could query the database directly for the CDR records. In current releases, CDR records no longer are stored in the CDR database, but are stored as flat files.

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:get_file>
         <soap:in0>sftp_hostname</soap:in0>
         <soap:in1>sftp_username</soap:in1>
         <soap:in2>sftp_password</soap:in2>
         <soap:in3>/home/sftp_username/incoming_cdr_files</soap:in3>
         <soap:in4>cdr_StandAloneCluster_01_202207112241_0</soap:in4>
         <soap:in5>True</soap:in5>
      </soap:get_file>
   </soapenv:Body>
</soapenv:Envelope>

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

Request Format

Parameter Description
Host Name Mandatory parameter (string) that specifies the hostname of the server. The CDR server needs this information to connect to the specified server to deliver the CDR files.
User Name Mandatory parameter (string) that specifies the username for the server. The CDR server needs this information to connect to the specified server to deliver the CDR files.
Password Mandatory parameter (string) that specifies the password for the server. The CDR server needs this information to connect to the specified server to deliver the CDR files.
Remote Directory Mandatory parameter (string) that specifies the remote directory on the specified server where the CDR server sends the CDR files.
File Name Mandatory parameter (string) that specifies the filename of the CDR file that the application requests for delivery from the CDRonDemand Service.
Secure FTP Mandatory parameter (Boolean) that specifies whether to use standard FTP or secure FTP to deliver the CDR files. This depends on the application configuration and preferences.

Faults

The CDRonDemand Service raises exceptions when certain error conditions are met:

  • The service gets used during the maintenance period.
  • The values that are entered for starting and ending time do not reflect the correct length. 12 bytes in the format YYYYMMDDHHMM is the correct length.
  • The starting and ending time spans an interval of more than one hour.
  • The starting time is greater than or equal to the ending time, an invalid interval.
  • No files exist in the CDR Repository.
  • The FTP or SFTP connection to the remote node is not established.
  • The FTP or SFTP application failed to send the files that the third-party billing application requested.

The exception string describes the error condition that the billing application can print with the toString() function.

CDR Analysis Tool

The CDR Analysis Tool is a built-in tool to analyze Call Detail Records. The CDR Analysis Tool is found under Unified CM Serviceability Tools > CDR Analysis and Reporting

Security Considerations for CDRonDemand

Use standard FTP or SSH-FTP to deliver the CDR files. Refer to RFC959 and RFC2228 for further details about these applications.

The CDRonDemand Service will create either a standard FTP or SSH-FTP session with the specified server each time a CDR file is to be sent. Exceptions are created whenever an error occurs on the service side. In addition, all errors are written into log files.

On the application side, Cisco recommends that applications implement code to catch these exceptions and display the exception string for detailed error conditions.

Next