The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
The Cisco TelePresence Exchange System provides 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:
•Obtaining Configured Information
•Scheduling and Managing Meetings
This section describes how to get started with the Scheduling API and includes the following topics:
•Required and Optional Parameters
•API Parameter Naming Conventions
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.
The API uses a number of information elements. These elements are described in the following sections:
•Resource Groups and Reservation Types
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
The API uses the following conventions for parameter names.
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.
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).
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).
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:
•getOrganizationsForServiceProvider
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.
The service returns a Get Endpoint Availability Result in the service response. Table 2-2 describes the Get Endpoints Result.
|
|
|
---|---|---|
endpointAvailability |
Complex |
List of endpointAvailability elements. See Table 2-3 for a description of endpointAvailability element. |
Table 2-3 describes the endpointAvailability element.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
The service response contains a Get Endpoints Result. The Get Endpoints Result is described in Table 2-5.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
The service response contains the Get Organizations Result element, which is described in Table 2-12.
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-16 describes the Get Ports by Organization response.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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. |
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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.
The following sections describe the services for scheduling and managing meetings:
•scheduleTwoPartyDirectMeeting
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
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.
The Cancel Meeting service request has no response.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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. |
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
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 |
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). |
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.
|
|
|
---|---|---|
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.
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.
|
|
|
---|---|---|
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.
|
|
|
---|---|---|
free |
Boolean |
The boolean is set to true if the endpoint is available for the entire duration that is specified in the request. |
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:
•Unprovisioned 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.
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.
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.
Each of the Cisco TelePresence Exchange System APIs supports a common set of methods, which are described in the following sections:
•echo
The Echo service allows the system to confirm that the Scheduling API service is active.
For additional details about this service, see the "echo" section.
The Get Version service returns the product software version. For additional details about this service, see the "getVersion" section.
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.
|
|
|
---|---|---|
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 |
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.
|
|
---|---|
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 |
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 |
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 |
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. |
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.
|
|
|
---|---|---|
ercName |
String |
Name of the ERC (Exception Return Code). |
Table 2-56 describes the service response.
|
|
|
---|---|---|
return |
Complex |
List of causeCode elements. The causeCode type is an enumeration, which is described in the "Cause Codes" section. |
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
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:
•Organization Query Properties
•Service Provider Query Properties
•Service Number Query Properties
•Media Profile Query Properties
•WhiteList Groups Query Properties
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.
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).
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.
Table 2-58 provides a summary of query properties for endpoints.
Table 2-59 provides a summary of query properties for meetings.
Table 2-60 provides a summary of query properties for organizations.
Table 2-61 provides a summary of query properties for regions.
Table 2-62 provides a summary of query properties for service providers.
Table 2-63 provides a summary of query properties for service numbers.
Table 2-64 provides a summary of query properties for media profiles.
Table 2-65 provides a summary of query properties for reservation types.
Table 2-66 provides a summary of query properties for whitelist groups.