Sierra locations in the Catalogue API

1. Sierra items have locations which consist of a code and a name . There are a large number of possible values of these.

2. Catalogue API items have locations which can be DigitalLocations or PhysicalLocations. This document is about physical locations.

3. Catalogue API physical locations have locationTypes which have an id and a label. These can currently take the following values:

id	label
closed-stores	Closed stores
open-shelves	Open shelves
on-exhibition	On exhibition
on-order	On order

1. We currently map Sierra item locations to the above locationTypes using the name only. We could also use the code, but we currently don't. This mapping is done by looking for case-insensitive substrings in the location names:

substring exists in name?	locationType ID
archives & mss well.coll	closed-stores
at digitisation	closed-stores
by appointment	closed-stores
closed stores	closed-stores
conservation	closed-stores
early printed books	closed-stores
iconographic collection	closed-stores
offsite	closed-stores
unrequestable	closed-stores
biographies	open-shelves
folios	open-shelves
history of medicine	open-shelves
journals	open-shelves
medical collection	open-shelves
medicine & society collection	open-shelves
open shelves	open-shelves
quick ref collection	open-shelves
quick ref. collection	open-shelves
rare materials room	open-shelves
student coll	open-shelves
exhibition	on-exhibition

Additionally:

• If the name is empty, or if it contains bound in above or contained in above, we look at the other items on the bib:

  • We find all the distinct valid locationTypes of the other items

  • If there is only one, we use that for this location too. Otherwise, we assign no locationType.

• on-order items are created slightly differently using order records and can be considered separate for the purposes of this document.

Access conditions

Locations in the catalogue API (described above) have accessConditions consisting of a method and optionally a status, plus some optional free text terms and/or a note.

Access methods can currently take the following values:

id	label
online-request	Online request
manual-request	Manual request
not-requestable	Not requestable
view-online	View online
open-shelves	Open shelves

Access statuses can take the following values:

id	Label
open	Open
open-with-advisory	Open with advisory
restricted	Restricted
by-appointment	By appointment
temporarily-unavailable	Temporarily unavailable
unavailable	Unavailable
closed	Closed
licensed-resources*	Licensed resources
permission-required	Permission required

*the internal representation of licensed resources is further specified into "resources" and "related resources" as per MARC 856 ind 2, in order to implement availability.

Availability and Restrictions

Internally, access statuses also have derived boolean properties of isAvailable and hasRestrictions. Access conditions and locations inherit these properties transitively.

• An access status is available if it is open, open-with-advisory, or is a licensed-resource that is not a related resource.

• An access status has restrictions if it is open-with-advisory, restricted, by-appointment, closed or permission-required.

Externally, these properties have the following effects:

1. Catalogue API works have availabilities, a list of any number (including none) of the following:

id	label
online	Online
closed-stores	Closed stores
open-shelves	Open shelves

• A work has an online availability if any of its items have a DigitalLocation which is available

• A work has a closed-stores availability if any of its items have a PhysicalLocation with a closed-stores location type and none of the work's notes are a terms-of-use note that implies that the work is held at another institution. Note JP 18/01/24: this seems like a hack, should we address it?

• A work has an open-shelves availability if any of its items have a PhysicalLocation with an open-shelves location type

1. Catalogue API digital location thumbnails are not populated if the location is restricted.

Determining access conditions

Access methods are determined as a function of the following properties of the item in Sierra:

• Hold count

• Status code in fixed field 88

• OPAC message code in fixed field 108

• The result of the Sierra rules for requesting (see below)

• The location type (see above)

• The presence of a due date in fixed field 65

• The notes, in any varfield with a field tag n

• The reserves notes, in any varfield with a field tag r

Rules for requesting

The "rules for requesting" live in Sierra, but are replicated in both the catalogue pipeline and the items API. They determine whether an item is requestable or not. If it is not requestable, the rules can provide a message.

Mapping Sierra data to access conditions

Note JP 19/01/2024: the rules are described here in the roughly same way that they are written in the code. My view is that the logic here has grown in a way which mixes wholly unrelated concerns and that it would be possible and desirable to rewrite this mapping in a way that would be easier to reason about. I think a "funneling" or flowchart-like approach to the mapping would be preferable to this very flat representation.

