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

Scheduling API

Table Of Contents

Scheduling API

Getting Started

Scheduling API Overview

Information Model

Service Provider

Region

Resource Groups and Reservation Types

Organization

Endpoint Types

Endpoint Protocols

Endpoint Capacity

Custom Layouts

Meeting Types

Meeting Extensions

Inherited Values

Obtaining the WSDL

API Versions

Required and Optional Parameters

API Parameter Naming Conventions

Key

Name

Description

Obtaining Configured Information

getEndpointAvailability

getEndpoints

getEndpointsForOrganization

getMediaProfiles

getOrganizations

getOrganizationsForServiceProvider

getPortsByOrganization

getRegions

getRegionsForServiceProvider

getReservationTypes

getServiceNumbers

getServiceProviders

getWhiteListGroups

Scheduling and Managing Meetings

scheduleMeeting

scheduleRendezvousMeeting

scheduleRemoteMeeting

scheduleTwoPartyDirectMeeting

modifyMeeting

modifyRendezvousMeeting

modifyRemoteMeeting

modifyTwoPartyDirectMeeting

cancelMeeting

getMeetings

getMeeting

checkPorts

isEndpointFree

Endpoint Elements

Provisioned Endpoint Fields

Unprovisioned Endpoint Fields

Remote Endpoint Fields

Performing API-Related Tasks

echo

getVersion

Error Handling

getPossibleCauseCodes

Cause Codes

Creating Queries

Query Syntax

Complex Queries

Null Queries

Endpoint Query Properties

Meeting Query Properties

Organization Query Properties

Regions Query Properties

Service Provider Query Properties

Service Number Query Properties

Media Profile Query Properties

Reservation Type Queries

WhiteList Groups Query Properties


Scheduling API


Revised January 30, 2013

The Cisco TelePresence Exchange System provides the Scheduling Application Programming Interface (API) to facilitate the development of scheduling portals and other software applications.

This chapter provides a description of the Scheduling API and includes the following sections:

Getting Started

Obtaining Configured Information

Scheduling and Managing Meetings

Performing API-Related Tasks

Error Handling

Creating Queries

Getting Started

This section describes how to get started with the Scheduling API and includes the following topics:

Scheduling API Overview

Information Model

Obtaining the WSDL

API Versions

Required and Optional Parameters

API Parameter Naming Conventions

Scheduling API Overview

The Scheduling API provides services to accomplish the following tasks:

Obtain configured information

The API provides a selection of Get methods to obtain information about the regions, organizations, endpoints, and so on, that are configured on the Cisco TelePresence Exchange System. These methods are described in the "Obtaining Configured Information" section.

Schedule and manage meetings

The API provides methods to schedule new meetings, modify existing meetings, and cancel meetings. For more details see the "Scheduling and Managing Meetings" section.

Perform tasks that are related to the API

The API provides services that are related to managing the Scheduling API. These methods are described in the "Performing API-Related Tasks" section.

Information Model

The API uses a number of information elements. These elements are described in the following sections:

Service Provider

Region

Resource Groups and Reservation Types

Organization

Endpoint Types

Endpoint Capacity

Custom Layouts

Meeting Types

Meeting Extensions

Inherited Values

Service Provider

A service provider offers telepresence services to a set of business customers (organizations) by using media resources that are provisioned in one or more regions in their network.

The Cisco TelePresence Exchange System provides the ability to customize the service greetings and IVR prompts for each service provider.

Region

A region represents a major geographic area in which a service provider operates.

The region contains one or more resource clusters that generally include either a Cisco TelePresence Multipoint Switch and/or Cisco TelePresence MSE 8000 Series, a Cisco router with integrated voice response (IVR) records, and a Cisco Session Border Controller (SBC). A resource cluster is a connected set of resources in one physical data center and is also known as a point of presence (POP).

All media resources in a region are considered to be equivalent for resource allocation purposes, even if the resources span multiple POPs.

A service provider can be associated with multiple regions that are configured on a Cisco TelePresence Exchange System, and it is possible for a given region to contain resources for different service providers.

Resource Groups and Reservation Types

Resource groups and reservation types provide greater flexibility and control of how media bridge resources are allocated for Meet-Me and Rendezvous meetings.

When configuring a resource group, you choose a specific service provider and region and one or more reservation types to be associated with the group. After the resource group has been created, you associate specific media bridge resources to the group. Based on the set of requirements configured for a meeting (such as service provider, region, reservation type, and endpoint requirements), the system selects the best-fit resource group and associated media bridge resources to use for the meeting.

The reservation type determines whether the system provides a guaranteed or best-effort level of service when reserving a media bridge resource for a Meet-Me or Rendezvous meeting. The reservation type levels of service are defined as follows:

Guaranteed—When you create a guaranteed Meet-Me meeting, the system reserves media bridge resources for the specified meeting duration. For a guaranteed Rendezvous meeting, the system reserves resources for the meeting that can never be used for other meetings.

Best-effort—When you create a best-effort Meet-Me or Rendezvous meeting, the system does not reserve any media bridge resources in advance for the meeting. Instead, the system allocates resources when the first participant joins the meeting and deallocates resources when the last participant leaves the meeting. For a best-effort meeting, the system may fail to allocate resources to the meeting because all the available resources may be in use by other best-effort meetings for the given time period.

You configure Meet-Me meetings, Rendezvous meetings, and resource groups to be associated with specific reservation types. When creating a resource group, you configure the allowable amount of dedicated media resources and meeting booking capacity for each reservation type chosen. Assigning both a guaranteed and best-effort reservation type to a single resource group allows you to dedicate a specific percentage of the resources to guaranteed meetings and another percentage to best-effort meetings. For best-effort meetings, you have the capability to overbook the media bridge resources. Overbooking assumes that all Meet-Me and Rendezvous meetings associated with a specific reservation type will not be active at the same time. By having different levels of overbookings, you can provide different service levels (for example, Gold, Silver, and Bronze) whereby the higher service levels have lower overbooking and thus have a higher likelihood of successful meetings.

Organization

An organization is a business customer that is served by a service provider. An organization controls one or more telepresence endpoints that can be included in a meeting. An organization can choose hosted endpoint service or enterprise endpoint service.

With hosted endpoint service, the service provider operates the telepresence service on behalf of the business customer. Endpoints are managed by a Cisco TelePresence Manager that is owned by the service provider.

With enterprise endpoint service, the enterprise organization operates their conferencing services and the service provider provides inter-company connectivity. Enterprise endpoints are managed by a Cisco TelePresence Manager that is owned by the organization. One-Button-to-Push (OBTP) functionality, which provides easy access to meetings, is not supported for enterprise endpoint service.

Organization Ports Management

Organization ports management allows each organization to optionally control the amount of organization bandwidth that is consumed by telepresence traffic on the network between the organization and the Cisco TelePresence Exchange System.

You specify the maximum number of ports when you configure an organization. The units are segments (screens). The ports required for each endpoint are specified in the endpoint table. If you wish to use organization port management, you can specify the ports that are required by endpoints when you schedule a Meet-Me or remote meeting. (See the "Meeting Types" section for a description of the meeting types.)

When the system schedules a Meet-Me or remote meeting, the port requirement for each organization is calculated, based on the endpoints that are included in the meeting. If the total port capacity for the organization (for all meetings that are scheduled in this time slot) exceeds the maximum value, the system rejects the attempt to schedule this meeting.

Endpoint Types

The Cisco TelePresence Exchange System supports SIP, TIP, and standards-based endpoints from Cisco Systems and third-party suppliers. The system provides full dial-in and dial-out capabilities for SIP and TIP endpoints. The system provides dial-out service to standards-based H.323 and ISDN endpoints.

The Cisco TelePresence Exchange System supports the following types of endpoints:

Provisioned endpoints—Endpoints for which all configuration details (such as name, phone number, number of screens, and organization) are known by the administrator and configured on the Cisco TelePresence Exchange System. Meet-Me and direct dial calls are placed on provisioned endpoints.

Unprovisioned endpoints—Endpoints for which none of the configuration details are known by the administrator except the name of the meeting scheduler for the endpoint. Through the administration console you can reserve bandwidth for unprovisioned endpoints on the service provider network. This allows the endpoint to connect with other known endpoints within the network that are scheduled for the same meeting. This capability is useful for intercompany meetings.

Remote endpoints—Endpoints for which no configuration details are known. Remote endpoints are endpoints that join the meeting from another service provider network. Configuring a remote endpoint on the Cisco TelePresence Exchange System reserves capacity for the endpoint on the service provider network on which it is resident. The Cisco TelePresence Exchange System automatically determines and reserves the capacity to support these interprovider meetings.


Note Organization port management does not manage remote endpoints.


Endpoint Protocols

The Cisco TelePresence Exchange System supports endpoints that use the following protocols:

ISDN—Integrated Services Digital Network.

H.323—ITU Specifications for Voice over IP networks and endpoints.

SIP—Session Initiation Protocol.

TIP—TelePresence Interoperability Protocol.

MUX—A Cisco proprietary protocol, which was a predecessor of TIP.

Endpoint Capacity

Three factors determine how many segments the Cisco TelePresence Exchange System reserves for an endpoint:

The bridge type that handles the call (Cisco TelePresence Multipoint Switch or Cisco TelePresence MSE 8000 Series)

The type of call (dial in or dial out)

The number of endpoint screens

For more details on endpoint capacity calculation, see the Endpoint Capacity appendix of the Installation and Administration Guide for the Cisco TelePresence Exchange System at http://www.cisco.com/en/US/docs/telepresence/tx/exchange_system/1_1/install_admin/book/b_install_admin.html.

Custom Layouts

When you create or modify a meeting, you can optionally enter a value for the screen layout. This value will be used if the meeting is hosted on a Cisco TelePresence MCU MSE 8510, which supports a variety of screen layout options.

