v9.2.0

Changes included in this release

The following changes were included in this release of DCB Service.

Features

General

• Announcements: the consortium can publish notices for a library, its groups or the whole consortium (createAnnouncement, updateAnnouncement, deleteAnnouncement; GET /discovery/announcements).
• Libraries and consortia can provide support URLs for discovery services to use, alongside custom branding.

Requesting

• Implemented the ability for involved parties (libraries and consortia staff) to add notes and tags to a patron request to aid in troubleshooting.
  • Involved parties are defined as the borrowing, supplying and pickup libraries, as well as the consortium.
  • Notes are attributed to a library or consortium, not a person.
  • The UX work for this will follow in a subsequent DCB Admin and DCB Admin for Libraries release.
• Requests now flag whether staff or patrons placed them, making them easier to distinguish.
• Alma and Koha copies now state their volume and can be requested on a per-volume basis.

Adapters and OpenRS Setup

• Host LMS verification (such as during the setup of a new library) reports each Host LMS' configuration and auth profile status, and Host LMS pings can now be used to validate the DCB-LMS connection.
  • The last ping and its result are now saved on the LMS record.
• Polaris can now harvest over OAI-PMH, and we now expose a manual reconciliation sweep for such harvests.
• Host LMS verification now also checks whether the configuration DCB holds exists in the system, and checks the mapping values read from the system as well as those sent to it.
• Live availability is now supported for Koha libraries.
• Added the framework for Koha DCB mappings.

Fixes

Tracking and cancellation

• One failed item read no longer turns a collected item into a cancellation.
• A MISSING item needs no fresh read before a cancel-while-out request is parked.
• A value the supplier's system does not report is no longer recorded as a change.
• When a supplier's item has gone, the request says so instead of reporting an error.
• A failed patron validation is audited once, and a failed supplier hold cancel is audited as a cancel.

Requesting

A borrower hold that times out keeps the supplier hold; one that cannot be placed cancels it, and the supplier hold's status is recorded after cancelling. (DCB-2050)

• A supplier item's hold count is read under its bib, an unknown hold count is no longer read as zero.
• A failed patron validation is audited once, and a failed supplier hold cancel is audited as a cancel.
• A value the supplier's system does not report is no longer recorded as a change, instead of flooding the audit log [DCB-WHATEVER]

Insights

• The most requested titles are now listed in the correct order in Insights.
• Collection analysis in Insights now handles cluster records where is_deleted is null correctly.

OpenRS Setup

• A brand image that is still in use by a library or consortium can no longer be deleted.
• The "New Library" setup now sends the correct data change log reason.

Adapters and integrations - General

• A Host LMS ping failure no longer loops on a cycle in its cause chain.
• A Host LMS is explicitly not a shared system unless it says so, including when its setting cannot be read.
• One misconfigured Host LMS no longer fails the info endpoint.

Adapters and integrations - FOLIO

• A PIN FOLIO rejects is now a failed sign-in, when before it was raised as an error.

Adapters and integrations - Polaris

• A refused Polaris staff authentication is not cached.
• Invalid Polaris shelf locations are now tolerated

Adapters and integrations - Koha

• Koha: api-url keeps its path prefix; /api names the API root; a list Koha does not have reads as empty.

Adapters and integrations - Sierra

• Sierra: exhausted read timeouts raise an alarm.

Adapters and integrations - OpenRS Appliance

• An OpenRS Appliance library's patron type is now mapped to a canonical patron type in DCB.

Adapters and integrations - Alma

Patron sign-in and lookup

• Patrons are authenticated with Alma's documented authentication operation.
• A PIN is checked against the patron's PIN number, not their password.
• An auth profile the client can't verify is refused, and is reported as a configuration error the same way FOLIO reports it.
• An identifier Alma doesn't know finds no patron.
• Alma barcode identifiers are reported as patron barcodes.
• Patrons with an active Alma block are marked blocked.
• Changing a patron's group keeps the rest of the Alma user record.

Holds and requests

• An existing Alma hold is adopted instead of placing a duplicate, but only the hold DCB placed for this request.
• A circulation action Alma applied without answering is accepted, and the holding is found.
• A refused supplier hold says why, and the mappings that exist are checked.
• A request or item that has gone is reported as gone, and hold counts are no longer guessed. An unread hold count shows as 0.
• Alma user request statuses are mapped when tracking holds.
• A configurable cancellation reason is sent without notifying the patron.

Virtual records

• A barcode clash is named before the virtual item is created.
• When the virtual item can't be created, the new holding is deleted.
• A virtual bib is deleted only while it's still the one DCB made, and virtual bibs from before notes were added are deleted too.
• The virtual bib's control number and timestamp are left to Alma.
• Virtual bib title and author are escaped, and placeholder catalogue fields are dropped.
• A virtual item isn't shelved on the lender's transit, and pickup cleanup cancels the hold first.

Items, loans and renewals

• The item's process type is read, so a loaned copy shows as checked out.
• Due dates come from the loan, not the holding.
• Renewal finds the patron's loan beyond the first page.
• Renewal notes are no longer written onto the library's own item.
• The item states the client can act on are stated explicitly.

Availability and load

• Availability pages through every item on a bib.
• Alma calls are bounded per bib, and items that can't be mapped are reported.

Robustness and privacy

• Identifiers are encoded as single path segments in Alma API paths.
• The settings the Alma client reads are declared and validated.
• Request headers and bodies are kept out of Alma error details.
• Alma user records and patron identifiers are no longer logged.

Search index

• An unmapped location is no longer indexed as the text "null.".
• Errors changing the refresh setting are handled by both search backends.

