API User Guide for the Cisco TelePresence Exchange System Release 1.1
Backward Compatibility
Downloads: This chapterpdf (PDF - 110.0KB) The complete bookPDF (PDF - 1.02MB) | Feedback

Backward Compatibility

Table Of Contents

Backward Compatibility

Preparing For Backward Compatibility

Enabling Backward Compatibility

Scheduling API

Using the Release 1.0 API to Schedule, Modify, and Cancel Meetings

Conceptual Enhancements For Release 1.1

Meet-Me Meetings

Rendezvous Meetings

Scheduling Exception Values

Hybrid-Mode Operation Not Supported

Hybrid-Mode Meet-Me Meeting Scenarios

Hybrid-Mode Rendezvous Meeting Scenarios

Hybrid-Mode and Remote Meetings

Hybrid-Mode and Two-Party Direct Meetings

CDR API


Backward Compatibility


Revised January 30, 2013

This appendix provides notes on backward compatibility with Cisco TelePresence Exchange System Release 1.0, and includes the following sections:

Preparing For Backward Compatibility

Enabling Backward Compatibility

Scheduling API

CDR API

Preparing For Backward Compatibility

Before upgrading to Cisco TelePresence Exchange System Release 1.1, ensure that you have retrieved all existing CDR records. Any Release 1.0 records that remain will be purged when upgrading to Release 1.1.

Enabling Backward Compatibility

After upgrading to Cisco TelePresence Exchange System Release 1.1, you must explicitly enable the Release 1.0 API in order to use backward compatibility.

Procedure

To enable backward compatibility, do the following procedure:


Step 1 From the navigation pane, choose System > Backward Compatibility.

The Backward Compatibility window is displayed.

Step 2 In the SOAP API Versions box, check the 1.0.x check box.

Step 3 From the Default Service Number drop-down list, choose a service number to use when scheduling meetings via the Release 1.0 API. A service number is required when scheduling meetings in Release 1.1, but cannot be specified by using the Release 1.0 API.

For more information on service numbers, see the "Configuring Service Numbers" section in the "Configuring Collaboration Services" chapter of the Installation and Administration Guide for the Cisco TelePresence Exchange System Release 1.1.

Step 4 From the Default Reservation Type drop-down list, choose a reservation type to use when scheduling meetings via the Release 1.0 API. A reservation type is required when scheduling meetings in Release 1.1, but cannot be specified by using the Release 1.0 API.

For more information on reservation types, see the "Configuring Reservation Types" section in the "Configuring Collaboration Services" chapter of the Installation and Administration Guide for the Cisco TelePresence Exchange System Release 1.1.

Step 5 To save your changes, click Save.


Scheduling API

The following information pertains to using the scheduling API in backward compatibility mode:

Using the Release 1.0 API to Schedule, Modify, and Cancel Meetings

Conceptual Enhancements For Release 1.1

Hybrid-Mode Operation Not Supported

Using the Release 1.0 API to Schedule, Modify, and Cancel Meetings

Clients using the Release 1.0 API can successfully schedule, modify, and cancel meetings on a Cisco TelePresence Exchange System Release 1.1 system. The steps will be typically:

1. The Release 1.0 system has an operational scheduling portal using the Release 1.0 APIs.

2. The Release 1.0 system is upgraded to Release 1.1. Existing meetings are correctly migrated to the new Release 1.1 schemas.

3. The existing scheduling portal based on the Release 1.0 APIs continues to work, with both newly created meetings and meetings migrated during the upgrade to Release 1.1. The existing scheduling portal is used while the service provider finishes developing the Release 1.1 compatible portal.

4. The existing scheduling portal is replaced by the new scheduling portal based on Release 1.1. New meetings are created successfully and previously scheduled meetings can be modified successfully.

Here are a few caveats when using the Release 1.0 API with a Release 1.1 system:

None of the new user-facing Release 1.1 features are accessible through the Release 1.0 API. This includes Host PINs, Automatic Meeting Extension, and Multiple Language IVRs.