For details about the layout values, see the "Conference Layouts" section of the Cisco TelePresence MCU API reference guide at http://www.cisco.com/en/US/products/ps11447/products_programming_reference_guides_list.html.

When the conference is not hosted on a Cisco TelePresence MCU MSE 8510, the customLayout parameter is ignored.

Meeting Types

The Cisco TelePresence Exchange System supports the following types of meetings:

Meet-Me meeting—A scheduled meeting that is hosted by this Cisco TelePresence Exchange System. The Cisco TelePresence Exchange System reserves media resources based on the parameters that you configure for the meeting. Typically, a Meet-Me meeting is associated with a guaranteed reservation type. You can configure a Meet-Me meeting to provide One-Button-to-Push functionality for the provisioned endpoints and to reserve organization bandwidth. You can also designate the host participant role to one or more endpoints to control access to a Meet-Me meeting.

Remote meeting—A scheduled meeting that is hosted by a remote Cisco TelePresence Exchange System. The Cisco TelePresence Exchange System does not reserve any media resources for a remote meeting. You schedule remote meetings to provide OBTP functionality in the provisioned endpoints and to reserve the bandwidth, if requested.

Scheduled two-party direct meeting—A scheduled direct dialed meeting between two hosted provisioned endpoints. The Cisco TelePresence Exchange System does not reserve any media resources for a direct dialed meeting. Two-party direct meetings are scheduled to provide OBTP functionality for those endpoints within the same organization.

Rendezvous meeting—A predefined meeting that can occur at any time (not scheduled for a specific start time). A Rendezvous meeting instance starts when any participant dials into the meeting. Typically, a Rendezvous meeting is scheduled with a best-effort reservation type. With a best-effort reservation type, the Cisco TelePresence Exchange System does not reserve any media resources for a Rendezvous meeting. OBTP is not applicable for Rendezvous meetings. A Rendezvous meeting may optionally assign the host role to one or more endpoints, to control access to the meeting. If a host is assigned, the meeting starts only when the host (or alternate host) dials into the meeting.

Meeting Extensions

You can optionally configure a meeting to extend its duration automatically. The meeting will only be extended if there are any active participants at the time that the system checks for available resources for the extension, which happens shortly before the two minute end-of-meeting warning.

You can allow one or more extensions of the meeting. You can also specify the length of the meeting extension (in minutes). This value must be a multiple of 15 (i.e. extensions are allowed in 15-minute increments).

The maximum number of extensions times the extension length must not exceed 24 hours.

Inherited Values

The MeetingExtension element and the DropParticipantOnHostExit element are examples of enumerated types which allow a value of INHERIT.

If you set the value in the meeting to INHERIT, the meeting inherits the behavior defined by the organization hosting the meeting. In the organization element, INHERIT indicates that the organization will inherit the behavior from the service provider. A value of INHERIT is not valid in the service provider element.

If you set a value other than INHERIT for a meeting, the value in the meeting will override the value set for the organization. Similarly, setting a value other than INHERIT for the organization will override the value set for the service provider.

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/v1_1/sched?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 Scheduling 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 Scheduling API, which you can access by using the following URL:

http://<DNS name or IP address for your admin server>:8080/ctxapi/api/sched?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


Required and Optional Parameters

In the parameter tables throughout this chapter, we identify optional parameters by starting the description field with the following notation: (Optional). All other parameters are required.

API Parameter Naming Conventions

The API uses the following conventions for parameter names.

Key

The Scheduling API assigns a unique string identifier (called a key) to entities in the object model, such as service provider, organization, endpoint and meeting.

You use the key in subsequent API requests to ensure that the service selects the correct item.

Name

In addition to the unique key, the API returns the name string for the entity if the entity was provisioned with a name. The name provides a human-readable identifier for the item (for use in a UI display or a report).

Description

Like the name, the API returns a description string for the entity if the entity was provisioned with a description. The description provides a human-readable description for the item (for use in a UI display or a report).

Obtaining Configured Information

The Scheduling API provides "Get" methods for retrieving configured information about endpoints, regions, organizations, and so on, that are configured on the Cisco TelePresence Exchange System. The methods are described in the following sections:

getEndpointAvailability

getEndpoints

getEndpointsForOrganization

getMediaProfiles

getOrganizations

getOrganizationsForServiceProvider

getPortsByOrganization

getRegions

getRegionsForServiceProvider

getReservationTypes

getServiceNumbers

getServiceProviders

getWhiteListGroups

getEndpointAvailability

The Get Endpoint Availability service returns the availability status for a list of endpoints that meet the criteria that are supplied in the request.

Table 2-1 describes the parameters in the service request.

Table 2-1 Get Endpoint Availability Request 

Parameter
Type
Description

endpointKeys

String

Enter the key for one or more endpoints.

dateTimeStr

Date/Time, ISO 8601

Enter the starting date and time of the duration for which endpoint availability will be reported.

duration

int

Enter the length (in minutes) of the duration for which endpoint availability will be reported.

searchGranularity

int

Enter the granularity (in minutes) of the period for each availability status. For example, a value of 15 means that the endpoint availability will be reported for each 15-minute period in the duration.


The service returns a Get Endpoint Availability Result in the service response. Table 2-2 describes the Get Endpoints Result.

Table 2-2 Get Endpoint Availability Result 

Parameter
Type
Description

endpointAvailability

Complex

List of endpointAvailability elements. See Table 2-3 for a description of endpointAvailability element.


Table 2-3 describes the endpointAvailability element.

Table 2-3 endpointAvailability Element 

Parameter
Type
Description

endpointKey

String

Unique identifier for the endpoint.

freeBusy

enumeration

Availability is an enumeration, which allows the string values of "FREE" or "BUSY".

The endpointAvailability element will include multiple values of freeBusy (one for each period in the duration that was specified in the request). For example, if duration is 60 and searchGranularity is 15, there will be four values of freeBusy (one for each 15-minute period).


 
   

getEndpoints

The Get Endpoints service returns a list of endpoints that meet the criteria that are supplied in the request.

Table 2-4 describes the parameters in the service request.

For additional information about the parameters that control pagination (startingIndex, numberToReturn), see the "Pagination" section.

Table 2-4 Get Endpoints Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of endpoints. For information about building queries, see the "Query Syntax" section.

startingIndex

Integer

(Optional) Specify the index of the first entry to be returned.

numberToReturn

Integer

(Optional) Specify the number of entries to be returned.


The service returns a Get Endpoints Result in the service response. Table 2-5 describes the Get Endpoints Result.

Table 2-5 Get Endpoints Result 

Parameter
Type
Description

endpoints

Complex

List of apiEndpoint elements. See Table 2-6 for a description of apiEndpoint element.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-6 describes the apiEndpoint element.

Table 2-6 apiEndpoint Element 

Parameter
Type
Description

ctsManIpAddress

String

IP address of the CTS Manager associated with this endpoint.

ctsManRoomId

String

Unique room name stored in the CTS Manager associated with this endpoint.

description

String

Text description of the endpoint.

isActive

Boolean

Returns true if the endpoint is active.

key

String

The key is a unique identifier for the endpoint

mediaProfileKey

String

Key value of the media profile that is configured for this endpoint.

name

String

Text name of the endpoint.

number

String

Provides the directory number for the endpoint.

organizationKey

String

Key value of this endpoint's organization

supportOBTP

Boolean

Indicates that the endpoint supports OBTP functionality.


 
   

getEndpointsForOrganization

The Get Endpoints for Organization service returns a list of endpoints that are defined for the specified organization. An endpoint is active if it has been associated with an organization and is configured as available for scheduling (in the administration console Endpoints table).

Table 2-7 describes the parameters for the service request.

For additional information about the parameters that control pagination (startingIndex, numberToReturn), see the "Pagination" section.

Table 2-7 Get Endpoints for Organization Request 

Parameter
Type
Description

serviceProviderKey

String

Enter the key of the service provider that is associated with the organization.

organizationKey

String

Enter the key of the organization.

startingIndex

Integer

(Optional) Specify the index of the first entry to be returned.

numberToReturn

Integer

(Optional) Specify the number of entries to be returned.


The service response contains a Get Endpoints Result. The Get Endpoints Result is described in Table 2-5.

getMediaProfiles

The Get Media Profiles service returns a list of media profiles that meet the criteria that are supplied in the request. Table 2-8 describes the parameters in the service request.

Table 2-8 Get Media Profiles Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of media profiles. For information about building queries, see the "Query Syntax" section.


The service returns a Get Media Profiles Result in the service response.Table 2-9 describes the Get Media Profiles Result.

Table 2-9 Get Media Profiles Result 

Parameter
Type
Description

mediaProfiles

Complex

List of apiMediaProfileResult elements. See Table 2-10 for a description of this element.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-10 describes the apiMediaProfileResult element.

Table 2-10 apiMediaProfileResult Element 

Parameter
Type
Description

description

String

Text description of the media profile.

endpointProtocols

Complex

One or more endpointProtocol elements. The endpointProtocol is an enumeration, with the following string values:

ISDN—Integrated Services Digital Network.

H.323—ITU Specifications for Voice over IP networks and endpoints.

SIP—Session Initiation Protocol

TIP—TelePresence Interoperability Protocol

MUX—A Cisco proprietary protocol, which was a predecessor of TIP.

isBuiltin

Boolean

Set to true if this media profile is one of the media profiles that is pre-defined. The parameter is set to false if the media profile is user-defined.

key

String

The key is a unique string identifier for this media profile

name

String

Text name of the media profile.

numberOfScreens

int

Number of video screens that the endpoint supports. Most endpoints provide either one screen or three screens.

supports30fps

Boolean

Set to true if the endpoints using this media profile provide support for 30 frames-per-second presentation sharing.


 
   

getOrganizations

The Get Organizations service returns a list of all organizations that meet the criteria that are supplied in the request. Table 2-11 describes the parameters for the service request.

