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 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 provides services 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.
In the CDR API, the date and time fields are stored in ISO 8601 format. Specifically, a calendar date has the following format: YYYY-MM-DD and the time of day employs a 24-hour time period. The letter T is used to separate the date and time fields. All times are UTC.
For example, the API would store the date of February 11, 2011 and the time of 12:00 PM PDT as follows:
2011-11-02T19:00:00-07:00
You can access the WSDL file for the Scheduling API at
http://<DNS name or IP address for your admin server>:8080/ctxapi/api/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.
You can set a filter for all get, get count, and purge requests. By default, a request operates on all records that are defined for that command unless the API client specifies a subset of records for the get request.
Each of the filter parameters is optional. When the API client leaves all parameters set to null, the get, get count, and purge commands apply to all records. To narrow the scope of the request, the client must set one or more of the filter parameters to non-null.
For example, a client 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, the client sets the organization and the time range parameters appropriately, and leaves 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 example, to limit the system to return only 100 records per response to the API client, you would set the numberOfRecords parameter to 100 and set the firstIndex to the following sequence:
firstIndex = 0 for the first group of records, 100 for the second group of records, 200 for the third group of records, and so on for each subsequent group of records.
As long as the Cisco TelePresence Exchange System returns the 100 records in the response as the API client expects, the client will request the next portion of records. When the system returns fewer than 100 records in the response, the client can assume that it has received the last block of records and that no more requests are necessary.
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 call type element, which is described in Table 2-1.
Several of the CDR API service requests and responses include a Company Scope element, which is described in Table 2-2.
The Get Call Detail Records Count 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 Get Call Detail Records Count element. Table 2-3 describes the parameters in a Get Call Detail Records Count request. For each parameter that is set to null, the client 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) Specifies the service provider name. The service provider name that is specified in the records to be retrieved must match this name exactly. |
organization |
String |
(Optional) Specifies the organization name. The organization name that is specified in the records to be retrieved must match this name exactly. |
callType |
String |
(Optional) Selects a call record if the call type field in the record matches the specified value. The call type values are described in Table 2-1. |
The service returns a Get Call Detail Records Count Result in the service response. Table 2-4 describes the elements in the Get Call Detail Records Result.
The Get Call Detail Records service returns a list of records that meet the criteria that are supplied in the request. Table 2-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) Specifies the service provider name. The service provider name that is in the records to be retrieved must match this name exactly. |
organization |
String |
(Optional) Specifies the organization name. The organization name that is in the records to be retrieved must match this name exactly. |
callType |
String |
(Optional) You can specify the call type of the records to be retrieved. Table 2-1 describes the call type values. |
companyScope |
String |
(Optional) Selects a call record if the company scope field in the record matches the specified value. Table 2-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 Get Call Detail Records Result in the service response. Table 2-6 describes the Get Call Detail Records Result.
|
|
|
---|---|---|
callDetailRecords |
Complex |
List of apiCallDetailRecord elements. See Table 2-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 2-7 describes the apiCallDetailRecord element.
|
|
|
---|---|---|
callNetwork |
String |
Name of the network. |
callType |
String |
The call type in the record. The call type values are described in Table 2-1. |
callee |
String |
E.164 number of the called party. |
calleeAlternateIdentities |
String |
Alternate identifier for the called party, such as an IP address. |
calleeRegion |
String |
Region of the called party. |
calleeOrganization |
String |
Organization of the called party. |
calleeServiceProvider |
String |
Service provider of the called party. |
calleeType |
Integer |
Type of the called party. This field always has the value E.164 number. |
caller |
String |
E.164 number of the calling party. |
callerAlternateIdentities |
String |
Alternate identifier for the calling party, such as an IP address. |
callerRegion |
String |
Region of the calling party. |
callerOrganization |
String |
Organization of the calling party. |
callerServiceProvider |
String |
Service provider of the calling party. |
callerType |
Integer |
Type of the calling party. This field always has the value E.164 number. |
cdrRecordType |
Integer |
Value of zero (0) indicates that the record relates to a call. The client does not support any other values in this release. |
conferenceParticipantDisconnectCode |
Integer |
Numerical value from 1 to 8. See Table 2-8 for a description of the parameters that correspond to the numerical values. |
conferenceParticipantJoinTime |
Integer |
Time that the participant joins the meeting. The time is in ISO8601 format. |
conferenceParticipantReason |
Integer |
Additional disconnect information, when available. |
conferenceParticipantResourceID |
Integer |
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. |
disconnectCauseStr |
String |
Text description of the disconnect cause. |
disconnectData |
String |
Additional information to describe the disconnect cause. |
duration |
float |
Call duration. |
endTime |
String |
End time of the call. |
guid |
String |
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. |
meetingID |
String |
Unique identifier for the meeting. This is the number that the user dials from the endpoint keypad to access the meeting after dialing the main access number. |
meetingKey |
String |
Unique key that the system database uses to access this meeting. Scheduling API methods such as getMeeting, modifyMeeting, and cancelMeeting require the meetingKey as a parameter. |
requiredCapacity |
Integer |
The number of ports that the Cisco TelePresence Exchange System reserves for an endpoint. For details on the number of segments that are reserved for the endpoint, see the Endpoint Capacity appendix in the Installation and Administration Guide for the Cisco TelePresence Exchange System, at http://www.cisco.com/en/US/docs/telepresence/tx/exchange_system/1_0/install_admin/book/b_install_admin.html. |
sdp |
String |
The contents of the last session description protocol (SDP) message. |
serverIP |
String |
IP address of the call engine. |
serverName |
String |
Hostname of the call engine that the administrator assigns during installation. |
startTime |
String |
Start time of the call. |
videoBandwidth |
String |
Video bandwidth initially negotiated for the call. |
Table 2-8 describes the conferenceParticipantDisconnectCode elements.
Example
The following elements that appear in a CDR will vary depending on the type of call.
<callDetailRecords>
<callNetwork>tp</callNetwork>
<callType>MEETME</callType>
<callee>12826338661</callee>
<calleeAlternateIdentities>10.22.143.156</calleeAlternateIdentities>
<calleeOrganization>ATT</calleeOrganization>
<calleeRegion>San Francisco</calleeRegion>
<calleeServiceProvider>ATT</calleeServiceProvider>
<calleeType>1</calleeType>
<caller>17652468107</caller>
<callerAlternateIdentities>10.22.162.60</callerAlternateIdentities>
<callerOrganization>HostedX</callerOrganization>
<callerRegion>San Francisco</callerRegion>
<callerServiceProvider>ATT</callerServiceProvider>
<callerType>1</callerType>
<cdrRecordType>0</cdrRecordType>
<conferenceParticipantDisconnectCode>5</conferenceParticipantDisconnectCode>
<conferenceParticipantJoinTime>2011-02-15T00:16:52-08:00</
conferenceParticipantJoinTime> <conferenceParticipantResourceID>sol2-ctx2-TPS1:10.22.162.4</
conferenceParticipantResourceID>
<disconnectCauseCode>0</disconnectCauseCode>
<disconnectCauseStr>Call Completed</disconnectCauseStr>
<disconnectData>n/a</disconnectData>
<duration>787.747</duration>
<endTime>2011-02-15T00:30:00.000-08:00</endTime>
<guid>F9951C6CF8A-878D5D42E70-7DB20445267-BF249B176A0</guid>
<id>8a960f1a2dbf4c40012e26b948b70dc5</id>
<meetingID>95436111</meetingID>
<sdp>v=0
o=CODIAN 1297729099 1297729099 IN IP4 10.22.162.4
s=-
i=TANDBERG Telepresence Server 8710 v2.1(1.35)
c=IN IP4 10.22.162.4
b=TIAS:2250000
t=0 0
m=audio 58248 RTP/AVP 96 0 101
a=rtpmap:96 mpeg4-generic/48000
a=fmtp:96 profile-level-id=16;streamtype=5;config=B98C00;mode=AAC-hbr;sizeLength=13;indexLength=3;in
dexDeltaLength=3;constantDuration=480
a=rtpmap:0 PCMU/8000/1
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
m=video 54402 RTP/AVP 112
b=TIAS:2250000
a=rtpmap:112 H264/90000
a=fmtp:112 profile-level-id=42e016;max-mbps=108000;max-fs=3600;packetization-mode=1
a=sendrecv
m=video 57006 RTP/AVP 112
a=rtpmap:112 H264/90000
a=fmtp:112 profile-level-id=42e016;max-mbps=27000;max-fs=3600
a=sendrecv
a=content:slides
a=label:12</sdp>
<serverIP>10.22.143.156</serverIP>
<serverName>sol2-ctx2-engine1</serverName>
<startTime>2011-04-15T00:16:52.000-08:00</startTime>
<videoBandwidth>4000000</videoBandwidth>
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.
Table 2-9 describes the Purge Call Detail Records elements.
|
|
|
---|---|---|
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) Specifies the service provider name. The service provider name that is in the records to be retrieved must match this name exactly. |
organization |
String |
(Optional) Specifies the organization name. The organization name that is in the records to be retrieved must match this name exactly. |
callType |
Integer |
(Optional) You can specify the call type of the records to be retrieved. The call type values are described in Table 2-1. |
Table 2-10 describes the elements in the Purge Call Detail Records result.
See the following sections:
•echo
The Echo service is designed to confirm that the CDR API service is active. The client includes an arbitrary string in the echo request and the response message includes the same string.
Table 2-11 describes the input parameters for the Echo service request.
Table 2-12 describes the parameters in the Echo service response.
|
|
|
---|---|---|
return |
String |
The value of the string is identical to the string that was sent in the request message. |
The Get Version service returns the version of the CDR API. The service request contains no input parameters.
Table 2-13 describes the parameters in the service response.
|
|
|
---|---|---|
return |
String |
The string contains the build version of the CDR API. |
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 2-14.
|
|
|
---|---|---|
erc |
String |
Exception return code, as described in Table 2-15. |
message |
String |
A text message that provides additional information about the exception. The content of the message varies depending on the exception code. |
Table 2-15 describes the scheduling exception values.