WorkCalService
The WorkCalService contains functions to create, delete, edit, and get information about base and overlay calendars and the time zones and calendar entries that they use.
The table below lists the functions available from the WorkCalService.
For more information about calendars, see Calendars.
| Function | Description | Returns |
|---|---|---|
| copyCalendar | Copies an existing calendar to create a new calendar of the same type.
The request must identify the existing calendar and include a valid name and namespace for the new calendar. Note that <blank> is a valid namespace. The name specified must be unique within the given namespace. For base calendars, the properties to be copied from the original calendar will include the time zone and working hours. For both base and overlay calendars, all future calendar entries can also be copied if requested. Required system action: writeCalendars |
XmlUpdatedCalendar |
| createCalendarEntry | Creates a new working-day-exclusion calendar entry. (Note that in this context, "entry" is synonymous with "exclusion.")
Date and time values in the request are expected to be time-zone neutral. The request must include a version number that is compared against the value held by the identified calendar entry. If the values don't match, the request fails with a "concurrency exception". Required system action: writeCalendars |
XmlCalendarEntries |
| createCalendarReferences | Associates a calendar with a calendar reference that was created in TIBCO Business Studio. A reference can refer to only one calendar, but a calendar can be referenced by any number of client references.
If the request includes a calendar reference that is already associated with another calendar, that association is removed before adding the reference to the calendar identified in the request. The response identifies (by namespace and name) those calendars affected by the request, that is, those whose calendar references have been modified. It also lists the updated version number of each calendar. The request must include a version number that is compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception". Required system action: writeCalendars |
SaveCalendarReferencesResponseType |
| createRecurringEntry | Creates a new recurring exclusion calendar Entry.
The request must include a version number that is compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception". Required system action: writeCalendars |
XmlCalendarEntries |
| deleteCalendar | Deletes the named calendar, and all the working day and calendar entries associated with it. The deleted calendar cannot be recovered.
The association of any calendar references to the deleted calendar will also be deleted; leaving those calendar references unfulfilled. In the request, pass the version value returned in the earlier call to retrieve the calendar (getCalendar function). If the given version value does not match the current value held in the database, a conflicting update must have occurred since the initial request to retrieve the calendar, and the delete request is rejected. The caller must call the getCalendar function (see below) again. Amendments to existing calendars will not be reflected in those deadline calculations that have already been performed. Required system action: None |
Empty response (no JSON payload) |
| deleteCalendarEntries | Deletes the calendar entries identified by the GUIDs in the request. (Note that in this context, "entries" is synonymous with "exclusions.")
The version value returned in the earlier request to retrieve the calendar exclusion (getCalendarEntries function -- see below) should be passed in this deleteCalendarEntries call. If the given version value does not match the current value held in the database, a conflicting update must have occurred since the initial request to retrieve the calendar exclusion, and the delete request is rejected. The caller must then call the getCalendarEntries function again. Amendments to existing calendar exclusions will not be reflected in those deadline calculations that have already been performed. Required system action: deleteCalendars |
Empty response (no JSON payload) |
| deleteCalendarReferences | Deletes the specified calendar references from the identified calendar.
The request must include a version number that is compared against the value held by the identified calendar entry. If the values don't match, the request fails with a "concurrency exception". |
SaveCalendarReferencesResponseType |
| getCalendar | Lists the details of a named calendar.
The response also includes a version value that is used for optimistic locking purposes. The same value should be passed in a request to save the calendar. For a base calendar, the time zone and working day entries are included in the response. No other calendar entries are included in the response. Required system action: readCalendars |
XmlCalendarResponse |
| getCalendarEntries | Lists the calendar exclusions for a given date range. (Note that in this context, "entries" is synonymous with "exclusions.")
Returns both working-day exclusions and recurring exclusions. The date and time values of the exclusions are specified and displayed as time-zone neutral. For base calendars, the time-zone identifier is included in the response. In the case of recurring exclusions, those occurrences that fall within the given date range are listed in the response. Required system action: readCalendars |
XmlCalendarEntries |
| listCalendars | Lists all known base and overlay calendars.
Required system action: readCalendars |
ListCalendarsResponseType |
| listTimeZones | Lists all the time zones recognized by the system.
These time zones are the possible values for the time-zone property of a base calendar. The calling operation may cache the response, and use the entries to allow the user to select a time zone when creating or editing a base calendar. Required system action: None |
ListTimeZonesResponseType |
| purgeCalendarEntries | Deletes all the calendar exclusions with an end date earlier than the specified to-date, for the named calendar. (Note that in this context, "entries" is synonymous with "exclusions.")
If the to-date exceeds the current date, the current date is used. The deleted exclusions cannot be recovered. If any of the exclusions fails to be deleted, no exclusions are deleted. Required system action: deleteCalendars |
Empty response (no JSON payload) |
| renameCalendar | Changes a calendar's name, namespace, or both.
The change will not succeed if another calendar already exists with the new name and namespace combination. Any references to the calendar will not be affected by the change. Required system action: writeCalendars |
Empty response (no JSON payload) |
| resolveReferences | Resolves a collection of specified calendar reference GUIDs, by returning the identifier of the calendar instance with which each reference is associated.
More than one calendar reference may be associated with the same calendar. The response contains the same list of calendar references as requested, plus the identifier of the calendar instance that each reference is associated with. If any reference is not associated with a calendar instance, it is still included in the response but no calendar is identified for that reference. Required system action: readCalendars |
ResolveReferencesResponseType |
| saveBaseCalendar | Updates the specified base calendar if it already exists, or creates it if it does not exist.
The request does not include calendar entries; they are created using the createCalendarEntry function (see above). If this function call is to update an existing base calendar, the call should include the version value returned in the earlier request to retrieve the calendar (see the getCalendar function). If the given version value does not match the current value held in the database, a conflicting update must have occurred since the initial request to retrieve the calendar, and the save request is rejected. You must then call getCalendar again to obtain the current version. If the version value shows no conflict, the base calendar is updated, and the response includes a new version value. Amendments to existing base calendars are not reflected in deadline calculations that have already been performed. Required system action: writeCalendars |
XmlCalendarResponse |
| saveOverlayCalendar | Updates the specified overlay calendar if it already exists, or creates it if it does not exist.
The request does not include calendar entries; they are created using the createCalendarEntry function (see above). If the request is one to update an existing overlay calendar, the request should include the version value returned in the earlier request to retrieve the calendar (getCalendar). If the given version value does not match the current value held in the database, a conflicting update must have occurred since the initial request to retrieve the calendar, and the save request will be rejected; The caller must then perform another getCalendar request, to obtain the current version. If the version value shows no conflict, the calendar is updated, and the response includes a new version value. Amendments to existing calendars are not reflected in deadline calculations that have already been performed. Required system action: writeCalendars |
XmlCalendarResponse |
| updateCalendarEntry | Updates an existing calendar exclusion. (Note that in this context, "entry" is synonymous with "exclusion.")
If the request is to update an existing calendar exclusion, the version value returned in the earlier request to retrieve the calendar exclusion (getCalEntries) should be passed in this function call. If the given version value does not match the current value held in the database, a conflicting update must have occurred since the initial request to retrieve the exclusion, and the update request is rejected. You must then call getCalendar again to obtain the current version. Amendments to existing calendar exclusions is not reflected in deadline calculations that have already been performed. Required system action: writeCalendars |
XmlCalendarEntries |
| updateRecurringEntry | Updates an existing recurring calendar exclusion. (Note that in this context, "entry" is synonymous with "exclusion.")
A recurring exclusion is defined using the recurrence rule expression, not as a series of individual dates and times. You cannot edit an individual occurrence of a recurring exclusion as a separate entity, so any amendments made to a recurring exclusion are applied to all occurrences of that exclusion. If the request is to update an existing calendar exclusion, the version value returned in the earlier request to retrieve the calendar exclusion (getCalEntries) should be passed in this function call. If the given version value does not match the current value held in the database, a conflicting update must have occurred since the initial request to retrieve the exclusion, and the update request is rejected. You must then call getCalendar again to obtain the current version. Amendments to existing recurring calendar exclusions is not reflected in deadline calculations that have already been performed. Required system action: writeCalendars |
XmlCalendarEntries |
Time-zone and time-slot for Base Calendars
The following provides information about setting time zones and time slots when saving a base calendar using the saveBaseCalendar function (see above).
- time-zone - Use one of the values returned by the listTimeZones function (see above). If no time zone is specified, the time zone of the BPM server is used.
- time-slot start and
end - For each
day-of-week specified in a base calendar, there can be up to five entries, each entry giving the start and end times of a working period within the specified day. Morning and afternoon separated by a meal break, for example, would be two time slots. Specify times as hh:mm.SSSTZ, where:
TIBCO strongly recommends that you specify a time zone of Z for all entries. If no time zone is specified, some APIs used by TIBCO ActiveMatrix BPM will automatically convert the value to the time zone used by the server, regardless of the calendar's time-zone specification. This may not always be the time zone required.
BPM stores time-slot start and end times as UTC, regardless of any time zone specified. However, the base calendar's time-zone value is used to adjust these times for display purposes in the client application.