For additional information about the parameters that control pagination (startingIndex, numberToReturn), see the "Pagination" section.

Table 2-11 Get Organizations Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of organizations. For information about building queries, see the "Query Syntax" section.

startingIndex

Integer

(Optional) Specify the index of the first entry to be returned.

numberToReturn

Integer

(Optional) Specify the number of entries to be returned.


Table 2-12 describes the parameters for the service response.

Table 2-12 Get Organizations Result 

Parameter
Type
Description

organizations

Complex

List of zero or more apiOrganization elements that meet the query criteria. The apiOrganization type is described in Table 2-13.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-13 describes the apiOrganization type.

Table 2-13 apiOrganization Type 

Parameter
Type
Description

allowInterSPIncomingDirectDialCalls

Boolean

Set to TRUE if inter-service-provider incoming direct dial calls are allowed.

allowInterSPIncomingMeetMeCalls

Boolean

Set to TRUE if inter-service-provider incoming Meet-Me calls are allowed.

allowInterSPOutgoingCalls

Boolean

Set to TRUE if inter-service-provider outgoing calls are allowed.

description

String

Text description of the organization.

dropParticipantsOnHostExit

Enumeration

If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.

If the host role IS enabled, this parameter defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for a meeting will override the value set for the organization.

Enter one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

INHERIT—The setting defined in the service provider determines the drop behavior.

enforceWhitelisting

Boolean

Set to TRUE if the Whitelist is enforced for this organization.

key

String

The key is a unique identifier for the organization.

maxBandwidth

Integer

Maximum bandwidth that can be used by this organization across all calls simultaneously. Unit is number of screens.

maxMeetingExtensionsAllowed

Integer

Maximum number of meeting extensions allowed for any given meeting. The maximum number of extensions times the extension period must not exceed 24 hours.

meetingExtension

Enumeration

Determines whether meetings in this organization can be extended.

Note The MeetingExtension value of a meeting will override the value set for an organization.

Enter one of the string values:

DISABLE—The system will not extend meetings in this organization.

ENABLE—The system will extend meetings in this organization if resources are available near the end of the meeting.

INHERIT—The setting defined in the service provider determines the extension behavior.

meetingExtensionPeriod

Integer

Length of time (in minutes) of a meeting extension period. This value must be a multiple of 15.

minimizeCapacity

Boolean

If set to TRUE, the system reserves fewer ports of bridge capacity for the single-screen systems that are invited to Meet-me meetings. Instead of assuming the worst-case capacity for invited endpoints, the system reserves the actual capacity associated with the endpoint.

This feature allows an increase in the number of meetings that can be scheduled using the bridge resources. However, each meeting will have fewer reserve ports to accommodate additional participants (or unregistered participants with multi-screen systems).

name

String

Text name of the organization,

serviceProviderKey

String

The key value of the service provider that is associated with this organization.


getOrganizationsForServiceProvider

The Get Organizations for Service Provider service returns a list of organizations that are configured for the specified service provider. Table 2-14 describes the parameters for the service request.

For additional information about the parameters that control pagination (startingIndex, numberToReturn), see the "Pagination" section.

Table 2-14 Get Organizations for Service Provider Request 

Parameter
Type
Description

serviceProviderKey

String

Enter the unique key of the service provider.

startingIndex

Integer

(Optional) Specify the index of the first entry to be returned.

numberToReturn

Integer

(Optional) Specify the number of entries to be returned.


The service response contains the Get Organizations Result element, which is described in Table 2-12.

getPortsByOrganization

The Get Ports by Organization service returns the port bandwidth allocation for each organization (or for the specified organization). The information covers each 15-minute interval for the start time and duration that are specified in the request.

Table 2-15 describes the parameters for the service request.

Table 2-15 Get Ports by Organization Request 

Parameter
Type
Description

organizationKey

String

Enter the unique key of the organization. Enter a null string to get information for all organizations.

dateTimeStr

Date/time string

Enter the starting date and time for the port allocation. The default value is the date and time that the server receives the request.

duration

Integer

Enter the duration for the port allocation. The service response will include a value for each 15-minute interval in the duration that is specified. The first interval starts at the starting time and date.


Table 2-16 describes the Get Ports by Organization response.

Table 2-16 Get Ports by Organization Response 

Parameter
Type
Description

APIPortsList

Complex

List of apiPorts elements. The apiPorts elements are described in Table 2-17. For each organization (or the specified organization), the service returns one apiPorts element for each 15-minute interval in the requested duration.


Table 2-17 describes the apiPorts element.

Table 2-17 apiPorts Element

Parameter
Type
Description

date

Date/time string

Start date and time.

lane

String

Values are limited to CTS, ISDN, or IP.

organization

String

Name of the organization.

value

int

Bandwidth value.


getRegions

The Get Regions service returns a list of regions that meet the query criteria that are supplied in the request. Table 2-18 describes the parameters for the service request.

Table 2-18 Get Regions Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of regions. For information about building queries, see the "Query Syntax" section.


Table 2-19 describes the Get Regions service response.

Table 2-19 Get Regions Result

Parameter
Type
Description

regions

Complex

List of zero or more apiRegion elements. The apiRegion element is described in Table 2-20.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-20 describes the apiRegion element.

Table 2-20 apiRegionElement 

Parameter
Type
Description

description

String

Text description of the region

key

String

The key is a unique identifier for the region

name

String

Text name of the region.


getRegionsForServiceProvider

The Get Regions for Service Provider service returns a list of regions that are configured for the specified service provider. Table 2-21 describes the parameters for the service request.

Table 2-21 Get Regions for Service Provider Request 

Parameter
Type
Description

serviceProviderKey

String

Enter the key of the service provider that is associated with the region.


The service response contains a Get Regions Result, which is described in Table 2-19.

getReservationTypes

The Get Reservation Types service returns the reservation types that meet the criteria that are supplied in the request.

Table 2-22 describes the parameters in the service request.

Table 2-22 Get Reservation Types Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of reservation types. For information about building queries, see the "Query Syntax" section.


The service returns a Get Reservation Types Result in the service response. Table 2-23 describes the result.

Table 2-23 Get Reservation Types Result 

Parameter
Type
Description

reservationTypes

Complex

List of apiReservationType. See Table 2-24 for a description of this element.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-24 describes the apiReservationType element.

Table 2-24 apiReservationType Element 

Parameter
Type
Description

description

String

Text description of the reservation type.

isGuaranteed

Boolean

Set to true if the reservation is guaranteed, which means that the system has reserved bridge resources for the meeting. If the reservation is not guaranteed, the system attempts to allocate resources at the start of the meeting. This attempt may fail if the system is heavily loaded.

key

String

The key is a unique identifier for the reservation type.

name

String

Text name of the reservation type.


 
   

getServiceNumbers

The Get Service Numbers service returns the service numbers that meet the criteria that are supplied in the request. Typically, a different service number is defined for each IVR language that a service supports.

Table 2-25 describes the parameters in the service request.

Table 2-25 Get Service Numbers Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of service numbers. For information about building queries, see the "Query Syntax" section.


The service returns a Get Service Numbers Result in the service response. Table 2-26 describes the result.

Table 2-26 Get Service Numbers Result 

Parameter
Type
Description

serviceNumbers

Complex

List of apiServiceNumber elements. See Table 2-6 for a description of this element.

totalNumberFound

int

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-27 describes the apiServiceNumber element.

Table 2-27 apiServiceNumber Element 

Parameter
Type
Description

description

String

Text description of the service number.

ivrConfigName

String

Text name of the IVR resource that provides the voice prompts for this service number.

key

String

The key is a unique identifier for the service number.

name

String

Text name for the service number.

number

String

Digit string that the user dials for this service number.

serviceName

String

Text name of the service associated with this service number.

serviceProviderKey

String

The key value of the service provider that is associated with this service number.


 
   

getServiceProviders

The Get Service Provider service returns a list of service providers that meet the criteria that are supplied in the request. Table 2-28 describes the parameters for the service request.

Table 2-28 Get Service Providers Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of service providers. For information about building queries, see the "Query Syntax" section.


Table 2-29 describes the service response.

Table 2-29 Get Service Providers Response 

Parameter
Type
Description

serviceProviders

Complex

List of apiServiceProvider elements. The apiServiceProvider type is described in Table 2-30. Each apiServiceProvider provides the unique key and name of a service provider.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-30 describes the apiServiceProvider element.

Table 2-30 apiServiceProvider Element

Parameter
Type
Description

description

String

Text description of the service provider.

dropParticipantsOnHostExit

Enumeration

If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.

If the host role IS enabled, this parameter defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for the organization or for a meeting will override the value set for the service provider.

Enter one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

helpDeskNumber

String

Service desk phone number for the service provider.

key

String

The key is a unique identifier for the service provider.

maxIvrQueueTime

Integer

The maximum amount of time, in minutes, that callers will remain in the IVR waiting for a host-enabled meeting to start.

maxMeetingExtensionsAllowed

Integer

Maximum number of meeting extensions allowed for any given meeting. The maximum number of extensions times the extension period must not exceed 24 hours.

meetingExtension

Enumeration

Determines whether meetings in this service provider can be extended.

Note A value of ENABLE or DISABLE in the organization element or a meeting element will override the value set for the service provider.

String values:

DISABLE—meeting extensions not allowed.

ENABLE—meeting extensions allowed.

meetingExtensionPeriod

Integer

Length of time (in minutes) of a meeting extension period. This value must be a multiple of 15.

name

String

Text name of the service provider.


getWhiteListGroups

The Get WhiteList Groups service returns a list of all whitelist groups that meet the criteria that are supplied in the request. Table 2-31 describes the parameters for the service request.

Table 2-31 Get WhiteList Groups Request 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of whitelist groups. For information about building queries, see the "Query Syntax" section.


