foliolib.folio.api.calendar.Calendar
- class foliolib.folio.api.calendar.Calendar(tenant: str, okapi: Optional[foliolib.okapi.okapiClient.OkapiClient] = None)
Bases:
foliolib.folio.FolioApiCalendar Opening Hours API
- Parameters
tenant (str) – Tenant id
okapi (OkapiClient, optional) – Instance of OkapiClient. Defaults to None.
Methods
createcalendar(calendar)Create a new calendar from a provided body.
deletecalendar(calendarId)Delete a calendar by its ID.
deletecalendars(**kwargs)Delete a calendar by its ID.
getallopenings(servicePointId, **kwargs)Calculate the opening information for each date within a range
getcalendar(calendarId)Get a calendar's information by its ID.
getsurroundingopenings(servicePointId, **kwargs)Calculate openings nearest to a given date for a specified service point
searchcalendars(**kwargs)Get all calendars that match the given query
updatecalendar(calendarId, calendar)Overwrite an existing calendar with the provided payload.
- createcalendar(calendar)
Create a new calendar from a provided body. If an ID is provided for the calendar, it will be ignored (and a new one generated).
POST /calendar/calendars- Parameters
calendar (dict) – See Schema below.
- Returns
See Schema below.
- Return type
dict
- Raises
OkapiRequestError – Invalid request or parameters
OkapiRequestConflict – A calendar creation/update cannot be performed due to an existing assignment overlapping with the provided date range
OkapiFatalError – Internal server error
Schema
{ "description": "A single calendar", "type": "object", "properties": { "id": { "description": "A unique UUID identifying this calendar", "type": "string", "format": "uuid" }, "name": { "description": "A user-provided name used to label this calendar", "type": "string" }, "startDate": { "type": "string", "format": "date", "description": "The first effective date (inclusive, YYYY-MM-DD) of this calendar" }, "endDate": { "type": "string", "format": "date", "description": "The first effective date (inclusive, YYYY-MM-DD) of this calendar" }, "assignments": { "description": "A list of all service points that this calendar is assigned to", "type": "array", "items": { "$ref": "servicePointId.yaml" } }, "normalHours": { "description": "A list of objects describing when the calendar is normally open", "type": "array", "items": { "$ref": "normalHours.yaml" } }, "exceptions": { "description": "A list of objects describing exceptions to the normal hours", "type": "array", "items": { "$ref": "exceptionRange.yaml" } }, "metadata": { "$ref": "metadata.yaml" } }, "additionalProperties": false, "required": [ "name", "startDate", "endDate", "assignments", "normalHours", "exceptions" ], "example": { "name": "Sample Spring Calendar", "startDate": "2022-01-08", "endDate": "2022-05-09", "assignments": [ "44444444-4444-4444-4444-444444444444", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "dddddddd-dddd-dddd-dddd-dddddddddddd" ], "normalHours": [ { "startDay": "MONDAY", "startTime": "07:00:00", "endDay": "FRIDAY", "endTime": "22:00:00" }, { "startDay": "SATURDAY", "startTime": "07:00:00", "endDay": "SATURDAY", "endTime": "22:00:00" } ], "exceptions": [ { "name": "Spring break (closed)", "startDate": "2022-03-01", "endDate": "2022-03-05", "openings": [] }, { "name": "Early closure", "startDate": "2022-04-01", "endDate": "2022-04-01", "openings": [ { "startDate": "2022-04-01", "startTime": "07:00:00", "endDate": "2022-04-01", "endTime": "12:00:00" } ] } ] } }
- deletecalendar(calendarId)
Delete a calendar by its ID.
DELETE /calendar/calendars/{calendarId}- Parameters
calendarId (str) – The calendar ID to operate on. (format: uuid)
- Raises
OkapiRequestError – Invalid request or parameters
OkapiRequestNotFound – A calendar with the given UUID could not be found.
OkapiFatalError – Internal server error
- deletecalendars(**kwargs)
Delete a calendar by its ID.
DELETE /calendar/calendars- Keyword Arguments
id (list) – A list of calendars to delete, sent as separate parameters (?id=aaaa&id=bbbb…). If any calendars are missing, a 404 will be returned and nothing modified. (items: (type: string, format: uuid), minItems: 1)
- Raises
OkapiRequestError – Invalid request or parameters
OkapiRequestNotFound – A calendar with the given UUID could not be found.
OkapiFatalError – Internal server error
- getallopenings(servicePointId, **kwargs)
Calculate the opening information for each date within a range
GET /calendar/dates/{servicePointId}/all-openings- Parameters
servicePointId (str) – The service point to calculate openings on (format: uuid)
- Keyword Arguments
startDate (str) – The first date (YYYY-MM-DD) to include, inclusive (format: date)
endDate (str) – The last date (YYYY-MM-DD) to include, inclusive (format: date)
includeClosed (bool) – Whether or not the results should include days where the service point is closed. Exceptional closures will always be returned
offset (int) – Skip a certain number of the first values; used for pagination (default: 0, minimum: 0)
limit (int) – The maximum number of elements returned in the response, used for pagination. A limit of zero will not include any results (however, totalRecords will still be included) – to include all results, use a large number such as 2147483647. (default: 10, minimum: 0)
- Returns
See Schema below.
- Return type
dict
- Raises
OkapiRequestError – Invalid request or parameters
OkapiFatalError – Internal server error
Schema
{ "description": "Collection of opening information for single days", "type": "object", "properties": { "dates": { "type": "array", "description": "Each opening or date returned in the response", "items": { "$ref": "singleDayOpening.yaml" } }, "totalRecords": { "type": "integer", "minimum": 0, "description": "Number of total openings or dates available" } }, "additionalProperties": false, "required": [ "dates", "totalRecords" ], "example": { "dates": [ { "date": "2022-05-01", "allDay": false, "open": true, "exceptional": true, "exceptionName": "Holiday (reduced hours with lunch break)", "openings": [ { "startTime": "10:00:00", "endTime": "12:00:00" }, { "startTime": "13:30:00", "endTime": "17:00:00" } ] }, { "date": "2022-05-02", "allDay": true, "open": false, "exceptional": false, "openings": [] }, { "date": "2022-05-03", "allDay": true, "open": true, "exceptional": false, "openings": [ { "startTime": "00:00:00", "endTime": "23:59:00" } ] } ], "totalRecords": 3 } }
- getcalendar(calendarId)
Get a calendar’s information by its ID.
GET /calendar/calendars/{calendarId}- Parameters
calendarId (str) – The calendar ID to retrieve (format: uuid)
- Returns
See Schema below.
- Return type
dict
- Raises
OkapiRequestError – Invalid request or parameters
OkapiRequestNotFound – A calendar with the given UUID could not be found.
OkapiFatalError – Internal server error
Schema
{ "description": "A single calendar", "type": "object", "properties": { "id": { "description": "A unique UUID identifying this calendar", "type": "string", "format": "uuid" }, "name": { "description": "A user-provided name used to label this calendar", "type": "string" }, "startDate": { "type": "string", "format": "date", "description": "The first effective date (inclusive, YYYY-MM-DD) of this calendar" }, "endDate": { "type": "string", "format": "date", "description": "The first effective date (inclusive, YYYY-MM-DD) of this calendar" }, "assignments": { "description": "A list of all service points that this calendar is assigned to", "type": "array", "items": { "$ref": "servicePointId.yaml" } }, "normalHours": { "description": "A list of objects describing when the calendar is normally open", "type": "array", "items": { "$ref": "normalHours.yaml" } }, "exceptions": { "description": "A list of objects describing exceptions to the normal hours", "type": "array", "items": { "$ref": "exceptionRange.yaml" } }, "metadata": { "$ref": "metadata.yaml" } }, "additionalProperties": false, "required": [ "name", "startDate", "endDate", "assignments", "normalHours", "exceptions" ], "example": { "name": "Sample Spring Calendar", "startDate": "2022-01-08", "endDate": "2022-05-09", "assignments": [ "44444444-4444-4444-4444-444444444444", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "dddddddd-dddd-dddd-dddd-dddddddddddd" ], "normalHours": [ { "startDay": "MONDAY", "startTime": "07:00:00", "endDay": "FRIDAY", "endTime": "22:00:00" }, { "startDay": "SATURDAY", "startTime": "07:00:00", "endDay": "SATURDAY", "endTime": "22:00:00" } ], "exceptions": [ { "name": "Spring break (closed)", "startDate": "2022-03-01", "endDate": "2022-03-05", "openings": [] }, { "name": "Early closure", "startDate": "2022-04-01", "endDate": "2022-04-01", "openings": [ { "startDate": "2022-04-01", "startTime": "07:00:00", "endDate": "2022-04-01", "endTime": "12:00:00" } ] } ] } }
- getsurroundingopenings(servicePointId, **kwargs)
Calculate openings nearest to a given date for a specified service point
GET /calendar/dates/{servicePointId}/surrounding-openings- Parameters
servicePointId (str) – The service point to calculate openings on (format: uuid)
- Keyword Arguments
date (str) – The date (YYYY-MM-DD) to calculate openings around (format: date)
- Returns
See Schema below.
- Return type
dict
- Raises
OkapiRequestError – Invalid request or parameters
OkapiFatalError – Internal server error
Schema
{ "description": "Information for three dates: one before when the SP is open, one representing an opening or closure for the current date, and one after the provided date where the SP is open. If there are no openings before or after a given date, then an opening object will be returned with the date immediately following, denoting a closure.", "type": "object", "properties": { "openings": { "type": "array", "minItems": 3, "maxItems": 3, "items": { "$ref": "singleDayOpening.yaml" } } }, "required": [ "openings" ], "additionalProperties": false, "example": { "openings": [ { "date": "2022-05-01", "allDay": false, "open": true, "exceptional": true, "exceptionName": "Holiday (reduced hours with lunch break)", "openings": [ { "startTime": "10:00:00", "endTime": "12:00:00" }, { "startTime": "13:30:00", "endTime": "17:00:00" } ] }, { "date": "2022-05-02", "allDay": true, "open": false, "exceptional": false, "openings": [] }, { "date": "2022-05-03", "allDay": true, "open": true, "exceptional": false, "openings": [ { "startTime": "00:00:00", "endTime": "23:59:00" } ] } ] } }
- searchcalendars(**kwargs)
Get all calendars that match the given query
GET /calendar/calendars- Keyword Arguments
id (list) – The list of calendar IDs to retrieve, sent as separate parameters (?id=aaaa&id=bbbb…). If this list is passed, calendars must have an ID in this list in addition to any additional criteria. (items: (type: string, format: uuid))
servicePointId (list) – Filter for calendars that are assigned to a certain service point. If this parameter is excluded, all service points will be considered/included in the response. Multiple service points may be specified with form-style query expansions; in this case, calendars that are assigned to any of the provided service points will be returned. (items: (type: string, format: uuid))
startDate (str) – The first date (YYYY-MM-DD) to consider, inclusively (format: date)
endDate (str) – The last date (YYYY-MM-DD) to consider, inclusively (format: date)
offset (int) – Skip a certain number of the first values; used for pagination (default: 0, minimum: 0)
limit (int) – The maximum number of elements returned in the response, used for pagination. A limit of zero will not include any results (however, totalRecords will still be included) – to include all results, use a large number such as 2147483647. (default: 10, minimum: 0)
- Returns
See Schema below.
- Return type
dict
- Raises
OkapiRequestError – Invalid request or parameters
OkapiFatalError – Internal server error
Schema
{ "description": "Collection of calendars", "type": "object", "properties": { "calendars": { "type": "array", "description": "Each calendar returned in the response", "items": { "$ref": "calendar.yaml" } }, "totalRecords": { "type": "integer", "minimum": 0, "description": "Number of calendars in the response" } }, "additionalProperties": false, "required": [ "calendars", "totalRecords" ], "example": { "calendars": [ { "name": "Sample Spring Calendar", "startDate": "2022-01-08", "endDate": "2022-05-09", "assignments": [ "44444444-4444-4444-4444-444444444444", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "dddddddd-dddd-dddd-dddd-dddddddddddd" ], "normalHours": [ { "startDay": "MONDAY", "startTime": "07:00:00", "endDay": "FRIDAY", "endTime": "22:00:00" }, { "startDay": "SATURDAY", "startTime": "07:00:00", "endDay": "SATURDAY", "endTime": "22:00:00" } ], "exceptions": [ { "name": "Spring break (closed)", "startDate": "2022-03-01", "endDate": "2022-03-05", "openings": [] }, { "name": "Early closure", "startDate": "2022-04-01", "endDate": "2022-04-01", "openings": [ { "startDate": "2022-04-01", "startTime": "07:00:00", "endDate": "2022-04-01", "endTime": "12:00:00" } ] } ] } ], "totalRecords": 1 } }
- updatecalendar(calendarId, calendar)
Overwrite an existing calendar with the provided payload. The provided calendar must already exist (attempting to overwrite a calendar that does not yet exist will result in a 404). If the payload includes any IDs, they will be ignored, and the existing calendar ID reused.
PUT /calendar/calendars/{calendarId}- Parameters
calendarId (str) – The calendar ID to replace (format: uuid)
calendar (dict) – See Schema below.
- Returns
See Schema below.
- Return type
dict
- Raises
OkapiRequestError – Invalid request or parameters
OkapiRequestNotFound – A calendar with the given UUID could not be found.
OkapiRequestConflict – A calendar creation/update cannot be performed due to an existing assignment overlapping with the provided date range
OkapiFatalError – Internal server error
Schema
{ "description": "A single calendar", "type": "object", "properties": { "id": { "description": "A unique UUID identifying this calendar", "type": "string", "format": "uuid" }, "name": { "description": "A user-provided name used to label this calendar", "type": "string" }, "startDate": { "type": "string", "format": "date", "description": "The first effective date (inclusive, YYYY-MM-DD) of this calendar" }, "endDate": { "type": "string", "format": "date", "description": "The first effective date (inclusive, YYYY-MM-DD) of this calendar" }, "assignments": { "description": "A list of all service points that this calendar is assigned to", "type": "array", "items": { "$ref": "servicePointId.yaml" } }, "normalHours": { "description": "A list of objects describing when the calendar is normally open", "type": "array", "items": { "$ref": "normalHours.yaml" } }, "exceptions": { "description": "A list of objects describing exceptions to the normal hours", "type": "array", "items": { "$ref": "exceptionRange.yaml" } }, "metadata": { "$ref": "metadata.yaml" } }, "additionalProperties": false, "required": [ "name", "startDate", "endDate", "assignments", "normalHours", "exceptions" ], "example": { "name": "Sample Spring Calendar", "startDate": "2022-01-08", "endDate": "2022-05-09", "assignments": [ "44444444-4444-4444-4444-444444444444", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "dddddddd-dddd-dddd-dddd-dddddddddddd" ], "normalHours": [ { "startDay": "MONDAY", "startTime": "07:00:00", "endDay": "FRIDAY", "endTime": "22:00:00" }, { "startDay": "SATURDAY", "startTime": "07:00:00", "endDay": "SATURDAY", "endTime": "22:00:00" } ], "exceptions": [ { "name": "Spring break (closed)", "startDate": "2022-03-01", "endDate": "2022-03-05", "openings": [] }, { "name": "Early closure", "startDate": "2022-04-01", "endDate": "2022-04-01", "openings": [ { "startDate": "2022-04-01", "startTime": "07:00:00", "endDate": "2022-04-01", "endTime": "12:00:00" } ] } ] } }