For scheduling failures, the English text message may contain references to new Release 1.1 concepts that are not present in Release 1.0. For example, bridge resource capabilities in Release 1.0 have been replaced by the more general media profile concept in Release 1.1. Even though the Release 1.0 API will continue to support the usage of bridge resource capabilities, the Release 1.1 back-end will necessarily translate these to media profiles. Therefore, any exceptions related to these will refer to media profiles in the English text message.

Other than these caveats, the Release 1.0 portal clients should be able to operate normally against a Release 1.1 system.

Conceptual Enhancements For Release 1.1

Cisco TelePresence Exchange System Release 1.1 includes several conceptual enhancements that need to be noted when using the Release 1.0 API in the backward compatibility mode. In some cases, objects exposed in the Release 1.0 API were replaced and enhanced for Release 1.1. A few parameters were removed altogether.

The following sections list the changes:

Meet-Me Meetings

Rendezvous Meetings

Scheduling Exception Values

Meet-Me Meetings

In the Release 1.0 API, the unprovisioned endpoint object contained an attribute for endpoint protocol (e.g. SIP). For Release 1.1, unprovisioned endpoints instead contain a reference to a media profile, which in turn contains the protocol and other attributes.

In the Release 1.0 API, there was an ability to specify one or more bridge resource capabilities (e.g. SUPPORT_ANY_CTS) for the meeting. For Release 1.1, there is instead an ability to specify one or more media profiles, which in turn contain equivalent information.

Rendezvous Meetings

The Release 1.0 API refers to these as reservationless meetings. The Release 1.1 API uses the new terminology: Rendezvous meetings.

In Release 1.0, Rendezvous (i.e. reservationless) meetings were scheduled with a start time and a duration. These were largely ignored. In Release 1.1, these are removed from the method parameters.

In Release 1.0, Rendezvous meeting capacity was measured simply using maximum capacity. For Release 1.1, this is separated for clarity into number of endpoints and additional capacity.

As for Meet-Me meetings, the bridge resource capabilities for the meeting are replaced by the media profiles.

Scheduling Exception Values

Added January 30, 2013

In Release 1.0, if the Cisco TelePresence Manager is offline, the Cisco TelePresence Exchange System throws an ERC_CTSMAN_COMMUNICATION_FAILURE exception with the cause code CTSMAN_CONNECTION_ERROR. However, in Release 1.1, the system does a preemptive online validation and, if the Cisco TelePresence Manager is offline, throws an ERC_RESOURCE_UNAVAILABLE exception with the cause code CTSMAN_RESOURCE_NOT_AVAILABLE.

Hybrid-Mode Operation Not Supported

Hybrid-mode operation is using the Release 1.0 API to modify meetings that were created either from the Release 1.1 administration console or the Release 1.1 API. The Cisco TelePresence Exchange System does not support hybrid mode operation. The portal client application will likely maintain its own data for each scheduled meeting and only allow modifications on meetings that it knows about. Therefore it will not typically be aware of any meetings scheduled through the Cisco TelePresence Exchange System administration console "back door." The only way that the portal client can know of these meetings is to separately query for meetings using broad criteria (e.g. created within a certain time interval).

If administrators insist on supporting this mixed-mode operation, see the following sections for details on how the system behaves for each meeting type:

Hybrid-Mode Meet-Me Meeting Scenarios

Hybrid-Mode Rendezvous Meeting Scenarios

Hybrid-Mode and Remote Meetings

Hybrid-Mode and Two-Party Direct Meetings

Hybrid-Mode Meet-Me Meeting Scenarios

In Release 1.1, Schedule Meeting With No Specific Release 1.1 Features

When using the Release 1.0 API, most modifications happen as expected. Endpoints, capacity, start time, duration, etc., can be successfully changed. Bridge capabilities can be changed and the corresponding media profiles will be associated with the meeting. Unprovisioned dial-out endpoints can have their protocols changed and the corresponding media profiles will then be associated with the endpoints.

In Release 1.1, Schedule Meeting With Release 1.1 Features

Here, the meeting was scheduled with one or more Release 1.1 features, such as host pin or meeting extension. When using the Release 1.0 API, if the meeting is modified to change endpoints, capacity, start time, duration, etc., those changes will be applied as expected. However, any Release 1.1 features associated with the meeting will be explicitly disabled.