Table 2-32 describes the parameters for the service response.

Table 2-32 Get WhiteList Groups Result 

Parameter
Type
Description

whiteListGroups

Complex

List of zero or more apiWhiteListGroup elements that meet the query criteria. The apiWhiteListGroup type is described in Table 2-33.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


Table 2-33 describes the apiWhiteListGroup type.

Table 2-33 apiWhiteList Group Type 

Parameter
Type
Description

description

String

Text description of the whitelist group.

name

String

Text name of the whitelist group,

organizationKeyList

Complex

Keys for one or more organizations that belong to this whitelist group.

serviceProviderKey

String

The key value of the service provider that is associated with the organizations in this whitelist group.


Scheduling and Managing Meetings

The following sections describe the services for scheduling and managing meetings:

scheduleMeeting

scheduleRendezvousMeeting

scheduleRemoteMeeting

scheduleTwoPartyDirectMeeting

modifyMeeting

modifyRendezvousMeeting

modifyRemoteMeeting

modifyTwoPartyDirectMeeting

cancelMeeting

getMeetings

getMeeting

checkPorts

isEndpointFree

Endpoint Elements

scheduleMeeting

The Schedule Meeting service creates a new Meet-Me meeting, based on the parameter values that are supplied in the request. The response includes a meeting key, which must be supplied in all subsequent requests to view, modify or delete the meeting.

Table 2-34 describes the parameters for the service request.

Table 2-34 Schedule Meeting Request 

Parameter
Type
Description

conferenceID

String

(Optional) If you provide a null string for this field, the system generates a unique conference ID for the meeting. If you provide a conference ID in this parameter, the system will use this value.

Note The service request will fail if you provide a conference ID that is not unique.

auditID

String

(Optional) You can set this identifier to tag meetings, for example, with categories. The auditID field is saved but not processed by the API.

schedulerEmail

String

Enter the email address of the contact person for the meeting. The email address is displayed on the IP phone in the meeting room.

schedulerOrganizationKey

String

(Optional) Enter the key value for the meeting scheduler's organization.

Note This field is NOT optional if any field is set to INHERIT its value from the organization. Also, any configured whitelist policies will not be applied when attendees join the meeting if you do not specify the scheduler's organization.

subject

String

Enter the subject of the meeting.

dateTimeStr

Date/time string

Enter the date and time for the start of the meeting.

duration

Integer

Enter the duration of the meeting in minutes.

serviceProviderKey

String

Enter the unique key of the service provider that will host the meeting.

regionKey

String

Enter the key of the region for the meeting. The region contains the resources that will be used for this meeting.

requireOBTP

Boolean

(Optional) Set to TRUE when you want to display One-Button-to-Push (OBTP) information on the IP phone that is associated with the provisioned endpoint. Set to FALSE when you do not want to use OBTP for privacy reasons or when the Cisco TelePresence Manager is temporarily unavailable. When no value is set, a default of TRUE is set.

provisionedEndpointList

Complex

(Optional) Enter a list of apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section.

unprovisionedEndpointList

Complex

(Optional) Enter a list of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section.

remoteEndpointList

Complex

(Optional) Enter a list of apiRemoteEndpoint elements. See the "Remote Endpoint Fields" section.

additionalCapacity

Integer

Enter the additional capacity to reserve for unprovisioned and remote endpoints in the meeting. Units are segments.

additionalMediaProfiles

Complex

(Optional) Enter one or more media profile keys, which define the additional endpoint types that this meeting needs to support.

customLayout

Integer

(Optional) Enter a default value for the screen layout.

This value will be used if the meeting is hosted on a Cisco TelePresence MCU MSE 8510, which supports a variety of screen layout options.

For details on the layout values, see the "Custom Layouts" section

isHostRoleEnabled

Boolean

Set to true to define a host for this meeting.

hostPin

String

(Optional) Enter a numerical host PIN for the meeting. By default, the system will create a random PIN.

Note Only set a host PIN if the host role is enabled.

serviceNumberKey

String

Enter the key value of the service number that users will dial to join this meeting. Typically, a different service number is defined for each supported language.

reservationTypeKey

String

Enter the key value of the reservation type for this meeting.

meetingExtensionEnabledType

Enumeration

Determines whether this meeting can be extended.

Note A value of ENABLE or DISABLE in the meeting element will override the value set for the organization or service provider.

String values:

DISABLE—meeting extensions not allowed.

ENABLE—meeting extensions allowed.

INHERIT—The setting defined in the organization determines the behavior.

meetingExtensionPeriod

Integer

Enter the length of time (in minutes) of a meeting extension period. This value must be a multiple of 15.

maxMeetingExtensionsAllowed

Integer

Enter the maximum number of meeting extensions allowed for any given meeting. The maximum number of extensions times the extension period must not exceed 24 hours.

dropParticipantsOnHostExit

Enumeration

Defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for a meeting will override the value set for the organization.

Enter one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

INHERIT—The setting defined in the organization determines the drop behavior.

Note If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.


The service responds with a scheduleMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

 
   

scheduleRendezvousMeeting

The Schedule Rendezvous Meeting service creates a new Rendezvous meeting, based on the parameter values that are supplied in the request. A Rendezvous meeting instance starts whenever participants join the meeting, and ends when all participants leave or when the meeting reaches the maximum instance duration. Thus, there can be an unlimited number of instances of the same Rendezvous meeting.

The response includes a meeting key, which must be supplied in any subsequent request to view, modify or delete the meeting.

Table 2-35 describes the parameters for the service request.

Table 2-35 Schedule Rendezvous Meeting Request 

Parameter
Type
Description

conferenceID

String

(Optional) If you provide a null string for this field, the system generates a unique conference ID for the meeting. If you provide a conference ID in this parameter, the system will use this value.

Note If you provide conference IDs, you must provide a unique conference ID for each meeting.

auditID

String

(Optional) You can set this identifier to tag meetings, for example, with categories. The auditID field is saved but not processed by the API.

schedulerEmail

String

Enter the email address of the contact person for the meeting. The email address is displayed on the IP phone in the meeting room.

schedulerOrganizationKey

String

(Optional) Enter the key of the scheduler's organization.

Note This field is NOT optional if any field is set to INHERIT its value from the organization. Also, any configured whitelist policies will not be applied when attendees join the meeting if you do not specify the scheduler's organization.

subject

String

Enter the subject of the meeting.

serviceProviderKey

String

Enter the key of the service provider that will host the meeting.

regionKey

String

Enter the key of the region for the meeting. The region contains the resources that will be used for this meeting.

maximumNumberOfEndpoints

Integer

Enter the maximum number of endpoints that can join the meeting.

Note At attend time, the system does not limit the actual number of endpoints that can join the meeting to this value. As long as the reserved capacity is available, more endpoints can join if the endpoints have fewer screens than the "worst-case" scenario accounted for in the capacity calculation. For more information on the calculation, see the "Organization Bandwidth, Endpoint Capacity, Protocols and Bridge Selection" appendix in the Installation and Administration Guide for the Cisco TelePresence Exchange System Release 1.1, at http://www.cisco.com/en/US/docs/telepresence/tx/exchange_system/1_1/install_admin/book/b_install_admin.html.

additionalCapacity

Integer

Enter the additional capacity to reserve for unprovisioned and remote endpoints in the meeting. Units are segments.

additionalMediaProfiles

Complex

(Optional) Enter one or more media profile keys, which define the additional endpoint types that this meeting needs to support.

customLayout

Integer

(Optional) Enter a default value for the screen layout.

This value will be used if the meeting is hosted on a Cisco TelePresence MCU MSE 8510, which supports a variety of screen layout options.

For details on the layout values, see the "Custom Layouts" section.

maxInstanceDuration

Integer

Maximum duration (in minutes) of a Rendezvous meeting.

isHostRoleEnabled

Boolean

Set to true to define a host for this meeting.

hostPin

String

(Optional) Enter a numerical host PIN for the meeting. By default, the system will create a random PIN.

Note Only set a host PIN if the host role is enabled.

serviceNumberKey

String

Enter the key of the service number for this meeting. Typically, a different service number is defined for each supported language.

reservationTypeKey

String

Enter the key of the reservation type for this meeting.

allowedHostEndpoints

Complex

(Optional) If you have enabled the host role, provide a list of one or more endpointKey elements (for the host endpoint and any alternate hosts).

dropParticipantsOnHostExit

Enumeration

If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.

If the host role IS enabled, this parameter defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for a meeting will override the value set for the organization.

Enter one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

INHERIT—The setting defined in the organization determines the drop behavior.


The service responds with a scheduleMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

 
   

scheduleRemoteMeeting

The Schedule Remote Meeting service creates a new remote Meet-Me meeting based on the parameter values that are supplied in the request. The response includes a meeting key, which must be supplied in any subsequent request to view, modify or delete the meeting.

A remote meeting implies that another Cisco TelePresence Exchange System will schedule and manage the media resources for the meeting. No media resources are reserved on this Cisco TelePresence Exchange System for a remote meeting. You schedule remote meetings for the system to provide One-Button-to-Push (OBTP) functionality for the local provisioned endpoints and to reserve bandwidth for the meeting. This is required for organizations that are using the bandwidth port management feature.

Table 2-36 describes the parameters for the Schedule Remote Meeting service request.

Table 2-36 Schedule Remote Meeting Request 

Parameter
Type
Description

accessNumber

Digit string

Enter the number that the participants dial to access the remote system's IVR. This is also known as the Service Number.

conferenceID

String

Enter the conference ID for the participants to input when they join the meeting.

schedulerEmail

String

Enter the email address of the contact person for the meeting. The email address is displayed on the IP phone in the meeting room.

subject

String

Enter the subject of the meeting.

dateTimeStr

Date/time string

Enter the date and time for the start of the meeting.

duration

Integer

Enter the duration of the meeting in minutes.

serviceProviderKey

