Cisco Unity Connection Provisioning Interface (CUPI) API -- Schedules
Overview of Cisco Unity Connection Schedule Objects
Schedules in Cisco Unity Connection are somewhat complicated, since they are composed of several different types of objects. Before presenting the API for accessing schedules, it may be useful to review what these objects are and how they are used.
ScheduleSet Objects
ScheduleSet objects are the top-level objects. They are comprised of one or more Schedules, each of which is marked as included or excluded in the ScheduleSet.
Schedule Objects
Schedule objects are composed of one or more ScheduleDetail objects.
ScheduleDetail Objects
ScheduleDetail objects are the atomic schedule building blocks which comprise Schedule objects. They can be specified with Start and End Dates, Start and End Times of the day, and active Days of the Week. ScheduleDetails have a link to the Schedule objects that they are part of, and said Schedule object in a sense owns the ScheduleDetail object.
ScheduleSetMemberMap Objects
ScheduleSetMemberMap objects provide the linkage between a ScheduleSet and a Schedule that is included or excluded from it (via a boolean called Exclude). There will be one ScheduleSetMemberMap object for each Schedule that is included in or excluded from a ScheduleSet.
A ScheduleSetMemberMap abstracts the linkage between a ScheduleSet and a Schedule since neither object has an explicit linkage or ownership relationship of the other. One reason for this is that several ScheduleSets might reference the same Schedule (a Holiday Schedule for example). This differs from the relationship between a Schedule and a ScheduleDetail, since a ScheduleDetail has an explicit link to a Schedule, the Schedule essentially owns the ScheduleDetail, and no other Schedule may use another Schedule's ScheduleDetail object.
Schedule Example
For example, let's model a weekday schedule with the lunch hour blocked out as unavailable every work day, and with various holidays blocked out as well. Using the objects discussed previously, this schedule might be composed like so:
- First, we create a top-level ScheduleSet called WeekdaySet. WeekdaySet includes the WeekdaySchedule and excludes the HolidaySchedule (2 Schedule objects).
- After we create these 2 Schedule objects, we create 2 ScheduleSetMemberMap objects for WeekdaySet - one to include WeekdaySchedule and one to exclude HolidaySchedule.
- Then, we create 2 ScheduleDetail objects for WeekdaySchedule - one active from 8AM to 12PM Mon-Fri, and the other active from 1PM to 5PM Mon-Fri.
- Finally, we create various ScheduleDetails objects for HolidaySchedule, one per holiday. For example, we might create a July4ScheduleDetail with start and end dates both set to July 4 2010, and a WinterBreakScheduleDetail with a start date of Dec 23 2010 and an end date of Jan 3 2011.
To see how to create this schedule via CUPI, see the Schedule Example page.
CUPI for Schedules
The previously described database objects are accessible to the administrator via CUPI. The following sections list the URIs to access these resources along with the data contained within them.
ScheduleSets in CUPI
ScheduleSets are top-level resources in CUPI, with a base URI of +/vmrest/schedulesets+.
A ScheduleSet object has the following fields:
| Field Name | Field Type | Default | Notes |
|---|---|---|---|
| ObjectId | GUID | None | NA |
| TenantObjectId | Read Only | String (36) | The unique identifier of the tenant to which the schedulesets belong. This field is reflected in the response only if the schedulesets belong to a particular tenant. |
| DisplayName | String (64) | None | NA |
| OwnerLocationObjectId | GUID | Null | One of the Owners must be non-NULL |
| OwnerPersonalRulesSetObjectId | GUID | Null | NA |
| OwnerSubscriberObjectId | GUID | Null | NA |
| Undeletable | Boolean | False | Is only True for factory default objects |
Retrieving the list of ScheduleSets
To retrieve the list of ScheduleSets, an administrator makes a GET to the schedulesets resource:
|
This would return the following on success:
|
Listing Specific Tenant Related ScheduleSets by System Administrator
In Cisco Unity Connection 10.5(2) and later, the system administrator can use TenantObjectID to list the specific tenant related schedulesets using the following URI:
|
To get the TenantObjectID, use the following URI:
|
Retrieving a ScheduleSet
To retrieve a single ScheduleSet, an administrator makes a GET to the schedulesets resource, specifying the ObjectId of the requested ScheduleSet in the URI:
|
This would return the following on success:
|
This would return the following if the specified ScheduleSet does not exist:
|
Adding a ScheduleSet
To add a new ScheduleSet, an administrator makes a POST to the schedulesets resource, specifying the new ScheduleSet via XML:
|
This will return the URI to the newly created ScheduleSet (which includes its ObjectId):
|
Changing a ScheduleSet
To change an existing ScheduleSet, an administrator makes a PUT to the schedulesets resource, specifying the ObjectId of the ScheduleSet they wish to change in the URI and any data changes via XML:
|
This would return the following on success:
|
This would return the following if the specified scheduleset does not exist:
|
Deleting a ScheduleSet
To delete an existing ScheduleSet, an administrator makes a DELETE to the schedulesets resource, specifying the ObjectId of the ScheduleSet they wish to delete in the URI:
|
This would return the following on success:
|
This would return the following if the specified scheduleset does not exist:
|
Note that if an administrator deletes a ScheduleSet object, then all of the supporting ScheduleSetMembers for that ScheduleSet will also be deleted.
Schedules in CUPI
Schedules are top-level resources in CUPI, with a base URI of +/vmrest/schedules+.
A Schedule object has the following fields:
| Field Name | Field Type | Default | Notes |
|---|---|---|---|
| ObjectId | GUID | None | Na |
| TenantObjectId | Read Only | String (36) | The unique identifier of the tenant to which the schedule belong. This field is reflected in the response only if the schedule belong to a particular tenant. |
| DisplayNamre | String (64) | None | NA |
| OwnerLocationObjectId | GUID | NULL | One of the Owner's must be non-NULL |
| OwnerPersonalRuleSetObjectId | GUID | NULL | Na |
| OwnerSubscriberObjectId | GUID | NULL | NA |
| Undeletable | Boolean | False | Is only True for factory default objects |
| StartDate | DateTime | NULL | NULL means effective immediately |
| EndDate | DateTime | NULL | NULL means effective indefinitely |
| IsHoliday | Bolean | False | Holiday Greetings are used during this period if True |
Retrieving the list of Schedules
To retrieve the list of Schedules, an administrator makes a GET to the schedules resource:
|
This would return the following on success:
|
Listing Specific Tenant Related Schedules by System Administrator
In Cisco Unity Connection 10.5(2) and later, the system administrator can use TenantObjectID to list the specific tenant related schedules using the following URI:
|
To get the TenantObjectID, use the following URI:
|
Retrieving a Schedule
To retrieve a single Schedule, an administrator makes a GET to the schedules resource, specifying the Objectid of the requested Schedule in the URI:
|
This would return the following on success:
|
This would return the following if the specified Schedule does not exist:
|
Adding a Schedule
To add a new Schedule, an administrator makes a POST to the schedules resource, specifying the new Schedule via XML:
|
This will return the URI to the newly created Schedule (which includes its ObjectId):
|
Changing a Schedule
To change an existing Schedule, an administrator makes a PUT to the schedules resource, specifying the ObjectId of the Schedule they wish to change in the URI and any data changes via XML:
|
This would return the following on success:
|
This would return the following if the specified schedule does not exist:
|
Deleting a Schedule
To delete an existing Schedule, an administrator makes a DELETE to the schedules resource, specifying the ObjectId of the Schedule they wish to delete in the URI:
|
This would return the following on success:
|
This would return the following if the specified schedule does not exist:
|
Note that if an administrator deletes a Schedule object, then all of the supporting ScheduleDetail objects for that Schedule will also be deleted.
ScheduleSetMembers in CUPI
ScheduleSetMembers are the resources representing ScheduleSetMemberMaps objects. They are sub-resources of ScheduleSets in CUPI, and thus are at a sub-URI of the schedulesets resource: +/vmrest/scheduleset/+{_}+<ScheduleSetObjectId>+{_}+/schedulesetmembers+.
A ScheduleSetMember object has the following fields:
| Field Name | Field Type | Default | Notes |
|---|---|---|---|
| ScheduleSetObjectId | GUID | None | Owning ScheduleSet |
| ScheduleObjectId | GUID | None | Schedule to include/exclude from ScheduleSet |
| Exclude | Boolean | False | False means Include, True means Exclude |
Retrieving the list of ScheduleSetMembers
To retrieve the list of ScheduleSetMembers for a particular ScheduleSet, an administrator makes a GET to the schedulesetmembers resource, specifying the ObjectId of the ScheduleSet in the URI:
|
This would return the following on success:
|
Retrieving a ScheduleSetMember
To retrieve a single ScheduleSetMember for a particular ScheduleSet, an administrator makes a GET to the schedulesetmembers resource, specifying the ObjectIds of the ScheduleSet and the requested ScheduleSetMember in the URI:
|
This would return the following on success:
|
This would return the following if the specified ScheduleSetMember does not exist (meaning the Schedule is not listed as either included or excluded from the ScheduleSet):
|
Adding a ScheduleSetMember
To add a new ScheduleSetMember to a particular ScheduleSet, an administrator makes a POST to the schedulessetmembers resource, specifying the ObjectId of the ScheduleSet in the URI and the new ScheduleSetMember via XML:
|
This will return the URI to the newly created ScheduleSetMember (which includes its ObjectId):
|
 Note |
