Call Detail Record API

Revised January 30, 2013

The Cisco TelePresence Exchange System provides an Application Programming Interface (API) for managing and retrieving call detail records. Familiarity with telephony is required for readers to understand the terms and concepts within this chapter.

This chapter provides a description of the CDR API and includes the following sections:

•Getting Started

•Filtering CDRs

•Pagination

•Retrieving CDR Records

•Performing API-Related Tasks

•Error Handling

Getting Started

This section describes how to get started with the CDR API and includes the following topics:

•CDR API Overview

•Obtaining the WSDL

•API Versions

CDR API Overview

The CDR API enables you to accomplish the following tasks:

•Retrieve call detail records from the Cisco TelePresence Exchange System.

The API provides web services to retrieve CDR records.

•Perform tasks that are related to the API.

The API provides services that are related to managing the CDR API. These services are described in the "Performing API-Related Tasks" section.

Obtaining the WSDL

You can access the WSDL file for the CDR API at
http://<DNS name or IP address for your admin server>:8080/ctxapi/api/v1_1/cdr?wsdl

The WSDL file provides a complete and accurate definition of the API that is supported by your Cisco TelePresence Exchange System. In the event of any discrepancies between the WSDL file and this document, you should follow the WSDL file definition.

API Versions

At time of publication, the latest version of the CDR API is version 1.1, which is accessed by using the WSDL URL listed above.

Cisco TelePresence Exchange System also supports version 1.0 of the CDR API, which you can access using the following URL:

http://<DNS name or IP address for your admin server>:8080/ctxapi/api/cdr?wsdl

For notes on backward compatibility with Cisco TelePresence Exchange System Release 1.0, see "Backward Compatibility."

Note This document describes version 1.1 of the API. The documentation for version 1.0 of the API is available from Cisco.com at the following URL:
http://www.cisco.com/en/US/docs/telepresence/tx/exchange_system/1_0/api_guide/api_guide_101.html

Filtering CDRs

You can set filters for all get, get count, and purge requests. By default, a request operates on all records that are defined for that command unless you set filters to specify a subset of records for the request.

For example, you might want the request to apply only to Meet-Me calls for a single organization within a given month, from the first day of the month until the last day of the month. To accomplish this, you would set the organization and time range parameters appropriately, and leave the other parameters as null.

Pagination

You can define pagination parameters to limit the number of records that the Cisco TelePresence Exchange System returns to the API client, to adapt to a web display or a client buffer.

For information about the parameters that control pagination, see the "Pagination" section.

Retrieving CDR Records

The CDR API provides methods for retrieving call detail records that are stored on the Cisco TelePresence Exchange System. The methods are described in the following sections:

•callType

•companyScope

•getCallDetailRecordsCount

•getCallDetailRecords

•purgeCallDetailRecords

callType

Several of the CDR API service requests and responses include a callType element, which is described in Table 4-1.

Table 4-1 callType Element 

Parameter
Type
Description

callType

Enumeration

The callType field contains one of the following string values:

•DIRECTDIAL—Direct Dial call.

•MEETME_INCOMING—Call leg originates from an endpoint and connects to a Meet-Me or Rendezvous meeting on the Cisco TelePresence Exchange System.

•MEETME_OUTGOING—Call leg for a Meet-Me or Rendezvous meeting originates from the Cisco TelePresence Exchange System and connects to an endpoint (for example, dial out calls to H.323, ISDN, or SIP endpoints).

Note For call records imported from the Cisco Unified Communications Manager, the call type is DIRECTDIAL.


companyScope

Several of the CDR API service requests and responses include a companyScope element, which is described in Table 4-2.

Table 4-2 companyScope Element 

Parameter
Type
Description

companyScope

Enumeration

The companyScope field is relevant only for the DIRECTDIAL callType.

This field contains one of the following string values:

•INTRA_COMPANY—Returns intra-company direct dial calls that reside on Cisco Unified Communications Manager.

•INTER_COMPANY—Returns all inter-company direct dial calls.


getCallDetailRecordsCount

The getCallDetailRecordsCount service returns the number of call records that match the filtering criteria that are specified in the request message. You can use this information to adjust the criteria before requesting the actual call records.

The service request includes a getCallDetailRecordsCount element. Table 4-3 describes the parameters in a getCallDetailRecordsCount request. For each parameter that is set to null, the Cisco TelePresence Exchange System ignores the criteria.