String

Enter the unique key of the service provider that hosts the meeting.

requireOBTP

Boolean

(Optional) Set to TRUE when you want to display One-Button-to-Push (OBTP) information on the IP phone that is associated with the provisioned endpoint. Set to FALSE when you do not want to use OBTP for privacy reasons or when the Cisco TelePresence Manager is temporarily unavailable. When no value is set, a default of TRUE is set.

provisionedEndpointList

Complex

Enter a list of apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section.

Note For this request, there must be at least one endpoint in either the provisioned or unprovisioned list.

unprovisionedEndpointList

Complex

Enter a list of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section.

Note For this request, there must be at least one endpoint in either the provisioned or unprovisioned list.


The service responds with a scheduleMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

scheduleTwoPartyDirectMeeting

The Schedule Two Party Direct Meeting service creates a new direct meeting between two One-Button-to-Push (OBTP)-enabled provisioned endpoints within organizations under the same service provider and associated with the same Cisco TelePresence Manager, by using the parameter values that are supplied in the request. The response includes a meeting key, which must be supplied in any subsequent request to view, modify or delete the meeting.

The Cisco TelePresence Exchange System does not reserve any media resources or ports of organization bandwidth for a two party meeting. Two party meetings are scheduled to provide OBTP functionality for the endpoints.

Table 2-37 describes the parameters for the service request.

Table 2-37 Schedule Two Party Meeting Request 

Parameter
Type
Description

schedulerEmail

String

Enter the email address of the contact person for the meeting. The email address is displayed on the IP phone in the meeting room.

subject

String

Enter the subject of the meeting.

dateTimeStr

Date/time string

Enter the date and time for the start of the meeting.

duration

Integer

Enter the duration of the meeting in minutes.

serviceProviderKey

String

Enter the unique key of the service provider that hosts the meeting.

requireOBTP

Boolean

(Optional) Set to TRUE when you want to display One-Button-to-Push (OBTP) information on the IP phone that is associated with the provisioned endpoint. Set to FALSE when you do not want to use OBTP for privacy reasons or when the Cisco TelePresence Manager is temporarily unavailable. When no value is set, a default of TRUE is set.

provisionedEndpoint1

Complex

Enter an apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section.

Note The two endpoints must belong to organizations under the same service provider, and must be associated with the same Cisco TelePresence Manager resource.

provisionedEndpoint2

Complex

Enter an apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section.


The service responds with a scheduleMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

modifyMeeting

The Modify Meeting service modifies the information for a meeting based on the parameter values that are supplied in the request.

Meeting details cannot be modified after a meeting starts.


Note The Modify Meeting service request must include the meeting key of the meeting that you want to modify.


Table 2-38 describes the parameters for the service request.Except where otherwise specifically noted in the table, null parameter values are set for fields that you do not want to change.


Note When modifying a meeting, the endpoint and media profile lists must be specified completely, even if there are no changes. A null value cannot be used to indicate that there are no changes to the endpoint or media profile lists.


Table 2-38 Modify Meeting Request 

Parameter
Type
Description

meetingKey

String

Enter the meeting key, which is the unique identifier of a specific meeting.

schedulerOrganizationKey

String

(Optional) Enter the key value for the meeting scheduler's organization.

Note This field is NOT optional if any field is set to INHERIT its value from the organization. Also, any configured whitelist policies will not be applied when attendees join the meeting if you do not specify the scheduler's organization.

Note If you specify a null value for the schedulerOrganizationKey, the scheduler's organization will be removed from the meeting. (This can only be done in situations where the field is not required.)

subject

String

(Optional) Enter the subject of the meeting.

dateTimeStr

Date/time string

(Optional) Enter the date and time for the start of the meeting.

duration

Integer

(Optional) Enter the duration of the meeting in minutes.

regionKey

String

(Optional) Enter the key of the region for the meeting. The region contains the resources that will be used for this meeting.

requireOBTP

Boolean

(Optional) Set to TRUE when you want to display One-Button-to-Push (OBTP) information on the IP phone that is associated with the provisioned endpoint. Set to FALSE when you do not want to use OBTP for privacy reasons or when the Cisco TelePresence Manager is temporarily unavailable. When no value is set, a default of TRUE is set.

provisionedEndpointList

Complex

Enter a list of apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section.

Note The list must include all of the provisioned endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

unprovisionedEndpointList

Complex

Enter a list of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section.

Note The list must include all of the unprovisioned endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

remoteEndpointList

Complex

Enter a list of apiRemoteEndpoint elements. See the "Remote Endpoint Fields" section.

Note The list must include all of the remote endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

additionalCapacity

Integer

(Optional) Enter the additional capacity to reserve for unprovisioned and remote endpoints in the meeting. Units are segments.

additionalMediaProfiles

Complex

Enter one or more media profile keys, which define the additional endpoint types that this meeting needs to support.

Note The list must include all of the media profiles for the meeting (not just the added and changed media profiles). Any of the original media profiles that are not included in the list will be removed from the meeting.

customLayout

Integer

(Optional) Enter a default value for the screen layout.

This value will be used if the meeting is hosted on a Cisco TelePresence MCU MSE 8510, which supports a variety of screen layout options.

For details on the layout values, see the "Custom Layouts" section.

isHostRoleEnabled

Boolean

(Optional) Set this element to TRUE to define a host for this meeting.

hostPin

String

(Optional) Enter a numerical host PIN for the meeting. By default, the system will create a random PIN.

Note Only set a host PIN if the host role is enabled.

serviceNumberKey

String

(Optional) Enter a service number key value for this meeting. Typically, a different service number is defined for each supported language.

reservationTypeKey

String

(Optional) Enter a reservation type key value for this meeting.

meetingExtensionEnabledType

Enumeration

(Optional) Determines whether this meeting can be extended.

Note A value of ENABLE or DISABLE in the meeting element will override the value set for the organization or service provider.

String values:

DISABLE—meeting extensions not allowed.

ENABLE—meeting extensions allowed.

INHERIT—The setting defined in the organization determines the behavior.

meetingExtensionPeriod

Integer

(Optional) Enter the length of time (in minutes) of a meeting extension period. This value must be a multiple of 15.

maxMeetingExtensionsAllowed

Integer

(Optional) Enter the maximum number of meeting extensions allowed for any given meeting. The maximum number of extensions times the extension period must not exceed 24 hours.

dropParticipantsOnHostExit

Enumeration

(Optional) If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.

If the host role IS enabled, this parameter defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for a meeting will override the value set for the organization.

Enter one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

INHERIT—The setting defined in the organization determines the drop behavior.


The service responds with a modifyMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

modifyRendezvousMeeting

The Modify Rendezvous Meeting service updates a meeting, based on the parameter values that are supplied in the request.

Rendezvous meeting details cannot be modified while there are active participants in the meeting.


Note The Modify Rendezvous Meeting service request must include the meeting key of the meeting that you want to modify.


Table 2-39 describes the parameters for the service request. Except where otherwise specifically noted in the table, null parameter values are set for fields that you do not want to change.


Note When modifying a Rendezvous meeting, the allowed host endpoint list and media profile list must be specified completely if either is already defined for the meeting, even if there are no changes. A null value cannot be used to indicate that there are no changes to the allowed host endpoint or media profile lists.


Table 2-39 Modify Rendezvous Meeting Request 

Parameter
Type
Description

meetingKey

String

Enter the meeting key, which is the unique identifier of a specific meeting.

schedulerOrganizationKey

String

(Optional) Enter the key value for the meeting scheduler's organization.

Note This field is NOT optional if any field is set to INHERIT its value from the organization. Also, any configured whitelist policies will not be applied when attendees join the meeting if you do not specify the scheduler's organization.

Note If you specify a null value for the schedulerOrganizationKey, the scheduler's organization will be removed from the meeting. (This can only be done in situations where the field is not required.)

subject

String

(Optional) Enter the subject of the meeting.

regionKey

String

(Optional) Enter the key of the region for the meeting. The region contains the resources that will be used for this meeting.

maximumNumberOfEndpoints

Integer

(Optional) Maximum number of endpoints that can join the Rendezvous meeting.

additionalCapacity

Integer

(Optional) Enter the additional capacity to reserve for unprovisioned and remote endpoints in the meeting. Units are segments.

additionalMediaProfiles

Complex

Enter one or more media profile keys, which define the additional endpoint types that this meeting needs to support.

Note The list must include all of the media profiles for the meeting (not just the added and changed media profiles). Any of the original media profiles that are not included in the list will be removed from the meeting.

customLayout

Integer

(Optional) Enter a default value for the screen layout.

This value will be used if the meeting is hosted on a Cisco TelePresence MCU MSE 8510, which supports a variety of screen layout options.

Note For details on the layout values, see the "Custom Layouts" section.

maxInstanceDuration

Integer

(Optional) Enter the maximum meeting duration (in minutes).

isHostRoleEnabled

Boolean

(Optional) Set to true to define a host for this meeting.

hostPin

String

(Optional) Enter a numerical host PIN for the meeting. By default, the system will create a random PIN.

Note Only set a host PIN if the host role is enabled.

serviceNumberKey

String

(Optional) Enter the key of the service number for this meeting. Typically, a different service number is defined for each supported language.

reservationTypeKey

String

(Optional) Enter the key of the reservation type for this meeting.

allowedHostEndpoints

Complex

If you have enabled the host role, you may provide a list of one or more endpointKey elements (for the host endpoint and any alternate hosts).

Note The allowedHostEndpoints list must be specified completely, even if there are no changes. If you specify a null value for allowedHostEndpoints, the host endpoint and any alternate hosts will be cleared.

dropParticipantsOnHostExit

Enumeration

(Optional) Defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for a meeting will override the value set for the organization.

Enter one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

INHERIT—The setting defined in the organization determines the drop behavior.

Note If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.