A ScheduleSet can have at most 1 Schedule marked as Included, and that Schedule must not be a Holiday Schedule. A ScheduleSet can also have at most 1 Schedule marked as Excluded, and that Schedule must be a Holiday Schedule. If an administrator makes a POST to the schedulesetmembers resource in an attempt to Include or Exclude more than 1 Schedule of a given type to a ScheduleSet, then CUPI will return an HTTP 400 error with a descriptive error message. Similarly, if an administrator makes a POST to the schedulesetmembers resource in an attempt to Include a Holiday Schedule or Exclude a non-Holiday Schedule, then CUPI will return an HTTP 400 error with a descriptive error message. |
Changing a ScheduleSetMember
The schedulesetmembers resource does not support the PUT method. In order to change a ScheduleSetMember, an administrator must delete the existing one and then add it back with the requested change.
Deleting a ScheduleSetMember
To delete an existing ScheduleSetMember for a particular ScheduleSet, an administrator makes a DELETE to the schedulesetmembers resource, specifying the ObjectIds of the ScheduleSet and the ScheduleSetMember they wish to delete in the URI:
|
This would return the following on success:
|
This would return the following if the specified schedulesetmember does not exist:
|
ScheduleDetails in CUPI
ScheduleDetails are sub-resources of Schedules in CUPI, and thus are at a sub-URI of the schedules resources: +/vmrest/schedules/+{_}+<ScheduleObjectId>+{_}+/scheduledetails+.
A ScheduleDetail object has the following field:
| Field Name | Field Type | Default | Notes |
|---|---|---|---|
| ObjectId | GUID | None | NA |
| Subject | String (2048) | None | NA |
| ScheduleObjectId | GUID | None | Owning Schedule |
| StartDate | DateTime | NULL | NULL means effective immediately, also Time portion of DateTime is ignored |
| StartTime | Int | NULL | NULL means 12:00AM, otherwise minutes past 12:00AM so 480 means 8:00AM |
| EndDate | DateTime | NULL | NULL means effective indefinitely, also Time portion of DateTime is ignored |
| EndTime | Int | NULL | NULL means End-of-Day (11:59:59PM), otherwise minutes past 12:00AM so 1020 means 5:00PM |
| IsActiveMonday | Boolean | False | NA |
| IsActiveTuesday | Boolean | False | NA |
| IsActiveWednesday | Boolean | False | NA |
| IsActiveThursday | Boolean | False | NA |
| IsActiveFriday | Boolean | False | NA |
| IsActiveSaturday | Boolean | False | NA |
| IsActiveSunday | Boolean | False | NA |
Retrieving the list of ScheduleDetails
To retrieve the list of ScheduleDetails for a particular Schedule, an administrator makes a GET to the scheduledetails resource, specifying the ObjectId of the Schedule in the URI:
|
This would return the following on success:
|
Retrieving a ScheduleDetail
To retrieve a single ScheduleDetail for a particular Schedule, an administrator makes a GET to the scheduledetails resource, specifying the ObjectIds of the Schedule and the requested ScheduleDetail in the URI:
|
This would return the following on success:
|
This would return the following if the specified ScheduleDetail does not exist:
|
Adding a ScheduleDetail
To add a new ScheduleDetail to a particular Schedule, an administrator makes a POST to the scheduledetails resource, specifying the ObjectId of the Schedule in the URI and the new ScheduleDetail via XML:
|
This will return the URI to the newly created ScheduleDetail (which includes its ObjectId):
|
Changing a ScheduleDetail
To change an existing ScheduleDetail for a particular Schedule, an administrator makes a PUT to the scheduledetails resource, specifying the ObjectId of the Schedule and the ScheduleDetail they wish to change in the URI and the data changes via XML:
|
This would return the following on success:
|
This would return the following if the specified ScheduleDetail does not exist:
|
Deleting a ScheduleDetail
To delete an existing ScheduleDetail from a particular Schedule, an administrator makes a DELETE to the scheduledetails resource, specifying the ObjectId of the Schedule and the ScheduleDetail they wish to delete in the URI:
|
This would return the following on success:
|
This would return the following if the specified ScheduleDetail does not exist:
|
Feedback