Table 4-3 getCallDetailRecordsCount Request 

Parameter
Type
Description

startTimeFrom

String

(Optional) Selects a call record if the start time of the call in the call record is equal to or later than the time that is specified in this parameter.

startTimeTo

String

(Optional) Selects a call record if the start time of the call in the call record is earlier than the time that is specified in this parameter.

endTimeFrom

String

(Optional) Selects a call record if the end time of the call in the call record is equal to or later than the time that is specified in this parameter.

endTimeTo

String

(Optional) Selects a call record if the end time of the call in the call record is earlier than the time that is specified in this parameter.

serviceProvider

String

(Optional) Selects a call record if the service provider of the caller or callee matches this name. The service provider name in the call record must match this name exactly.

organization

String

(Optional) Selects a call record if the organization of the caller or callee matches this name. The organization name in the record must match this name exactly.

callTypeList

String

(Optional) List of call types. The service selects a call record if the call type field in the record matches one of the specified values. The call type values are described in Table 4-1.

companyScope

String

(Optional) Selects a call record if the company scope field in the record matches the specified value. Table 4-2 describes the company scope values.


The service returns a getCallDetailRecordsCountResult in the service response. Table 4-4 describes the elements in the getCallDetailRecordsCountResult.

Table 4-4 Get Call Details Records Count Result 

Parameter
Type
Description

totalNumberFound

Integer

The total number of records that are returned. The value is zero if the filter criteria did not match any call records.


getCallDetailRecords

Revised January 30, 2013

The getCallDetailRecords service returns a list of records that meet the criteria that are supplied in the request. Table 4-5 describes the parameters in the service request.

Table 4-5 getCallDetailRecords Request

Parameter
Type
Description

startTimeFrom

String

(Optional) Selects call records for which the start time of the call is equal to or later than the time that is specified in this parameter.

startTimeTo

String

(Optional) Selects call records for which the start time of the call is earlier than the time that is specified in this parameter.

endTimeFrom

String

(Optional) Selects call records for which the end time of the call is equal to or later than the time that is specified in this parameter.

endTimeTo

String

(Optional) Selects call records for which the end time of the call is earlier than the time that is specified in this parameter.

meetingID

String

(Optional) Specifies the meeting identifier. All records that are associated with this meeting ID are retrieved.

serviceProvider

String

(Optional) Selects a call record if the service provider of the caller or callee matches this name. The service provider name in the call record must match this name exactly.

organization

String

(Optional) Selects a call record if the organization of the caller or callee matches this name. The organization name in the record must match this name exactly.

callTypeList

String

(Optional) List of call types. The service selects a call record if the call type field in the record matches one of the specified values. The call type values are described in Table 4-1.

companyScope

String

(Optional) Selects a call record if the company scope field in the record matches the specified value. Table 4-2 describes the company scope combined value.

firstIndex

Integer

(Optional) The index value of the first call record within the response message. Pagination uses this value.

Note For details on managing how many records the Cisco TelePresence Exchange System returns to the API client, see the "Pagination" section.

numberOfRecords

Integer

(Optional) The maximum number of call records that will be included in the response message.

Note For details on managing how many records the Cisco TelePresence Exchange System returns to the API client, see the "Pagination" section.


The service returns a getCallDetailRecordsResult in the service response. Table 4-6 describes the getCallDetailRecordsResult.

Table 4-6 getCallDetailsRecordsResult 

Parameter
Type
Description

callDetailRecords

Complex

List of apiCallDetailRecord elements. See Table 4-7 for a description of apiCallDetailRecord.

totalNumberFound

Integer

The total number of records returned. The value is zero if the query does not match any rooms.


Table 4-7 describes the apiCallDetailRecord element.

Table 4-7 apiCallDetailRecord Element 

Parameter
Type
Description

callType

String

The call type in the record. The call type values are described in Table 4-1.

callee

String

The value of the callee field is dependent on the callType as follows:

•DIRECTDIAL—E.164 number or the username part of the SIP URI (the characters that precede the @ symbol in the SIP URI) of the called endpoint (callee).

•MEETME_INCOMING—Service number that the calling endpoint (caller) dials to reach the service for the meeting.