Improvements

General

• Logs have been reviewed to ensure patron barcodes and other PII cannot be logged.
• Catalogue metrics are counted in two grouped scans, shared for five minutes.
• A barcode lookup reports whether the system can see DCB's virtual items.
• We now delete libraries before agencies during tests
• Refactor IDP provisioning to use typed config
• Remove hardcoded responses from Sierra patron API tests
• Remove redundant mock in patron auth API tests
• Added the ability to show ingest details for specific chosen libraries or groups without needing to scan the whole consortium.

OpenRS Setup

• Sensible defaults applied throughout to reduce the amount of configuration users need to input when setting up a new library.
• Streamlined adapter config, making it clearer to see what is required and what is not.
• A Host LMS's configuration is validated only when it changes, and a missing configuration error names its Host LMS.
• Default environment variables are announced. DCB logs at startup when it uses the default preflight timeout, which trusted discovery services it loaded, and whether the access bar is off or in which mode.
• Each adapter publishes the defaults it applies.

OpenRS Appliance

• OpenRS Appliance location lookups are bounded.

Insights

• Collection figures come from one shared pass, and Postgres cancels a pass that runs past DCB_INSIGHTS_COLLECTION_ANALYSIS_STATEMENT_TIMEOUT (10 minutes).

Live availability and the availability check job.

• The availability job: concurrency is capped, location-mapping writes are bounded (3 at a time), stale counts are reconciled, and rechecks are less frequent: a mapped location after 60 days (was 30), an unmapped one after 14 (was 7).
• An experimental batch live availability endpoint is now available and (GET /items/availability/batch, new) asks about at most 25 clusters, 4 at a time.

Requesting

• A refusal names the requestor's agency, or failing that its home library, and the context sits beside the summary.
• Resolution checks the pickup system too when it differs from the borrowing system, and keeps excluded items and availability errors when it chooses a copy. When it chooses nothing, the request says why.
• Each adapter publishes the defaults it applies.

Alma adapter

• Patrons are authenticated with Alma's documented operation, and a PIN is checked against the patron's PIN number.
• If a request times out, but DCB still places a hold, DCB now checks for said hold on the re-try and if it's present, adopts it instead of placing a duplicate.
• DCB asks Alma why it refused a hold, and staff can ask the same.
• Renewal is denied on the virtual item, with a warning to staff where it cannot be.
• Supplier holds can go to a sharing desk; a patron's library is resolved from their campus code; virtual patron barcodes can carry a prefix.
• Calls are bounded per bib, and patrons with an active Alma block are marked blocked.

Polaris adapter

• The Polaris adapter bounds item availability bursts.
• Reporting of Polaris errors is improved, including for virtual item barcode conflicts

Behaviour changes

• Requests that would fail after placement are refused at placement, with a reason a patron can read. This will be further extended in future releases of DCB Service.
• A misconfigured supplier can now be skipped when supplier preflight is switched on.
• Consortial loan limits now apply to the agency DCB resolves from the patron's home library, for every client. This removes the dependency on discovery services to supply this information: it is still recommended that they do so.
• A copy already promised to a borrowing system is not chosen for it again until the earlier request is finalised.
• Manually skipping a supplier is refused once the item has shipped, or if the named supplier request is no longer the active one.
• Manual cleanup is now limited to the caller's library and properly reports its status, fixing an issue where cleanup could incorrectly report as done.
• Walk-up requesting will now refuse an item another request in flight already holds, with checks that library staff can act on.
• Koha: a bib with 942$n set is suppressed at the next harvest, as Koha's own catalogue suppresses it.
  -Duplicate-request check (off by default). It refuses a patron's second active request for a title, compares volumes, lets a chosen copy and a volume request through, and refuses a chosen copy the patron already has coming.
  • An optional …ACTIVE_WINDOW makes it less strict.
  • Requests placed by staff are never refused
• Availability counts are rechecked half as often, by default.
• The following are refused at placement instead of causing an error: a copy already promised to the borrowing system, a copy another walk-up request already holds, a patron over a consortial limit, and a patron over their local hold limit, with a reason and a patron-facing message.
  • Local hold limits only need to be set where DCB cannot get that information OR where the ILS does not automatically block a patron on reaching said limit. So far we have only observed this on Sierra.
• Placement checks are bounded by DCB_REQUESTS_PREFLIGHT_CHECKS_TIMEOUT (55 s by default). A placement still checking Preflight checks when it runs out is refused with PREFLIGHT_CHECKS_TIMED_OUT, and nothing is saved. Each placement logs one line, in ms, and the dcb.preflight.duration metric records it.
• Request limits fail closed. A limit that cannot be read refuses the request with REQUEST_LIMITS_UNCHECKED.
• The placed_by_staff migration marks earlier staff requests where it can tell (by using the description).

Known limitations

• Ingest status checks during library setup are bound to 20s. Some systems take longer to harvest one page, and therefore users may see "Ingest Check Failed" when setting up libraries using these systems. The remedy in this case is to monitor the "bib records" page for this library in DCB Admin to see if records are coming in.
• A supplier's request policy can still send a request to ERROR.
  • For example, when a FOLIO supplier's circulation rules refuse the request DCB places for its patron group, the request goes to ERROR instead of trying another library, for example with REQUEST_NOT_ALLOWED_FOR_PATRON_ITEM_COMBINATION.
  • This most often happens when a second patron requests a single copy another request has already paged.
  • The supplier preflight checks only the supplier's own setup, not its policies: this will be extended in future versions of DCB Service.
  • For now, these errors should be fixed in the supplier's circulation rules for the DCB patron groups.