The service responds with a modifyMeetingResult, which contains an apiMeeting element. Table 2-46 describes the apiMeeting element.

 
   

modifyRemoteMeeting

The Modify Remote Meeting service modifies the information for a remote meeting based on the parameter values that are supplied in the request.


Note The Modify Remote Meeting service request must include the meeting key of the meeting to be modified.


Table 2-40 describes the parameters for the Modify Remote Meeting request. Except where otherwise specifically noted in the table, null parameter values are set for fields that you do not want to change.


Note When modifying a remote meeting, the endpoint lists must be specified completely, even if there are no changes. A null value cannot be used to indicate that there are no changes to the endpoint lists.


Table 2-40 Modify Remote Meeting Request 

Parameter
Type
Description

meetingKey

String

Enter the meeting key, which is the unique identifier of a specific meeting.

accessNumber

String

(Optional) Enter the number that the participants dial to access the remote system's IVR. This is also known as the Service Number.

conferenceID

String

(Optional) Enter the conference ID for the participants to input when they join the meeting.

subject

String

(Optional) Enter the subject of the meeting.

dateTimeStr

Date/time string

(Optional) Enter the date and time for the start of the meeting.

duration

Integer

(Optional) Enter the duration of the meeting in minutes.

requireOBTP

Boolean

(Optional) Set to TRUE when you want to display One-Button-to-Push (OBTP) information on the IP phone that is associated with the provisioned endpoint. Set to FALSE when you do not want to use OBTP for privacy reasons or when the Cisco TelePresence Manager is temporarily unavailable. When no value is set, a default of TRUE is set.

provisionedEndpointList

Complex

Enter a list of apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section.

Note The list must include all of the provisioned endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.

unprovisionedEndpointList

Complex

Enter a list of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section.

Note The list must include all of the unprovisioned endpoints for the meeting (not just the added and changed endpoints). Any of the original endpoints that are not included in the list will be removed from the meeting.


The service responds with a modifyMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

modifyTwoPartyDirectMeeting

The Modify Two Party Direct Meeting service modifies the information for a two-party meeting based on the parameter values that are supplied in the request.


Note The Modify Two Party Direct Meeting service request must include the meeting key of the meeting that you want to modify.


Table 2-41 describes the parameters for the Modify Two Party Direct Meeting request. Except where otherwise specifically noted in the table, null parameter values are set for fields that you do not want to change.


Note When modifying a two-party direct meeting, either both of the endpoints need to be specified or both of the endpoints need to be set to null to indicate no changes.


Table 2-41 Modify Two Party Meeting Request 

Parameter
Type
Description

meetingKey

String

Enter the meeting key, which is the unique identifier of a specific meeting.

subject

String

(Optional) Enter the new subject of the meeting.

dateTimeStr

Date/time string

(Optional) Enter the new date and time for the start of the meeting.

duration

Integer

(Optional) Enter the new duration of the meeting in minutes.

requireOBTP

Boolean

(Optional) Set to TRUE if you want to display One-Button-to-Push (OBTP) information on the IP phone that is associated with the provisioned endpoints. Set to FALSE when you do not want to use OBTP for privacy reasons or when the Cisco TelePresence Manager is temporarily unavailable. When no value is set, a default of TRUE is set.

provisionedEndpoint1

Complex

Enter an apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section.

Note To indicate no change, set both this parameter and provisionedEndpoint2 to null.

provisionedEndpoint2

Complex

Enter a apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section.

Note To indicate no change, set both this parameter and provisionedEndpoint1 to null.


The service responds with a modifyMeetingResult, which contains an apiMeeting element. The apiMeeting element is described in Table 2-46.

cancelMeeting

This service cancels a scheduled meeting. The service request must include the meeting key of the meeting that you want to cancel.

Table 2-42 describes the fields in the Cancel Meeting request.

Table 2-42 Cancel Meeting Request Parameters 

Parameter
Type
Description

meetingKey

Integer

Enter the meeting key, which is the unique identifier of a specific meeting.

cancelOBTP

Boolean

(Optional) Set to true if you want to remove the One-Button-to-Push (OBTP) entry from the IP phones in the rooms.


The Cancel Meeting service request has no response.

getMeetings

The service returns the details for the meetings that are specified by the parameters supplied in the request.

Table 2-43 describes the fields in the Get Meetings request. For additional information about the parameters that control pagination (startingIndex, numberToReturn), see the "Pagination" section.

Table 2-43 Get Meetings Request Parameters 

Parameter
Type
Description

queryString

String

(Optional) Enter a query to select the desired set of meetings. For information about building queries, see the "Query Syntax" section.

startingIndex

Integer

(Optional) Specify the index of the first entry to be returned.

numberToReturn

Integer

(Optional) Specify the number of entries to be returned.


The service returns a Get Meetings Result in the service response.Table 2-44 describes the Get Meetings Result.

Table 2-44 Get Meetings Result

Parameter
Type
Description

meetings

Complex

List of apiMeeting elements. Table 2-46 describes the apiMeeting element.

totalNumberFound

Integer

The total number of records that are returned in the response message. The value is zero if the query did not match any results.


getMeeting

The service returns the details for the meeting that are specified by the meeting key that is supplied in the request.

Table 2-45 describes the fields in the Get Meeting request.

Table 2-45 Get Meeting Request Parameters 

Parameter
Type
Description

meetingKey

Integer

Enter the meeting key, which is the unique identifier of a specific meeting.


The Get Meeting Response returns a list of apiMeeting elements. Table 2-46 describes the apiMeeting element.

Table 2-46 apiMeeting Element 

Parameter
Type
Description

accessNumber

String

The number that the participants dial to join the meeting (also known as the service number).

additionalMediaProfileList

Complex

List of apiMediaProfileResult elements. See Table 2-10 for a description of this element

bridgeResourceType

Enumeration

CTMS, TPS, TPS_8510

conferenceId

String

The conference ID for the participants to input when they join the meeting.

dateTimeStr

Date/time string

The date and time for the start of the meeting.

didOBTP

Boolean

This element is set to TRUE if OBTP capability was provided for this meeting.

dropParticipantsOnHostExitType

Enumeration

If the host role is not enabled, participants will remain on the call regardless of who drops from the call before them.

If the host role IS enabled, this parameter defines the default action for participants when the host exits a meeting.

Note Setting DROP or DO NOT DROP for a meeting will override the value set for the organization.

This will be one of the string values:

DO NOT DROP—Participants remain in the meeting.

DROP—Participants are dropped and the meeting ends.

INHERIT—The setting defined in the organization determines the drop behavior.

duration

Integer

The duration of the meeting in minutes.

hostPin

String

The 6-digit string that the host enters via the phone keypad to start the meeting when the host role is enabled.

isCancelled

Boolean

This element is set to TRUE if the meeting is cancelled.

isHostRoleEnabled

Boolean

This element is set to TRUE if the host role is enabled for this meeting.

isRemote

Boolean

This element is set to TRUE if the meeting is remote.

isRendezvous

Boolean

This element is set to TRUE if the meeting is a Rendezvous meeting.

isTwoPartyDirect

Boolean

This element is set to TRUE if the meeting is a two party direct meeting.

lastModified

Date/time string

Date and time that the meeting record was last modified.

maxInstanceDuration

Integer

Maximum call duration (in minutes) if this is a Rendezvous meeting.

maxMeetingExtensionsAllowed

Integer

Maximum number of meeting extensions allowed for any given meeting. The maximum number of extensions times the extension period must not exceed 24 hours.

meetingExtensionEnabledType

Enumeration

Determines whether this meeting can be extended.

Note The MeetingExtension value of a meeting will override the value set for an organization.

String values:

DISABLE—meeting extensions not allowed.

ENABLE—meeting extensions allowed.

INHERIT—meeting extensions allowed if the organization allows extensions.

meetingExtensionPeriod

Integer

Length of time (in minutes) of a meeting extension period. This value must be a multiple of 15.

meetingKey

Integer

The meeting key is a unique identifier of a specific meeting.

numberOfRendezvousEndpoints

Integer

Maximum number of endpoints allowed in a meeting, if this is a Rendezvous meeting.

provisionedEndpointList

Complex

List of apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section.

remoteEndpointList

Complex

List of apiRemoteEndpoint elements. See the "Remote Endpoint Fields" section.

requiredCapacity

Integer

Amount of bridge capacity required

reservationTypeKey

String

Key value of the reservation type for this meeting.

scheduler

String

Email address of the meeting scheduler.

schedulerOrgKey

String

Key value of the scheduler's organization.

subject

String

Subject of the meeting.

unprovisionedEnd
pointList

Complex

List of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section.

useBestEffortAllocation

Boolean

If set to TRUE, no bridge resources are reserved for this meeting.

If set to FALSE, the system uses guaranteed allocation (bridge resources are reserved for the meeting).


checkPorts

The Check Ports service queries availability of sufficient organization port bandwidth for the specified meeting or period of time. Table 2-47 describes the fields in the Check Port request.

Table 2-47 Check Port Request 

Parameter
Type
Description

meetingKey

Integer

(Optional) Enter the meeting key, which is the unique identifier of a specific meeting.

If the meeting key is present, the bandwidth is calculated for the existing meeting plus the specified endpoints. For example, enter the meeting key to check for bandwidth availability when adding endpoints to an existing meeting.

If the meeting key is not present, the bandwidth is calculated based on the start time, service provider, duration, and endpoints. For example, you may check to see if bandwidth is available for a particular time slot when creating a new meeting, before the meeting key is available.

dateTimeStr

Date/time string

Enter the date and time of the start of the meeting.

duration

Integer

Enter the duration of the meeting in minutes.

serviceProviderKey

String

Enter the unique key for the service provider.

provisionedEndpointList

Complex

Enter a list of the apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section.


Table 2-48 describes the Check Ports response.

Table 2-48 Check Ports Response 

