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:
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, and endpoints 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:
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.
All media resources in a region are dedicated to one service provider.
A service provider might have multiple regions that are configured on a Cisco TelePresence Exchange System.
An organization is a business customer that is served by a service provider. An organization controls one or more telepresence rooms (also known as 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 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. You must specify the ports that are required by endpoints when you schedule the meeting.
When the system schedules a 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 provides telepresence services for Cisco TelePresence System (CTS) endpoints and third-party endpoints. Cisco TelePresence endpoints include both TIP-based endpoints and standards-based H.323 and ISDN endpoints. Supported third-party endpoints only include select single-screen endpoints that are H.323 and ISDN standards-based.
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 API also distinguishes the following endpoint types:
•CTS—Cisco Telepresence System endpoints.
•INTEROP—Standards-based (H.323, ISDN) endpoints that can interoperate with the Cisco TelePresence Exchange System.
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_0/install_admin/book/b_install_admin.html.
Each meeting is associated with a service provider and a region. All media resources for the meeting will be allocated from the specified region, even if some participants are from another region or a different service provider. You must specify the region when you schedule the meeting.
The Cisco TelePresence Exchange System supports the following types of meetings:
•Meet-Me meeting—A Meet-Me service meeting that is hosted by this Cisco TelePresence Exchange System. The system reserves and allocates media resources for all of the endpoints in the meeting and provides One-Button-to-Push (OBTP) functionality to the provisioned endpoints. The system also reserves bandwidth for the meeting, if requested.
•Remote meeting—A Meet-Me service 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.
You can access the WSDL file for the Scheduling API at
http://<DNS name or IP address for your admin server>:8080/ctxapi/api/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.
The Scheduling API assigns a unique identifier (called a key) to each service provider, organization, region, endpoint and meeting.
When the API responds to Get requests, each item in the response is represented as a pair of values called a key name map. A key name map contains the item key and a text string that contains the name of the item.
Key name maps are provided as a convenience for the API user. The name string provides a human-readable identifier for the item (for use in a display or a report). The key provides a unique identifier for the item. You use the key in subsequent API requests to ensure that the service selects the correct item.
Table 3-1 describes the fields in a key map.
The Scheduling API provides methods for retrieving configured information about endpoints, regions, and organizations that are configured on the Cisco TelePresence Exchange System. The methods are described in the following sections:
•getOrganizationsForServiceProvider
The Get Endpoints service returns a list of endpoints that meet the criteria that are supplied in the request. Table 3-2 describes the parameters in the service request.
|
|
|
---|---|---|
queryString |
String |
(Optional) Enter a query to select the desired set of endpoints. For information about building queries, see the "Query Syntax" section. |
endpointType |
String |
(Optional) Specifies the endpoint type for the service to return. You can enter one of the following values: •CTS—Cisco Telepresence System endpoints. •INTEROP—Standards-based (H.323, ISDN) endpoints that can interoperate with the Cisco TelePresence Exchange System. Note The system ignores the endpointType parameter if you enter a null string. |
The service returns a Get Endpoints Result in the service response. Table 3-3 describes the Get Endpoints Result.
|
|
|
---|---|---|
endpoints |
Complex |
List of apiEndpoints. See Table 3-4 for a description of apiEndpoint element. |
totalNumberFound |
Integer |
The total number of records that are found and returned in the query. The value is zero if the query did not match any endpoints. |
Table 3-4 describes the apiEndpoint element.
|
|
|
---|---|---|
isCts |
Boolean |
Returns true if the endpoint is a Cisco TelePresence endpoint. |
keyNameMap |
keyNameMap |
Contains a key, which is a unique identifier for the endpoint, and the corresponding endpoint name. See Table 3-1 for the keyNameMap fields. |
number |
number |
Provides the directory number for the endpoint. |
supportOBTP |
Boolean |
Indicates that the endpoint supports OBTP functionality. |
Example
The following example shows how to get the list of endpoints that meet a complex query. The API will include an endpoint in the response if the endpoint name starts with the letters test, the endpoint capacity is less than one, and the endpoint is synchronized with the Cisco TelePresence Manager.
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sch="http://sched.api.ctx.txbu.cisco.com">
<soapenv:Header/>
<soapenv:Body>
<sch:getEndpoints>
<queryString>(AND (roomName sw test) (capacity lt 1) (isSynchronized eq true))</queryString>
</sch:getEndpoints>
</soapenv:Body>
</soapenv:Envelope>
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 3-5 describes the parameters for the service request.
The service response contains a Get Endpoints Result. The Get Endpoints Result is described in Table 3-3.
The Get Regions service returns a list of regions that meet the query criteria that are supplied in the request. Table 3-6 describes the parameters for the service request.
|
|
|
---|---|---|
queryString |
String |
(Optional) Enter a query to select the desired set of regions. |
Table 3-7 describes the Get Regions service response.
|
|
|
---|---|---|
regions |
Complex |
List of zero or more apiRegions. The apiRegion type is a key name map, which is described in Table 3-1. Each apiRegion provides the unique key and name of a region. |
totalNumberFound |
Integer |
The total number of region records returned. |
The Get Regions for Service Provider service returns a list of regions that are configured for the specified service provider. Table 3-8 describes the parameters for the service request.
The service response contains a Get Regions Result, which is described in Table 3-7.
The Get Organizations service returns a list of all organizations that meet the criteria that are supplied in the request. Table 3-9 describes the parameters for the service request.
|
|
|
---|---|---|
queryString |
String |
(Optional) Enter a query to select the desired set of organizations. For information about building queries, see the "Query Syntax" section. |
Table 3-10 describes the parameters for the service response.
|
|
|
---|---|---|
organizations |
Complex |
List of zero or more apiOrganizations that meet the query criteria. The apiOrganization type is described in Table 3-11. |
totalNumberFound |
Integer |
The total number of records returned. |
Table 3-11 describes the apiOrganization type.
|
|
|
---|---|---|
keyNameMap |
keyNameMap |
Unique organization key and the corresponding text name. The key name map is described in Table 3-1. |
maxPort |
Integer |
Maximum number of ports that can be scheduled for this organization. |
The Get Organizations for Service Provider service returns a list of organizations that are configured for the specified service provider. Table 3-12 describes the parameters for the service request.
|
|
|
---|---|---|
serviceProviderKey |
String |
(Required) Enter the unique key of the service provider. |
The service response contains the Get Organizations Result element, which is described in Table 3-10.
The Get Service Provider service returns a list of service providers that meet the criteria that are supplied in the request. Table 3-13 describes the parameters for the service request.
|
|
|
---|---|---|
queryString |
String |
(Optional) Enter a query string. For information about building queries, see the "Query Syntax" section. |
Table 3-14 describes the service response.
|
|
|
---|---|---|
serviceProviders |
Complex |
List of apiServiceProviders. The apiServiceProvider type is a key name map, which is described in Table 3-1. Each apiServiceProvider provides the unique key and name of a service provider. |
totalNumberFound |
Integer |
The total number of service provider records returned. |
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 3-15 describes the parameters for the service request.
Table 3-16 describes the Get Ports by Organization response.
|
|
|
---|---|---|
APIPortsList |
Complex |
List of apiPorts elements. The apiPorts elements are described in Table 3-17. For each organization (or the specified organization), the service returns one apiPorts element for each 15-minute interval in the requested duration. |
Table 3-17 describes the apiPorts element.
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 any subsequent request to view, modify or delete the meeting.
Table 3-18 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 |
(Optional) 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 |
(Required) Enter the subject of the meeting. |
dateTimeStr |
Date/time string |
(Required) Enter the date and time for the start of the meeting. |
duration |
Integer |
(Required) Enter the duration of the meeting in minutes. |
serviceProviderKey |
String |
(Required) Enter the unique key of the service provider that will host the meeting. |
regionKey |
String |
(Required) Enter the key of the region for the meeting. The region must be associated with the service provider. |
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 |
(Required) Enter the additional capacity to reserve for unprovisioned and remote endpoints in the meeting. Units are segments. |
bridgeCapabilityList |
Complex |
Enter the bridge capabilities that are required for the meeting. Enter one of the following values: •SUPPORT_ANY_CTS •SUPPORT_SINGLESCREEN_INTEROP •SUPPORT_MULTISCREEN_INTEROP Note The system can infer the bridge requirements for provisioned endpoints. The bridge capability list is required to specify capabilities for unprovisioned and remote endpoints. Note When no provisioned endpoints are specified in the request, the bridgeCapabilityList parameter is required. When one or more endpoints are specified in the bridgeCapabilityList, this parameter is optional. |
customLayout |
Integer |
(Optional) Enter a default value for the screen layout. For details on the layout values, see the "Conference Layouts" section of the Cisco TelePresence MCU Remote Management API Reference Guide, at http://www.cisco.com/en/US/products/ps11341/products_programming_reference_guides_list.html. Note When the conference is not hosted on a Cisco TelePresence MCU MSE 8510, the customLayout parameter is ignored. |
Table 3-19 describes the Schedule Meeting result.
Examples
The following example shows how to schedule a meeting:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sch="http://sched.api.ctx.txbu.cisco.com">
<soapenv:Header/>
<soapenv:Body>
<sch:scheduleMeeting>
<auditID>audit</auditID>
<schedulerEmail>user1@cisco.com</schedulerEmail>
<subject>test</subject>
<dateTimeStr>2011-04-19T06:00:00-07:00</dateTimeStr>
<duration>15</duration>
<serviceProviderKey>0a4fa39d9c2d11df98187da9da46d147</serviceProviderKey>
<regionKey>09439bb29c2d11df98187da9da46d147</regionKey>
<requireOBTP>true</requireOBTP>
<provisionedEndpointList>
<provisionedEndpoints>
<endpointKey>00eb0d9b2b6007c7012b60207b8e01ba</endpointKey>
<bandwidth>2</bandwidth>
<dialOut>false</dialOut>
<minimizeCapacity>false</minimizeCapacity>
</provisionedEndpoints>
</provisionedEndpointList>
<unprovisionedEndpointList>
<unprovisionedEndpoints>
<bandwidth>4</bandwidth>
<organizationKey>0b463c0b9c2d11df98187da9da46d147</organizationKey>
</unprovisionedEndpoints>
</unprovisionedEndpointList>
<remoteEndpointList>
<remoteEndpoints/>
</remoteEndpointList>
<additionalCapacity>8</additionalCapacity>
<bridgeCapabilityList>
<bridgeCapabilties>SUPPORT_ANY_CTS</bridgeCapabilties>
</bridgeCapabilityList>
<customLayout/>
</sch:scheduleMeeting>
</soapenv:Body>
</soapenv:Envelope>
The following example shows the response to the Schedule Meeting request:
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
<ns2:scheduleMeetingResponse xmlns:ns2="http://sched.api.ctx.txbu.cisco.com">
<return>
<accessNumber>12345</accessNumber>
<conferenceID>05195048</conferenceID>
<meetingKey>00eb0da32a830ebc012a865fa8f9003a</meetingKey>
<bridgeResourceType>CTMS</bridgeResourceType>
<capacityAllocated>12</capacityAllocated>
</return>
</ns2:scheduleMeetingResponse>
</env:Body>
</env:Envelope>
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 3-20 describes the parameters for the Schedule Remote Meeting service request.
|
|
|
---|---|---|
accessNumber |
Digit string |
(Required) Number that the participants dial to join the meeting. |
conferenceID |
String |
(Required) Conference ID for the participants to input when they join the meeting. |
schedulerEmail |
String |
(Optional) 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 |
(Required) Enter the subject of the meeting. |
dateTimeStr |
Date/time string |
(Required) Enter the date and time for the start of the meeting. |
duration |
Integer |
(Required) Enter the duration of the meeting in minutes. |
serviceProviderKey |
String |
(Required) 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 response contains a scheduleMeetingResult element, which is described in Table 3-19.
The Schedule Two Party Direct Meeting service creates a new direct meeting between two local provisioned endpoints within the same organization, 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 for a two party meeting. Two party meetings are scheduled to provide One-Button-to-Push (OBTP) functionality for the endpoints.
Table 3-21 describes the parameters for the service request.
|
|
|
---|---|---|
schedulerEmail |
String |
(Optional) 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 |
(Required) Enter the subject of the meeting. |
dateTimeStr |
Date/time string |
(Required) Enter the date and time for the start of the meeting. |
duration |
Integer |
(Required) Enter the duration of the meeting in minutes. |
serviceProviderKey |
String |
(Required) 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 |
(Required) Enter a apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section. |
provisionedEndpoint2 |
Complex |
(Required) Enter a apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section. |
The service response contains a scheduleMeetingResult element, which is described in Table 3-19.
The Modify Meeting service modifies the information for a meeting based on the parameter values that are supplied in the request. Null parameter values are set for fields that you do not want to change.
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.
Note When modifying a 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 3-22 describes the parameters for the service request.
|
|
|
---|---|---|
meetingKey |
Integer |
(Required) Enter the meeting key. The meeting key 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. |
regionKey |
String |
(Optional) Enter the unique region key for the meeting. The region must be associated with the service provider. |
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 provisionedEndpointList must be specified to retain the original endpoints. When a null or empty list is provided, it is interpreted that all endpoints are being removed. |
unprovisionedEndpointList |
Complex |
Enter a list of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section. Note The unprovisionedEndpointList must be specified to retain the original endpoints. When a null or empty list is provided, it is interpreted that all endpoints are being removed. |
remoteEndpointList |
Complex |
Enter a list of apiRemoteEndpoint elements. See the "Remote Endpoint Fields" section. Note The remoteEndpointList must be specified to retain the original endpoints. When a null or empty list is provided, it is interpreted that all endpoints are being removed. |
additionalCapacity |
Integer |
(Optional) Enter the additional capacity to reserve for unprovisioned and remote endpoints in the meeting. Units are segments. |
bridgeCapabilityList |
Complex |
(Optional) Enter the bridge capabilities that are required for the meeting. Enter one of the following values: •SUPPORT_ANY_CTS •SUPPORT_SINGLESCREEN_INTEROP •SUPPORT_SINGLESCREEN_INTEROP |
customLayout |
Integer |
(Optional) Enter a default value for the screen layout. For details on the layout values, see the "Conference Layouts" section of the Cisco TelePresence MCU Remote Management API Reference Guide, at http://www.cisco.com/en/US/products/ps11341/products_programming_reference_guides_list.html. |
Table 3-23 describes the Modify Meeting result.
The Modify Remote Meeting service modifies the information for a remote meeting based on the parameter values that are supplied in the request. Set null parameter values in the request for fields that you are not changing.
Note The Modify Remote Meeting service request must include the meeting key of the meeting to be modified.
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 3-24 describes the parameters for the Modify Remote Meeting request.
|
|
|
---|---|---|
meetingKey |
String |
(Required) Enter the meeting key, which is the unique identifier of a specific meeting. |
accessNumber |
String |
(Optional) Enter the number that the participants dial to join the meeting. |
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 provisionedEndpointList must be specified to retain the original endpoints. When a null or empty list is provided, it is interpreted that all endpoints are being removed. |
unprovisionedEndpointList |
Complex |
Enter a list of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section. Note The unprovisionedEndpointList must be specified to retain the original endpoints. When a null or empty list is provided, it is interpreted that all endpoints are being removed. |
No parameters are returned in the Modify Remote Meeting service response.
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. Set null parameter values in the request for fields that you are not changing.
Note The Modify Two Party Direct Meeting service request must include the meeting key of the meeting that you want to modify.
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 3-25 describes the parameters for the Modify Two Party Direct Meeting request.
|
|
|
---|---|---|
meetingKey |
String |
(Required) 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 Either both the provisionedEndpoint1 and the provisionedEndpoint2 parameters must change or both parameters must be set to null to indicate no change. |
provisionedEndpoint2 |
Complex |
Enter a apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section. Note Either both the provisionedEndpoint1 and the provisionedEndpoint2 parameters must change or both parameters must be set to null to indicate no change. |
No parameters are returned in the Modify Two Party Direct Meeting service response.
This service cancels a scheduled meeting. The service request must include the meeting key of the meeting that you want to cancel.
Table 3-26 describes the fields in the Cancel Meeting request.
The Cancel Meeting service request has no response.
The service returns the details for the meeting that are specified by the meeting key that is supplied in the request.
Table 3-27 describes the fields in the Get Meeting request.
|
|
|
---|---|---|
meetingKey |
Integer |
(Required) Enter the meeting key, which is the unique identifier of a specific meeting. |
The Get Meeting Response returns a list of apiMeeting elements. Table 3-28 describes the apiMeeting element.
|
|
|
---|---|---|
accessNumber |
String |
The number that the participants dial to join the meeting. |
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. |
duration |
Integer |
The duration of the meeting in minutes. |
isCancelled |
Boolean |
This element is set to TRUE if the meeting is cancelled. |
isRemote |
Boolean |
This element is set to TRUE if the meeting is remote. |
meetingKey |
Integer |
The meeting key is a unique identifier of a specific 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. |
subject |
String |
Subject of the meeting. |
unprovisionedEnd |
Complex |
List of apiUnprovisionedEndpoint elements. See the "Unprovisioned Endpoint Fields" section. |
The Check Ports service queries availability of sufficient organization port bandwidth for the specified meeting. Table 3-29 describes the fields in the Check Port request.
|
|
|
---|---|---|
meetingKey |
Integer |
(Required) Enter the meeting key, which is the unique identifier of a specific meeting. |
dateTimeStr |
Date/time string |
(Required) Enter the date and time of the start of the meeting. |
duration |
Integer |
(Required) Enter the duration of the meeting in minutes. |
serviceProviderKey |
String |
(Required) Enter the unique key for the service provider. |
provisionedEndpointList |
Complex |
(Required) Enter a list of the apiProvisionedEndpoint elements. See the "Provisioned Endpoint Fields" section. |
Table 3-30 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. Table 3-31 describes the fields in the Is Endpoint Free request.
|
|
|
---|---|---|
dateTimeStartStr |
String |
(Required) Start date and time for checking the endpoint availability. |
dateTimeEndStr |
String |
(Required) End date and time for checking the endpoint availability. |
serviceProviderKey |
String |
(Required) Enter the unique key for the service provider of the endpoint. |
provisionedEndpoint |
Complex |
(Required) apiProvisionedEndpoint element. See the "Provisioned Endpoint Fields" section. |
Table 3-32 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 XML definitions for endpoints 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 3-33 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 3-34 describes the unprovisioned endpoint element.
Remote endpoints are not hosted by the service provider; therefore, the Cisco TelePresence Exchange System does not provide One-Button-to-Push (OBTP) functionality for remote endpoints. You do not need to specify any information to include a remote endpoint in a meeting.
See the following sections:
•echo
The Echo service allows the system to confirm that the Scheduling API service is active. The client includes an arbitrary string in the echo request and the response message includes the same string.
Table 3-35 describes the input parameters for the Echo service request.
|
|
|
---|---|---|
echoString |
String |
(Required) Enter an arbitrary string. The same string is returned in the response message. |
Table 3-36 describes the parameters in the Echo service response.
|
|
|
---|---|---|
return |
String |
The value of the string is identical to the string that was sent in the request message. |
The Get Version service returns the version of the Scheduling API. The service request contains no input parameters.
Table 3-37 describes the parameters in the service response.
|
|
|
---|---|---|
return |
String |
The value of the string is the build version of the Scheduling API. |
The Cisco TelePresence Exchange System API communicates an error condition to the client by returning a SOAP fault message. The fault message contains an API scheduling exception, which is described in Table 3-38.
|
|
|
---|---|---|
erc |
String |
Exception return code. Note For information on Scheduling Exception values, see Table 3-39. |
cause code |
String |
(Optional) Provides more detailed information about an exception return code. |
error map |
Map |
An optional map with name and value pairs that identify the parameters that caused the exception. Possible keys are as follows: MEETING_KEY |
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. |
Table 3-39 describes the scheduling exception values.
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
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 3-40 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 3-41 provides a summary of query properties for endpoints.
Table 3-42 provides a summary of query properties for meetings.
Table 3-43 provides a summary of query properties for organizations.
Table 3-44 provides a summary of query properties for regions.
Table 3-45 provides a summary of query properties for service providers.