For closed-stores location types:

• If they have no holds, an available status code, an online request OPAC message, and are determined as requestable by the rules for requesting: they are accessible by the method online-request with status open.

• If they have no holds, an available status code, a restricted OPAC message, and are determined as requestable by the rules for requesting: they are accessible by the method online-request with status restricted.

• If they have no holds, an available status code, a manual request OPAC message, and are determined as not requestable with a message corresponding to "needs manual request" by the rules for requesting: they are accessible by the method manual-request. Relevant notes are copied into the notes field.

• If they have a closed status code, an unavailable OPAC message, and are determined as not requestable with a message corresponding to a closed item by the rules for requesting: they are not-requestable with status closed.

• If they have no holds, a permission required status code, a by appointment OPAC message, and are determined as not requestable with a message corresponding to "no public message" by the rules for requesting: they are accessible by the method manual-request with status by-appointment.

• If they have no holds, a permission required status code, a donor permission OPAC message, and are determined as not requestable by the rules for requesting: they are accessible by the method manual-request with status permission-required.

• If they have 1 or more holds: they are not-requestable with status temporarily-unavailable.

• If the rules for requesting determine them to be not requestable with a message corresponding to "in use by another reader": they are not-requestable with status temporarily-unavailable.

For open-shelves location types:

• If they have no holds, an available status code, an open shelves OPAC message, no due date, and are determined as not requestable with a message corresponding to "on open shelves" by the rules for requesting: they are accessible by the method open-shelves.

• If they are determined as not requestable with a message corresponding to "in use by another reader" by the rules for requesting: they are open-shelves with status temporarily-unavailable.

• If they have a due date: they are open-shelves with status temporarily-unavailable.

on-exhibition location types with a non-empty reserve notes varfield are not-requestable with the note from the reserve notes.

Finally, for all locations not yet mapped:

• If they are determined as not requestable with a message corresponding to "request top item" by the rules for requesting: they are not-requestable with a note from the message.

• If they have no location type, a closed access status, an unavailable OPAC message, and are determined as not requestable with a message corresponding to a closed item by the rules for requesting: they are not-requestable with status closed.

• If they have an unavailable status code, an unavailable OPAC message, and are determined as not requestable with a message corresponding to "item unavailable" or "at digitisation" by the rules for requesting: they are not-requestable with status temporarily-unavailable.

• If they have a missing or withdrawn status code annd are determined as not requestable with a message corresponding to "item missing" or "item withdrawn" by the rules for requesting: they are not-requestable with status unavailable.

• If any non-mapped item has a due date, it is not-requestable with status temporarily-unavailable.

• Any remaining items are not-requestable.

Requesting

Answering the question of "what makes a work requestable?" thankfully only requires knowledge of a subset of the above. This is represented by the equivalent class in the items API.

Note JP 19/01/2024: is it wise to duplicate a subset of the logic from the pipeline like this? Why are we representing rules for requesting results as Options?

An item is requestable via the items API if all of the below hold:

• It is in the closed stores

• It has an available status code

• It has no current holds

• It satisfies the rules for requesting

• It has an OPAC message for online request or restricted access

Note JP 19/01/2024: Are all of these necessary? Why don't the rules for requesting cover the status code and OPAC message?

From the perspective of API consumers, this is equivalent to an item being requestable if it:

• Has a location type of closed-stores

• Has an online-request access method

• Has an open, open-with-advisory, or restricted access status

Request dates

The items API can receive a request with a pickupDate. This is not validated (other than for correctness) against any opening times etc. It is placed in the hold note with the format "Requested for: yyyy-MM-dd".

A list of valid pickup dates is created by the frontend webapp and presented to the user by using the venue opening times.

1. We take the list of all days on which the library is open (starting the next open day if it's currently before 10am, or 2 working days later if it's after 10am) over the next 2 weeks.

2. If there are any exceptional (ie non-routine working hours) closure dates during that period, we extend the list until until the total number of available days is equivalent to a normal 2 week period.

The data for opening times comes from Prismic.

Note JP 19/01/2024: the way this data is computed is very complex. I wonder if it could be simplified. It also feels like the responsibility to provide possible pickup dates should reside in the items API, although this would require it to talk to Prismic.