Release 1.1, Schedule Meeting With Parameters Different From Backward Compatibility Configuration

Here, the meeting was scheduled using a different service number or reservation type than what was defined in the backward compatibility settings within the Release 1.1 administration console. When using the Release 1.0 API, if the meeting is modified to change endpoints, capacity, start time, duration, etc., those changes will be applied as expected. However, the service number and reservation type will be forced to what is defined in the backward compatibility settings. Note that the reservation type change may lead to an unexpected failure if the corresponding bridge capacity cannot be reserved with this reservation type.

Hybrid-Mode Rendezvous Meeting Scenarios

In Release 1.1, Schedule Rendezvous Meeting With No Specific Release 1.1 Features

When using the Release 1.0 API, the capacity can be changed but this will only affect the additional capacity of the meeting. This will not impact the number of endpoints as scheduled within Release 1.1 administration console. The total capacity of the meeting will reflect the sum of these. Bridge capabilities can be changed and the corresponding media profiles will be associated with the meeting.

In Release 1.1, Schedule Meeting With Release 1.1 Features

Here, the meeting was scheduled with a Release 1.1 feature such as host pin. When using the Release 1.0 API, if the meeting is modified to change capacity, bridge resource type, etc., those changes will be applied as expected. However, the Release 1.1 features associated with the meeting will be explicitly disabled.

In Release 1.1, Schedule Meeting With Parameters Different From Backward Compatibility Configuration

As with Meet-Me meetings (see above), any modification from the Release 1.0 API will force the service number and reservation type to be what is defined in the backward compatibility settings. Note that only one reservation type can be specified for backward compatibility, so a decision needs to be made whether Meet-me or Rendezvous meetings will be accessible using backwards compatibility.

Hybrid-Mode and Remote Meetings

The only difference here is that the unprovisioned endpoints have a protocol attribute in the Release 1.0 API and this has been generalized to a media profile reference in Release 1.1. Otherwise, all modifications using the Release 1.0 API should work correctly and as expected.

Hybrid-Mode and Two-Party Direct Meetings

There are no differences here. All modifications using the Release 1.0 API should work correctly and as expected.

CDR API

The following call detail record changes apply when using the Release 1.0 CDR API on a Release 1.1 System.

InterSP Incoming Direct Dial

If InterSP Incoming Direct Dial calls are enabled, CDR data retrieved from the Cisco TelePresence Exchange SystemAPI will have these calls mapped to the INTERSP_OUTGOING callType category.

Host PIN and Active Meeting Management Feature

Below are additional disconnect codes in Release 1.1. These are generated if Host PIN or Active Meeting Management (AMM) feature in Release 1.1 is used.

11 - Participant disconnected because host left.

12 - Bridge disconnected because all participants left

SIP Dial Out

Calls dialed out from a resource (for endpoints with SIP/TIP Media Profile) will be returned under the TPS_Dialout callType.

Rendezvous Meeting

If the Rendezvous meeting feature from Release 1.1 is used, then CDRs will contain the same meeting ID for all instances.

Fields deprecated

The following attributes have been deprecated in Release 1.1. (No value will be returned for these)

callNetwork

Sdp

cdrRecordType

calleeType

callerType

For Release 1.0, these were deemed to be incomplete and inconsistent.

CDR Purging

Purge API is not supported in backward compatibility mode. We recommend that you do not use the purge API in backward compatibility mode.

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.

callType Element Mapping

The following table maps the Release 1.0 CDR API callType values to the new Release 1.1 CDR API callType values. When you use the Release 1.0 CDR API on a Release 1.1 system, the Release 1.0 callType values are displayed in the CDRs.

Release 1.0 callType
Release 1.1 callType

UNKNOWN

No equivalent value in Release 1.1.

MEETME

MEETME_INCOMING

DIRECTDIAL

DIRECTDIAL

INTERSP_INCOMING

MEETME_INCOMING

INTERSP_OUTGOING

DIRECTDIAL

TPS_DIALOUT

MEETME_OUTGOING