# Class: WorkCalService

## tibco.objectapi.service.WorkCalService

#### new WorkCalService()

### Methods

#### copyCalendar(request, callback)

Copies an identified calendar to create a new calendar of the same type. For Base Calendars, the properties to be copied from the original calendar will include the time-zone and working hours. All future calendar entries can also be copied, if requested.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.CopyCalendarRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlUpdatedCalendar`.

#### createCalendarEntry(request, callback)

Creates a new working day exclusion calendar entry. Date and time values in the request are expected to be time-zone neutral.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

The response includes the saved calendar entry.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.CreateCalendarEntryRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlCalendarEntries`.

#### createCalendarReferences(request, callback)

Associates a calendar with a client component's reference identifier. A reference can refer to only one calendar, but a calendar can be referenced by any number of client references.

A calendar Reference is an external reference to a calendar instance held within the Calendar Component. References simply consist of a unique identifier (a GUID), that can be associated with any one of the Calendars held within the Calendar Component. The same calendar instance can be associated with any number of calendar References.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.CreateCalendarReferencesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `SaveCalendarReferencesResponseType`.

#### createRecurringEntry(request, callback)

Creates a new recurring exclusion calendar entry. Date and time values in the request are expected to be time-zone neutral.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

The response will include the saved calendar entry, and the instances that occur within the given response start and end date-time.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.CreateRecurringEntryRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlCalendarEntries`.

#### deleteCalendar(request, callback)

Deletes the named calendar, and all the working day and calendar entries associated with it. The deleted calendar cannot be recovered.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.DeleteCalendarRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `NoContentResponse`.

#### deleteCalendarEntries(request, callback)

Deletes working day exclusions or recurring exclusions, identified by their GUID. The deleted entries cannot be recovered.

If any of the entries fails to be deleted, non of the listed entries will be deleted.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.DeleteCalendarEntriesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `NoContentResponse`.

#### deleteCalendarReferences(request, callback)

Deletes the given calendar references from the identified calendar.

A calendar reference is an external reference to a calendar instance held within the Calendar component. References simply consist of a unique identifier (a GUID), that can be associated with any one of the Calendars held within the Calendar Component. The same calendar instance can be associated with any number of calendar references.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.DeleteCalendarReferencesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `SaveCalendarReferencesResponseType`.

#### getCalendar(request, callback)

Returns the details of a named calendar. For a base calendar, the time-zone and working day entries are included.

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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.GetCalendarRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlCalendarResponse`.

#### getCalendarEntries(request, callback)

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 (for information about the exclusion types, the see saveCalendarEntry function). 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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.GetCalendarEntriesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlCalendarEntries`.

#### listCalendars(request, callback)

Returns the list of known calendar instances (that is, Base and Overlay Calendars). If there are no calendar instances, the result is an empty list.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.ListCalendarsRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `ListCalendarsResponseType`.

#### listTimeZones(request, callback)

Returns the list of time-zone identifiers recognised by the Calendar component. The entries in the returned list are 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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.ListTimeZonesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `ListTimeZonesResponseType`.

#### purgeCalendarEntries(request, callback)

Deletes all 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 any of the entries fails to be deleted, no entries are deleted.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.PurgeCalendarEntriesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `NoContentResponse`.

#### renameCalendar(request, callback)

Changes the name, and/or namespace, of a calendar. The change will not succeed if no calendar already exists with the new name and namespace combination.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.RenameCalendarRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `NoContentResponse`.

#### resolveReferences(request, callback)

Resolves a given collection of calendar references, by returning the identifier of the calendar instance to which each reference is associated.

A calendar reference is an external reference to a calendar instance held within the Calendar Component. References simply consist of a unique identifier (a GUID), that can be associated with any one of the Calendars held within the Calendar Component. The same calendar instance can be associated with any number of calendar references.

The response will consist of the same calendar references as the request, but with the identifier of the calendar instance they are associated with.

If a given reference is not associated with a calendar instance, it will still be included but no calendar will be identified for that reference.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.ResolveReferencesRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `ResolveReferencesResponseType`.

#### saveBaseCalendar(request, callback)

Updates the specified base calendar if it already exists, or creates it if it does not exist.

Note that calendar Entries are not included in the request. Calendar Entries can be created using the saveCalendarEntry function.

Date and time values in the request are stored as UTC. However it is best practice to specify a timezone of UTC for each time entered, to prevent any misinterpretation that might result from the different timezones of the client and server.

If the request is one to update an existing base 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 curent version.

If the version value shows no conflict, the calendar is updated, and the response includes a new version value.

Amendments to existing calendars will not be reflected in those deadline calculations that have already been performed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.SaveBaseCalendarRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlBaseCalendar`.

#### saveOverlayCalendar(request, callback)

Updates the specified overlay calendar if it already exists, or creates it if it does not exist.

Note that calendar entries are not included in the request. Calendar entries can be created using the saveCalendarEntry function.

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 will not be reflected in those deadline calculations that have already been performed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.SaveOverlayCalendarRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlOverlayCalendar`.

#### updateCalendarEntry(request, callback)

Updates an existing working day exclusion calendar entry. Date and time values in the request are expected to be time-zone neutral.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

The response will include the saved calendar entry.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.UpdateCalendarEntryRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlCalendarEntries`.

#### updateRecurringEntry(request, callback)

Updates an existing recurring exclusion calendar entry. Date and time values in the request are expected to be time-zone neutral.

The request must include a version number that will be compared against the value held by the identified calendar entry. If the values don't match, the request will fail with a "concurrency exception".

The response will include the saved calendar entry, and the instances that occur within the given response start and end date-time.

##### Parameters:

Name | Type | Description
--- | --- | ---
`request` | tibco.objectapi.service.request.UpdateRecurringEntryRequest | A request set with data for this service call.
`callback` | tibco.objectapi.service.Callback | A callback to handle the service response of type `XmlCalendarEntries`.