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.
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:
This section describes how to get started with the CDR API and includes the following topics:
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.
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.
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
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.
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.
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:
Several of the CDR API service requests and responses include a callType element, which is described in Table 4-1.
Several of the CDR API service requests and responses include a companyScope element, which is described in Table 4-2.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
Each of the Cisco TelePresence Exchange System APIs supports a common set of methods, which are described in the following sections:
•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.
The Get Version service returns the product software version. For additional details about this service, see the "getVersion" section.
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.
|
|
|
---|---|---|
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.