•MEETME_OUTGOING—E.164 number or the username part of the SIP URI (the characters that precede the @ symbol in the SIP URI) of the called endpoint (callee).

calleeAlternateIdentities

String

Alternate identifier of the called endpoint (callee), such as an IP address.

calleeOrganization

String

The value of the calleeOrganization field is dependent on the callType as follows:

•DIRECTDIAL—Organization of the called endpoint (callee).

•MEETME_INCOMING—Organization of the meeting scheduler.

•MEETME_OUTGOING—Organization of the called endpoint (callee).

Note If the Cisco TelePresence Exchange System cannot determine a value for this field, the value is null.

calleeRegion

String

The value of the calleeRegion field is dependent on the callType as follows:

•DIRECTDIAL—Region of the service provider SBC of the called endpoint (callee).

•MEETME_INCOMING—Region in which the media bridge resource allocated for the meeting is hosted.

•MEETME_OUTGOING—Region of the service provider SBC of the called endpoint (callee).

Note If the Cisco TelePresence Exchange System cannot determine a value for this field, the value is null.

calleeServiceProvider

String

The value of the calleeServiceProvider field is dependent on the callType as follows:

•DIRECTDIAL—Service provider of the called endpoint (callee).

•MEETME_INCOMING—Service provider hosting the meeting.

•MEETME_OUTGOING—Service provider of the called endpoint (callee).

Note If the Cisco TelePresence Exchange System cannot determine a value for this field, the value is null.

caller

String

The value of the caller field is dependent on the callType as follows:

•DIRECTDIAL—E.164 number or the username part of the SIP URI (the characters that precede the @ symbol in the SIP URI) of the calling endpoint (caller).

•MEETME_INCOMING—E.164 number or the username part of the SIP URI (the characters that precede the @ symbol in the SIP URI) of the calling endpoint (caller).

•MEETME_OUTGOING—Internal number of the media bridge resource that initiated the dial out call.

callerAlternateIdentities

String

Alternate identifier of the calling endpoint (caller), such as an IP address.

callerOrganization

String

The value of the callerOrganization field is dependent on the callType as follows:

•DIRECTDIAL—Organization of the calling endpoint (caller).

•MEETME_INCOMING—Organization of the calling endpoint (caller).

•MEETME_OUTGOING—Organization of the meeting scheduler.

Note If the Cisco TelePresence Exchange System cannot determine a value for this field, the value is null.

callerRegion

String

The value of the callerRegion field is dependent on the callType as follows:

•DIRECTDIAL—Region of the service provider SBC of the calling endpoint (caller).

•MEETME_INCOMING—Region of the service provider SBC of the calling endpoint (caller).

•MEETME_OUTGOING—Region in which the media bridge resource allocated for the meeting is hosted.

Note If the Cisco TelePresence Exchange System cannot determine a value for this field, the value is null.

callerServiceProvider

String

The value of the callerServiceProvider field is dependent on the callType as follows:

•DIRECTDIAL—Service provider of the calling endpoint (caller).

•MEETME_INCOMING—Service provider of the calling endpoint (caller).

•MEETME_OUTGOING—Service provider hosting the meeting.

Note If the Cisco TelePresence Exchange System cannot determine a value for this field, the value is null.

companyScope

String

Specifies the company scope. Table 4-2 describes the company scope values.

conferenceParticipantDisconnectCode

Integer

Numerical value. See Table 4-8 for a description of the parameters that correspond to the numerical values.

conferenceParticipantDisconnectReason

String

Additional disconnect information, when available.

conferenceParticipantJoinTime

String

Time that the meeting participant joined the meeting. The time is in ISO8601 format.

Note The Cisco TelePresence Exchange System does not consider the participant as having joined the meeting until after any interaction with the IVR prompts is complete.

conferenceParticipantLeaveTime

String

Time that the participant left the meeting. The time is in ISO8601 format.

conferenceParticipantResourceID

String

Concatenation of the resource name and IP address of the Cisco TelePresence Multipoint Switch or Cisco TelePresence MSE 8000 Series system that is involved in the meeting.

disconnectCauseCode

Integer

Q.850 or SIP cause code.

Note For H.323 and ISDN calls, the value of this field is the same as conferenceParticipantDisconnectCode.

disconnectCauseStr

String

Text description of the disconnect cause.

Note For H.323 and ISDN calls, the value of this field is the same as conferenceParticipantDisconnectReason.