Parameter
Type
Description

free

Boolean

The boolean is set to true when organization port bandwidth is available for the entire duration that is specified in the request.


isEndpointFree

The Is Endpoint Free service queries the availability of the specified endpoint during the duration between the specified start time and end time. This service is analogous to a simplified version of getEndpointAvailability, where you specify only one endpoint and receive only one status response (for the entire period specified in the request).

Table 2-49 describes the fields in the Is Endpoint Free request.

Table 2-49 Is Endpoint Free Request Parameters 

Parameter
Type
Description

dateTimeStartStr

String

Start date and time for checking the endpoint availability.

dateTimeEndStr

String

End date and time for checking the endpoint availability.

serviceProviderKey

String

Enter the unique key for the service provider of the endpoint.

provisionedEndpoint

Complex

apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section.


Table 2-50 describes the Is Endpoint Free Result service response.

Table 2-50 Is Endpoint Free Result

Parameter
Type
Description

free

Boolean

The boolean is set to true if the endpoint is available for the entire duration that is specified in the request.


Endpoint Elements

The endpoint definitions are common to all requests and responses in the Scheduling API that contain endpoints. The fields in the endpoint element vary depending on the type of endpoint.

The following sections describe the fields for each type of endpoint:

Provisioned Endpoint Fields

Unprovisioned Endpoint Fields

Remote Endpoint Fields

Provisioned Endpoint Fields

Provisioned endpoints are managed by the Cisco TelePresence Manager of the service provider. This enables the Cisco TelePresence Exchange System to offer One-Button-to-Push (OBTP) functionality for provisioned endpoints.

Table 2-51 describes the provisioned endpoint element.

Table 2-51 Provisioned Element Fields 

Parameter
Type
Description

dialOut

Boolean

(Optional) Indicates whether the system can dial out to this provisioned endpoint at the start of the meeting.

The dialOut default value is FALSE.

endpointKey

String

The unique key of the endpoint.

isHost

Boolean

Set to true of this endpoint is a designated host for the meeting.

ports

Integer

(Optional) The network bandwidth number for this endpoint. Units must be consistent with the maximum ports field that is configured for the organization.


Unprovisioned Endpoint Fields

Unprovisioned endpoints are not hosted by the service provider, so the Cisco TelePresence Exchange System does not provide One-Button-to-Push (OBTP) functionality for these endpoints.

Table 2-52 describes the unprovisioned endpoint element.

Table 2-52 Unprovisioned Element Fields 

Parameter
Type
Description

dialOut

Boolean

(Optional) Indicates whether the system can dial out to this unprovisioned endpoint at the start of the meeting.

The dialOut default value is FALSE.

Note This field is required only for guest outdials; it can otherwise be left blank.

mediaProfileKey

String

Specifies the media profile to use for this endpoint when dialing out.

number

String

The E.164 number for the guest dial out participant.

Note When the dialOut parameter has a value of TRUE, the number is required. Otherwise the number is ignored.

Note This field is required only for guest outdials; it can otherwise be left blank.

organizationKey

String

The unique key of the organization that is associated with this endpoint.

ports

Integer

(Optional) The network bandwidth number for this endpoint. Units must be consistent with the maximum bandwidth field that is configured for the organization.


Remote Endpoint Fields

Remote endpoints are not hosted by the service provider; therefore, the Cisco TelePresence Exchange System does not send any One-Button-to-Push (OBTP) information to remote endpoints. You do not need to specify any additional information for each remote endpoint in a meeting.

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

Revised January 30, 2013

The Cisco TelePresence Exchange System API communicates an error condition to the client by returning a SOAP fault message. The fault message contains an API scheduling exception, which is described in Table 2-53.

Table 2-53 API Scheduling Exception 

Parameter
Type
Description

cause code

String

(Optional) Provides more detailed information about an exception return code.

The cause codes are listed in the "Cause Codes" section.

erc

String

Exception return code.

Note For information on Scheduling Exception values, see Table 2-54.

message

String

English text message that provides additional information about the exception code. The content of the message varies depending on the exception code.

Note This message is not localized. Therefore, Cisco recommends that the message string not be displayed to the end user directly, due to the possibility that the portal may cater to multiple languages.

value map

String

(Optional) A name/value map in which each element is a pair of strings (a key and a value). The key identifies the type of entity, and the value identifies the specific instance that caused the exception.

Possible key values are as follows:

MEETING_KEY
ENDPOINT_KEY
ORGANIZATION_KEY
SERVICE_PROVIDER_KEY
REGION_KEY
MEETING_ENDPOINT_KEY
SERVICE_NUMBER_KEY
RESERVATION_TYPE_KEY
MEDIA_PROFILE_KEY
SUBSCRIPTION_KEY


The following example shows an error message caused by an unknown endpoint:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <env:Body>
      <env:Fault>
         <faultcode>env:Server</faultcode>
         <faultstring>Provisioned endpoint with key "00eb0d9b2b6007c7012b60207b8e01b9" not 
found</faultstring>
         <detail>
            <ns2:APISchedulingException xmlns:ns2="http://sched.api.ctc.txbu.cisco.com">
               <erc>ERC_NOT_FOUND</erc>
               <message>Provisioned endpoint with key "00eb0d9b2b6007c7012b60207b8e01b9" 
not found</message>
               <valueMap>
                  <map>
                     <entry key="ENDPOINT_KEY">00eb0d9b2b6007c7012b60207b8e01b9</entry>
                  </map>
               </valueMap>
            </ns2:APISchedulingException>
         </detail>
      </env:Fault>
   </env:Body>
</env:Envelope>

Table 2-54 describes the scheduling exception values.

Table 2-54 Scheduling Exception Values 

Exception Value
Description or Cause Code

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

Generic exception for a bad parameter value from the client.

ERC_INTERNAL_SCHEDULING_EXCEPTION

General scheduling failure. See the message element for more information about the exception.

ERC_SCHEDULING_VALIDATION_EXCEPTION

At least one of the supplied parameters is invalid or the specified combination of parameters is invalid. A cause code is returned.

The causeCode type is an enumeration, which is described in the "Cause Codes" section.

ERC_INVALID_DATE_TIME

The supplied date and time string is invalid.

ERC_INVALID_QUERY

The supplied query is badly-formed or contains an invalid property.

ERC_CTSMAN_COMMUNICATION_FAILURE

The Cisco TelePresence Manager might be unavailable for OBTP scheduling due to invalid login credentials, misconfiguration, or other communication failures. See specific cause codes below:

CTSMAN_SCHEDULING_ERROR
CTSMAN_CONNECTION_ERROR
CTSMAN_INTERCOMPANY_NOT_CONFIGURED

ERC_CONCURRENCY_FAILURE

This is a transient exception that often resolves itself on retry. The client is encouraged to retry the request.

ERC_STRING_TOO_LONG

The parameter string is too long.

ERC_CAPACITY_NOT_AVAILABLE

There is not enough capacity at the specified time for the meeting to be reserved.

ERC_NOT_FOUND

The provided key does not resolve to a valid item.

ERC_MISMATCHED_SERVICE_PROVIDER

The service provider that is supplied in the request does not match the stored service provider that is associated with the specified resource (endpoint or region).

ERC_LICENSE_ERROR

The Cisco TelePresence Exchange System requires a valid meeting service license. See specific cause codes below.

LICENSE_NOT_VALID
LICENSE_SERVER_NOT_ACCESSIBLE

ERC_ORG_BANDWIDTH_NOT_AVAILABLE

There is insufficient organization bandwidth for the meeting to be reserved.

ERC_CUVCM_SCHEDULING_FAILURE

This ERC is obsolete.

ERC_LARGE_CAPACITY_NOT_AVAILABLE

There is not enough capacity available on the large capacity Cisco TelePresence Multipoint Switch at the specified time to reserve the meeting.

ERC_RESOURCE_UNAVAILABLE

There is insufficient resource capacity at the specified time on the specified resource type. When you see the "large" term within the cause code, it refers to large meetings.

See specific cause codes below:

BRIDGE_RESOURCE_NOT_AVAILABLE
CTSMAN_RESOURCE_NOT_AVAILABLE
LARGE_BRIDGE_RESOURCE_NOT_AVAILABLE

ERC_RESTORE_IN_PROGRESS

A database restore is in progress; therefore, no requests can be handled. When the restore is complete, requests can be handled. (A database restore may take several minutes.)

ERC_BACKWARDS_COMPATIBILITY_ERROR

Error related to API backwards-compatibility behavior.

ERC_EXTERNAL_SCHEDULING_EXCEPTION

Error detected when scheduling an external meeting.

ERC_INVALID_DURATION

The request included an invalid time duration.

ERC_INVALID_GRANULARITY

The endpoint availability request included an invalid granularity for the period duration.

ERC_TOO_MANY_ENDPOINTS

The endpoint availability request included too many endpoints in the request.

ERC_CANNOT_EXPAND_MEETING_ON_SAME_BRIDGE

The meeting cannot be expanded with additional endpoints or capacity on the current bridge. This only applies to active meetings.


getPossibleCauseCodes

The Get Possible Cause Codes service returns a list of possible cause codes for the specified ERC (Exception Return Code). If no ercName parameter is provided, the service returns all possible cause codes that the scheduling API could use in an error message. Table 2-55 describes the parameters for the service request.

Table 2-55 Get Possible Cause Codes Request 

Parameter
Type
Description

ercName

String

Name of the ERC (Exception Return Code).


Table 2-56 describes the service response.

Table 2-56 Get Possible Cause Codes Response 

Parameter
Type
Description

return

Complex

List of causeCode elements. The causeCode type is an enumeration, which is described in the "Cause Codes" section.


Cause Codes

The list of possible cause codes includes the following:

BRIDGE_RESOURCE_NOT_AVAILABLE
CANNOT_ENABLE_HOST_FOR_ACTIVE_MEETING
CANNOT_SCHEDULE_IN_PAST
CTSMAN_CONNECTION_ERROR
CTSMAN_INTERCOMPANY_NOT_CONFIGURED
CTSMAN_RESOURCE_NOT_AVAIILABLE
CTSMAN_SCHEDULING_ERROR
DUPLICATE_CONFERENCE_ID
DUPLICATE_ENDPOINT
DUPLICATE_GUEST_DIALOUT_NUMBER
EMPTY_MEDIA_PROFILES_FOR_NON_PROVISIONED_ENDPOINT_MEETING
ENDPOINT_DOES_NOT_BELONG_TO_SERVICE_PROVIDER
ENDPOINT_DOES_NOT_SUPPORT_OBTP
ENDPOINT_NOT_ACTIVE
ENDPOINT_WITHOUT_ORGANIZATION_ASSIGNED
ENDPOINTS_FROM_DIFFERENT_CTSMANS
ENDPOINTS_FROM_DIFFERENT_ORGANIZATIONS
INVALID_DIALIN_PROTOCOL
INVALID_CAPACITY_VALUE
INVALID_CONFERENCE_ID
INVALID_DURATION
INVALID_E164_NUMBER
INVALID_HOST_PIN
INVALID_HOST_PIN_ENDPOINT_CONFIGURATION
INVALID_MEETING_EXTENSION_PERIOD
INVALID_NUMBER_OF_MEETING_EXTENSIONS
INVALID_TOTAL_MEETING_EXTENSION_TIME
INVALID_STRING_LENGTH
INVALID_UNPROVISIONED_DIALOUT_ENDPOINT_DOMAIN
LARGE_BRIDGE_RESOURCE_NOT_AVAILABLE
LICENSE_NOT_VALID
LICENSE_SERVER_NOT_ACCESSIBLE
REGION_DOES_NOT_BELONG_TO_SERVICE_PROVIDER
MAXIMUM_MEETING_DURATION_EXCEEDED
MEETING_IS_CANCELLED
MEETING_START_TIME_IN_PAST
MEETING_TYPE_ONLY_SUPPORTS_DIALIN
MISSING_ENDPOINT_NUMBER
MISSING_ENDPOINT_PROTOCOL
MISMATCHED_MEETING_TYPE
NEED_HOST_ROLE_ENABLED_AND_PIN
NOT_ENOUGH_ENDPOINTS_OR_EQUIVALENT_CAPACITY
ORGANIZATION_DOES_NOT_BELONG_TO_SERVICE_PROVIDER
REMOTE_ACCESS_NUMBER_NOT_VALID
REQUIRED_CONFIGURATION_MISSING
REQUIRED_PARAMETER_MISSING
SCHEDULER_EMAIL_NOT_VALID
TOO_LONG_ENDPOINT_NUMBER
PORTS_CANNOT_BE_NEGATIVE
SCHEDULER_ORGANIZATION_IS_REQUIRED
INVALID_PARAMETER_COMBINATION
INVALID_NUMBER_OF_ RENDEZVOUS_ENDPOINTS

Creating Queries

For services that retrieve information about data objects (such as endpoints or meetings) in the Cisco TelePresence Exchange System, the API provides a generalized query mechanism to allow clients to flexibly construct the desired queries. The API supports simple and complex queries. A null query is interpreted as a request to get all of the requested data objects.

This section provides a description of the queries and includes the following topics:

Query Syntax

Complex Queries

Null Queries

Endpoint Query Properties

Meeting Query Properties

Organization Query Properties

Regions Query Properties

Service Provider Query Properties

Service Number Query Properties

Media Profile Query Properties

Reservation Type Queries

WhiteList Groups Query Properties

Query Syntax

A simple query follows the following syntax:

(<property> <operator> <value>)

as shown in the following example:

(name sw Building31)
 
   

where

name is the property

sw is the operator

Building 31 is the value

Table 2-57 describes query parameters.

Table 2-57 Query Parameters 

Parameter
Description

property

Name of the property of the object to be queried. Examples include:

name

id

region.name

organization.serviceProvider.serviceProviderKey

You can specify the property in dotted notation format, which is shown in the above example. The property string is case-sensitive.

operator

The operator is a comparator or string match operator between the property and the value. Comparator operators include the following:

eq — equals

lt — less than

le — less than or equal

gt — greater than

ge — greater than or equal

The string match mode operators include the following:

sw — string starts with

ew — string ends with

contains — string contains

null — is null

notnull — is not null

value

Numeric or string value. String values are case sensitive and can contain spaces. When the operator is null or notnull, no value parameter is specified in the query.


Complex Queries

Simple queries can be combined by using the conjunctive operator (AND) and the disjunctive operator (OR) to make complex queries. For conjunctive operations, the syntax is as follows:

(AND (query) (query') (query'') ... )

The following is an example query for selecting specific endpoints:

(AND (name contains sjc) (lastModified gt 2011-0-04) (isActive eq true))

For disjunctive operations, the syntax is as follows:

(OR (query) (query') (query'') ... )

The complex query syntax is fully recursive, so that each query in a complex query can also be a conjunctive query (by using the AND keyword) or a disjunctive query (by using the OR keyword).

Null Queries

If you send a null or blank query in a request, the scheduling API interprets it as a request to get all of the requested objects.

Endpoint Query Properties

Table 2-58 provides a summary of query properties for endpoints.

Table 2-58 Endpoint Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Endpoint name

(name sw Cisco)

description

Endpoint description

(description notnull)

number

Directory number

(number eq 7206)

isActive

Is endpoint activated

(isActive eq true)

isSupportsOBTP

Does endpoint support One-Button-to-Push (OBTP)

(isSupportsOBTP eq true)

organization.name

Organization name

(organization.name sw Cisco)

organization.description

Organization description

(organization.description contains Ireland)

mediaProfile.name

Media profile name

(mediaProfile.name contains CTS-1000)

mediaProfile.description

Media profile name description

(mediaProfile.description sw Default CTS)

mediaProfile.numberOfScreens

Media profile number of screens

(mediaProfile.numberOfScreens gt 1)

organization.serviceProvider.name

Service provider name

(organization.serviceProvider.name sw Building31)

organization.serviceProvider.
description

Service provider description

(organization.serviceProvider.description contains 
telepresence)

Meeting Query Properties

Table 2-59 provides a summary of query properties for meetings.

Table 2-59 Meeting Query Properties 

Property
Description
Query String Example

meetingKey

Unique identifier

(meetingKey eq 0a4fa39d9c2d11df98187da9da46d147)

subject

Meeting subject

(subject contains weekly staff)

scheduler

Meeting scheduler

(scheduler eq john@cisco.com)

conferenceID

Meeting ID or access code

(conferenceID eq 11456271)

startTime

Starting time of the meeting

(startTime ge 2011-02-01)

endTime

Ending time of the meeting

(endTime gt 2011-04-16T12:00)

duration

Duration of the meeting

(duration le 30)

isRemote

Is this a remote meeting

(isRemote eq true)

isTwoPartyDirect

Is this a direct dial meeting

(isTwoPartyDirect eq true)

isCancelled

Was the meeting cancelled

(isCancelled eq true)

serviceProvider.name

Service provider name

(serviceProvider.name sw Building31)

serviceProvider.description

Service provider description

(serviceProvider.description contains telepresence)

isTimeless

Is this a Rendezvous meeting?

(isTimeless eq true)

conference.isHostRoleEnabled

Does this meeting require host pins?

(conference.isHostRoleEnabled eq true)

schedulerOrg.name

Scheduler's organization name

(schedulerOrg.name sw Cisco)

conference.hostPIN

Host PIN number

(conference.hostPIN eq 123456)

Organization Query Properties

Table 2-60 provides a summary of query properties for organizations.

Table 2-60 Organization Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Organization name

(name sw Cisco)

description

Organization description

(description contains Ireland)

maxBandwidth

Maximum bandwidth

(maxBandwidth ge 20)

directDialEnabled

Is direct dial enabled

(directDialEnabled eq true)

serviceProvider.name

Service provider name

(serviceProvider.name sw Building31)

serviceProvider.description

Service provider description

(serviceProvider.description contains telepresence)

Regions Query Properties

Table 2-61 provides a summary of query properties for regions.

Table 2-61 Regions Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Region name

(name sw WestCoast)

description

Region description

(description notnull)

serviceProvider.name

Service provider name

(serviceProvider.name sw Building31)

serviceProvider.description

Service provider description

(serviceProvider.description contains telepresence)

Service Provider Query Properties

Table 2-62 provides a summary of query properties for service providers.

Table 2-62 Service Provider Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Service provider name

(name sw Building31)

description

Service provider description

(description contains telepresence)

helpDeskNumber

Help desk phone number

(helpDeskNumber eq 1000)

Service Number Query Properties

Table 2-63 provides a summary of query properties for service numbers.

Table 2-63 Service Number Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Service number name

(name contains English)

description

Service number description

(description contains English)

number

Service number

(number sw 408)

Media Profile Query Properties

Table 2-64 provides a summary of query properties for media profiles.

Table 2-64 Media Profile Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Media profile name

(name sw CTS)

description

Media profile description

(description contains CTS)

Reservation Type Queries

Table 2-65 provides a summary of query properties for reservation types.

Table 2-65 Reservation Type Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Reservation type name

(name sw Standard)

description

Reservation type description

(description contains guaranteed)

isGuaranteed

Is reservation guaranteed

(isGuaranteed eq true)

WhiteList Groups Query Properties

Table 2-66 provides a summary of query properties for whitelist groups.

Table 2-66 Whitelist Group Query Properties 

Property
Description
Query String Example

key

Unique identifier

(key eq 0a4fa39d9c2d11df98187da9da46d147)

name

Whitelist group name

(name sw Open)

description

Whitelist group description

(description contains English)