API User Guide for the Cisco TelePresence Exchange System Release 1.0
API for Call Detail Records
Downloads: This chapterpdf (PDF - 204.0KB) The complete bookPDF (PDF - 614.0KB) | Feedback

API for Call Detail Records

Table Of Contents

API for Call Detail Records

Getting Started

CDR API Overview

Time Fields

Obtaining the WSDL

Filtering CDRs

Pagination

Retrieving CDR Records

Call Type Element

companyScope Element

getCallDetailRecordsCount

getCallDetailRecords

purgeCallDetailRecords

Performing API-Related Tasks

echo

getVersion

Error Handling


API for Call Detail Records


Revised June 29, 2011

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:

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

Time Fields

Obtaining the WSDL

CDR API Overview

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.

Time Fields

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

Obtaining the WSDL

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.

Filtering CDRs

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.

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 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.

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:

Call Type Element

companyScope Element

getCallDetailRecordsCount

getCallDetailRecords

purgeCallDetailRecords

purgeCallDetailRecords

Call Type Element

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

Table 2-1 Call Type Element 

Parameter
Type
Description

callType

String

The call type field contains one of the following string values:

UNKNOWN—Call type is unknown.

The Unknown field value is typically not used as a request filtering parameter. To receive all call types in the response, the client must set the callType filter parameter to null.

MEETME—Meet-Me call leg for a CTS end point.

DIRECTDIAL—Direct Dial.

INTERSP_INCOMING—Call originates from an endpoint on a remote service provider and connects to a meeting on this Cisco TelePresence Exchange System.

INTERSP_OUTGOING—Call originates from an endpoint that is associated with a service provider on this Cisco TelePresence Exchange System, and that connects to an external meeting that is hosted by another service provider whose service might not be on a Cisco TelePresence Exchange System.

TPS_DIALOUT—Interop leg of a Meet-Me call that is handled by the 8710.


companyScope Element

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

Table 2-2 Company Scope Element 

Parameter
Type
Description

companyScope

String

The companyScope parameter is relevant only for the DIRECTDIAL callType.

The companyScope 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 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.

Table 2-3 Get Call Detail Records Count 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) 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.

Table 2-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

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.

Table 2-5 Get Call Detail Records Element 

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) 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.

Table 2-6 Get Call Details Records Result 

Parameter
Type
Description

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.

Table 2-7 apiCallDetailRecord Element 

Parameter
Type
Description

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.

Table 2-8 conferenceParticipantDisconnectCode Element 

Value
Parameter
Description

1

DISCONNECT_CODE_NORMAL

Indicates that the incoming leg is in a hung state.

2

DISCONNECT_CODE_INVITE_REJECT

Indicates that the INVITE to the Cisco TelePresence Multipoint Switch has been rejected.

3

DISCONNECT_CODE_INVITE_TIMEOUT

Indicates that the INVITE to the Cisco TelePresence Multipoint Switch has timed out.

4

DISCONNECT_CODE_CTMS_HANGUP

Indicates that the outgoing leg to the Cisco TelePresence Multipoint Switch is in a hung state.

5

DISCONNECT_CODE_MEETING_END

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

6

DISCONNECT_CODE_DUPLICATE_CALL

Indicates that the caller is already connected to another meeting.

7

DISCONNECT_CODE_IXL_POLICY_REJECT

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

8

DISCONNECT_CODE_RESOURCE_OFFLINE

Indicates that the bridge resource is offline.


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>

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.

Table 2-9 describes the Purge Call Detail Records elements.

Table 2-9 Purge Call Detail Records Count Element 

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) 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.

Table 2-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

See the following sections:

echo

getVersion

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-11 Echo Request Parameters 

Parameter
Type
Description

echoString

String

(Required) Enter an arbitrary string. The same string is returned in the response message.

Note The Cisco TelePresence Exchange System throws an exception when this value is missing.


Table 2-12 describes the parameters in the Echo service response.

Table 2-12 Echo Response Parameters 

Parameter
Type
Description

return

String

The value of the string is identical to the string that was sent in the request message.


getVersion

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.

Table 2-13 Get Version Response Parameters 

Parameter
Type
Description

return

String

The string contains the build version of the CDR API.


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 2-14.

Table 2-14 API CDR Exception 

Parameter
Type
Description

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.

Table 2-15 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.