disconnectData

String

Additional information to describe the disconnect cause.

duration

Integer

Length of time in minutes from the startTime to the endTime of the call.

endTime

String

Time the Caller or Callee disconnects from the call. The time is in ISO8601 format.

guid

String

Globally unique identifier for a call. The CDR for each call leg contains the same GUID.

id

String

Unique identifier for CDR in the Cisco TelePresence Exchange System database.

isHost

Boolean

Set to TRUE if the participant joined the meeting as the host.

meetingID

String

Unique identifier for a Meet-Me or Rendezvous meeting. This is the number that the participant dials from the endpoint keypad to access the meeting after dialing the main access number.

Note For direct dial calls or if the participant never joins the meeting, the value for this field is null.

meetingInstanceID

Integer

This indicates the instance number of a Rendezvous meeting. The number starts at 0 for the first instance and increments by one for each successive instance of the Rendezvous meeting. For other meeting types, the value is always 0.

meetingKey

String

Unique key that the system database uses to access the Meet-Me or Rendezvous meeting. Scheduling API methods such as getMeeting, modifyMeeting, and cancelMeeting require the meetingKey as a parameter.

Note For direct dial calls or if the participant never joins the meeting, the value of this field is null.

requiredCapacity

Integer

The number of media bridge resource segments that the Cisco TelePresence Exchange System allocated to the endpoint when it joined the meeting.

serverIP

String

IP address of the call engine.

serverName

String

Hostname of the call engine that the administrator assigns during installation.

startTime

String

The time the called endpoint (callee) answers the call. The time is in ISO8601 format.

videoBandwidth

String

Video bandwidth used by the participant. This parameter is relevant only for Meet-Me meeting calls.

For a SIP endpoint, the value is determined based on the last maximum negotiated bandwidth from the SIP messages exchanged between the client and MCU.

For an H323 or ISDN endpoints, the value is reported from the MCU.


Table 4-8 describes the conferenceParticipantDisconnectCode elements.

Table 4-8 conferenceParticipantDisconnectCode Element 

Value
Description

1

Indicates normal disconnect (the participant disconnected from the call).

2

Indicates that the SIP INVITE to the bridge has been rejected.

3

Indicates that the SIP INVITE to the bridge has timed out.

4

Indicates that the outgoing leg to the bridge is in a hung state.

5

Indicates that the meeting ended with a participant connected to the call.

6

Indicates that the caller is already connected to another meeting.

7

Indicates that the caller was rejected because of its presence on a blacklist.

8

Indicates that the bridge resource is offline.

9

Participant was disconnected by a third party.

10

Participant disconnected for an unknown reason.

11

Participant was disconnected because the host disconnected from the meeting.

12

