A basic utility to retrieve a library's hours of service the from Ex Libris Alma /open-hours
API endpoint; then convert this data into an array of UNIX timestamps which can be used to update the host's website CMS calendar.
Developer information regarding the /open-hours
API endpoint can be found @ https://developers.exlibrisgroup.com/alma/apis/docs/conf/R0VUIC9hbG1hd3MvdjEvY29uZi9saWJyYXJpZXMve2xpYnJhcnlDb2RlfS9vcGVuLWhvdXJz/.
The following variables can be set in alma-open-hours.config.php
:
-
$ALMA_API_BASEURL
= (string) Base API URL of your Alma instance. (e.g.https://api-ca.hosted.exlibrisgroup.com/almaws/v1/conf/libraries/
) -
$ALMA_API_KEY
= (string) Your Alma API key. -
$ALMA_API_LIBRARY_ID
= (string) Your library ID within Alma. This is probably a short ALL-CAPS abbreviation of your library's name.
-
date_default_timezone_set('local_timezone')
= (string, default "UTC") Your local timezone. Refer to PHP's documentation for more information about this function. -
$ALMA_API_QUERY_DAYS
= (integer, range 1-28, default 28) Number of days into the future for which you would like to retrieve data. -
$ALMA_API_QUERY_DAYS_MULTIPLE
= (integer, range 1-13, default 1) Number of times to execute the query operation. Setting this value greater than 1 allows you to retrieve more than 28 days of data; to a maximum of 364 days. -
$DATE_TIME_FORMAT
= (string, default "Y-m-d H:i") Friendly format of date/time values contained in the'open_dt'
and'close_dt'
keys of the final$hours
array. -
$TEST
= (boolean, default true) Enable testing mode where the Alma API is polled and data is prepared, but the contents ofalma-open-hours.cms_import.php
are not executed; therefore, your CMS database is not changed. Note: Turning on test mode also turns on data-dump mode, below. -
$DUMP
= (boolean, default true) Enable data-dump mode. Outputs the API query URL(s), raw JSON, prepared array of hours, and statuses of each step in the data process.
To minimize the frequency of API queries, raw JSON is cached in a subdirectory of this utility that is (not suprisingly) named ./cache
. If you wish to use caching, please ensure that this directory can be read from and written to by your web server. Cache files will be named yyyy-mm-dd.json
where each file corresponds to the first date of a given /open-hours
API call.
Do it yourself! :)
Seriously though, you'll need to write your own CMS/database import code and place it in alma-open-hours.cms_import.php
.
Prepared data is stored in the $hours
variable. If you run the open-hours utility in a web browser with the $TEST
and $DUMP
configuration variables set to true
, you'll see a 2-dimensional associative array that looks something like this:
[2023-04-28] => Array
(
[date] => 2023-04-28
[is_closed] => 0
[has_exceptions] => 0
[open_ts] => 1682679600
[close_ts] => 1682712000
[open_dt] => 2023-04-28 08:00
[close_dt] => 2023-04-28 17:00
)
[2023-04-29] => Array
(
[date] => 2023-04-29
[is_closed] => 1
[has_exceptions] => 0
[open_ts] => 1682737200
[close_ts] => 1682823599
[open_dt] => 2023-04-29 00:00
[close_dt] => 2023-04-29 23:59
)
Each array element of $hours
is keyed to a basic ISO-formatted date which corresponds to the calendar date for a given range of open (and closed) hours. Further, stored within each element of $hours
is a child array which, itself, contains an assortment of potentially useful data elements for populating your own CMS database.
$hours['yyyy-mm-dd']
= (array)['date']
= (date, format "yyyy-mm-dd")['is_closed']
= (integer, range 0-1) Numeric boolean representation of whether the library is closed (1
) or open (0
) on this date.['has_exceptions']
= (integer, range 0+) If this date's open hours are comprised of a regular open/close time as well exceptions thereto, the value indicates how many time exceptions were set in Alma.['open_ts']
= (UNIX timestamp) Opening time retrieved from the API query. Note: If['is_closed']
is1
, then the "opening" time defaults to00:00:00
(on['date']
).['close_ts']
= (UNIX timestamp) Closing time retrieved from the API query. Note: If['is_closed']
is1
, then the "closing" time defaults to23:59:59
(on['date']
).['open_dt']
= (datetime, format per config$DATE_TIME_FORMAT
) Human-readable version of['open_dt']
.['close_dt']
= (datetime, format per config$DATE_TIME_FORMAT
) Human-readable version of['close_dt']
.
This utility is licensed under the GNU Public License (GPL) version 3. Refer to LICENSE.md
for the complete text.
This utility's PHP source code is hosted on GitHub @ https://github.com/Acadia-University-Library/alma-open-hours.
Copyright (C) 2023 Vaughan Memorial Library, Acadia University