API User Guide for the Cisco TelePresence Exchange System Release 1.1

Bias-Free Language

The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.

Book Contents

Find Matches in This Book

Available Languages

Download Options

Book Title

API User Guide for the Cisco TelePresence Exchange System Release 1.1

Chapter Title

Call Detail Record API

PDF - Complete Book (1.02 MB) PDF - This Chapter (186.0 KB)
View with Adobe Reader on a variety of devices

Results

Updated:: June 19, 2012

Chapter: Call Detail Record API

Getting Started
Filtering CDRs
Pagination
Retrieving CDR Records
Performing API-Related Tasks
- echo
- getVersion
Error Handling

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.

Was this Document Helpful?

Feedback

Contact Cisco

Open a Support Case
(Requires a Cisco Service Contract)