Bridge disconnected because all participants disconnected from the meeting. 


 
   
 
     
    
    
   
 purgeCallDetailRecords 
 
    
   
 The Purge Call Detail Records service deletes the set of records that are specified by the criteria in the request and returns the number of call records that were deleted. 
 
    
   
 The Cisco TelePresence Exchange System retains CDRs for up to 30 days from the recorded end time of the CDR. The system automatically purges CDRs that exceed this 30-day limit. If the total number of CDRs retained by the system reaches 100,000, the system retains only the most recent 100,000 records and automatically purges the rest. 
 
    
   
 Table 4-9 describes the parameters in the service request. 
 
    
   
 
 
   
 
    
 
      
       
       
      
 Table 4-9 purgeCallDetailRecordsCount Request 
 
      
      
      
 
        
        

          Parameter 
        
 		 
        
        

          Type 
        
 		 
        
        

          Description 
        
 		 
      
 
      
 
       
 startTimeFrom 
 		 
       
 String 
 		 
       
 (Optional) Selects call records for which the start time of the call is equal to or later than the time that is specified in this parameter. 
 		 
      
 
      
 
       
 startTimeTo 
 		 
       
 String 
 		 
       
 (Optional) Selects call records for which the start time of the call is earlier than the time that is specified in this parameter. 
 		 
      
 
      
 
       
 endTimeFrom 
 		 
       
 String 
 		 
       
 (Optional) Selects call records for which the end time of the call is equal to or later than the time that is specified in this parameter. 
 		 
      
 
      
 
       
 endTimeTo 
 		 
       
 String 
 		 
       
 (Optional) Selects call records for which the end time of the call is earlier than the time that is specified in this parameter. 
 		 
      
 
      
 
       
 serviceProvider 
 		 
       
 String 
 		 
       
 (Optional) Selects a call record if the service provider of the caller or callee matches this name. The service provider name in the call record must match this name exactly. 
 		 
      
 
      
 
       
 organization 
 		 
       
 String 
 		 
       
 (Optional) Selects a call record if the organization of the caller or callee matches this name. The organization name in the record must match this name exactly. 
 		 
      
 
      
 
       
 callTypeList 
 		 
       
 Enumeration 
 		 
       
 (Optional) You can specify the call types of the records to be purged. The call type values are described in Table 4-1. 
 		 
      
 
      
 
       
 companyScope 
 		 
       
 String 
 		 
       
 (Optional) Selects a call record if the company scope field in the record matches the specified value. Table 4-2 describes the company scope values. 
 		 
      
 
      
    
 
   
 
   
 
   
 
 
    
   
 Table 4-10 describes the elements in the Purge Call Detail Records result. 
 
    
   
 
 
   
 
    
 
      
       
       
      
 Table 4-10 Purge Call Details Records Result  
 
      
      
      
 
        
        

          Parameter 
        
 		 
        
        

          Type 
        
 		 
        
        

          Description 
        
 		 
      
 
      
 
       
 totalNumberPurged 
 		 
       
 Integer 
 		 
       
 The total number of records that were deleted. The value is zero if the query did not match any call records. 
 		 
      
 
      
    
 
   
 
   
 
   
 
 
     
    
    
   
 Performing API-Related Tasks 
 
    
   
 Each of the Cisco TelePresence Exchange System APIs supports a common set of methods, which are described in the following sections: 
 
    
   
 •echo 
 
    
   
 •getVersion 
 
     
    
    
   
 echo 
 
    
   
 The Echo service allows the system to confirm that the Scheduling API service is active. 
 
    
   
 For additional details about this service, see the "echo" section. 
 
     
    
    
   
 getVersion 
 
    
   
 The Get Version service returns the product software version. For additional details about this service, see the "getVersion" section. 
 
     
    
    
   
 Error Handling 
 
    
   
 The Cisco TelePresence Exchange System API communicates an error condition to the client by returning a SOAP fault message. The fault message contains an APICdrException, which is described in Table 4-11. 
 
    
   
 
 
   
 
    
 
      
       
       
      
 Table 4-11 APICdrException  
 
      
      
      
 
        
        

          Parameter 
        
 		 
        
        

          Type 
        
 		 
        
        

          Description 
        
 		 
      
 
      
 
       
 erc 
 		 
       
 String 
 		 
       
 Exception return code, as described in Table 4-12. 
 		 
      
 
      
 
       
 message 
 		 
       
 String 
 		 
       
 A text message that provides additional information about the exception. The content of the message varies depending on the exception code. 
 		 
      
 
      
    
 
   
 
   
 
   
 
 
    
   
 Table 4-12 describes the CDR exception values. 
 
    
   
 
 
   
 
    
 
      
       
       
      
 Table 4-12 CDR Exception Values  
 
      
      
      
 
        
        

          Exception Value 
        
 		 
        
        

          Description 
        
 		 
      
 
      
 
       
 ERC_EXCEPTION 
 		 
       
 General exception. See the message element for more information about the exception. 
 		 
      
 
      
 
       
 ERC_MISSING_PARAMETER 
 		 
       
 One or more of the required parameters is missing. 
 		 
      
 
      
 
       
 ERC_INVALID_VALUE 
 		 
       
 One or more of the supplied parameters is invalid. The message text lists the invalid parameters. 
 		 
      
 
      
 
       
 ERC_INVALID_DATE_TIME 
 		 
       
 The supplied date/time string is not valid. 
 		 
      
 
      
 
       
 ERC_SERVICE_PROVIDER_NOT_FOUND 
 		 
       
 An invalid service provider name was specified in the request. 
 		 
      
 
      
 
       
 ERC_ORGANIZATION_NOT_FOUND 
 		 
       
 An invalid organization name was specified in the request. 
 		 
      
 
      
 
       
 ERC_MEETING_NOT_FOUND 
 		 
       
 An invalid meeting ID was specified in the request.