Tracking v4 matrix

Overview

When a patron places a Direct Consortial Borrowing request it goes through some initial [[preflight checks]] to make sure there isn’t anything immediately fatal that will prevent the request from being fulfillled.

If those checks are passed, the request is not accepted by DCB and the patron’s requesting system is notified so that the patron can be informed.

Once those checks are received, the request is stored with DCB and then goes through a largely deterministic sequence:

1. Preliminary States - ensure we have good data to propagate requests in downstream systems

   1. SUBMITTED_TO_DCB

   2. PATRON_VERIFIED

   3. RESOLVED

2. Circulation Tracking - to track and synchronise downstream systems

   1. REQUEST_PLACED_AT_SUPPLYING_AGENCY

   2. CONFIRMED

   3. REQUEST_PLACED_AT_BORROWING_AGENCY

   4. PICKUP_TRANSIT

   5. RECEIVED_AT_PICKUP

   6. READY_FOR_PICKUP

   7. LOANED

   8. RETURN_TRANSIT

3. Finishing States - to terminate and clean up traces of finished requests where possible

   1. Preliminary Finishing

      1. NOT_SUPPLIED_CURRENT_SUPPLIER

      2. Aged to lost → if detected, update supplier and then finalized

      3. Declared lost → if detected, update supplier and then finalized

      4. Lost and paid → if detected, update supplier and then finalized

      5. Claims returned →

      6. NO_ITEMS_AVAILABLE_AT_ANY_AGENCY → NO_ITEMS_SELECTABLE_AT_ANY_AGENCY

   2. Circulation Finishing

      1. CANCELLED

   3. Happy Path Finishing

      1. COMPLETED

      2. FINALISED

   4. Unexpected Termination

      1. ERROR

Preliminary States

The initial sequence of states that a request goes through to verify a patron’s identity and resolve to an selectable item.

• Until it completes this deterministic sequence, the request only exists in DCB and not in downstream systems.

• There is no polling in these states.

Circulation States

When a request has gone through preliminary verification and resolution states DCB attempts to place, update and track its progress in downstream systems.

• Once the initial circulation state is entered, polling is triggered to handle state transitions based on the criteria defined

• A request is expected to transition through each state in the given circulation sequence

  • this is the “happy path”

• In rare scenarios, DCB may not always pick up all state transitions, depending on downstream system processing and polling intervals

  • in this case the request is flagged as out of sequence

  • this is not always fatal for a request - and they are often picked up again when they are in RETURN TRANSIT, the loan to patron having been skipped by DCB

Finishing States

When a request completes its cycle, or if it terminates prematurely, it enters a finishing state.

• In most cases this indicates the end of the request, resulting in a finishing sequence

  • in the future, NOT_SUPPLIED_CURRENT_SUPPLIER will trigger a re-request

• The finishing sequence may or may not involve clean up of virtual records, depending on whether the request

Explanatory Notes

• Max backoff / Next Poll interval / Next Step (see table below)

  • None: no downstream polling will happen

  • Time: add time period to now to calculate “Check Due Time” (not called that in code) when the next check should happen

• Polling interval : (configured at an environment level in dcb-service config):

  • indicates how often to trigger a polling cycle generally, and then within each cycle, only check those items with states that have passed a Check Due Time

• Force check update: check now regardless of Check Due Time

Polling Durations

8.24.0-SNAPSHOT (28th April 2025) has changed the mechanism for controlling the polling intervals in each of the different states. Previously, a global system setting called CIRCULATION_TRACKING_PROFILE_KEY created different profiles (DEV, TEST, PROD) that had coarse grained impact over all settings. This does not give sufficient control to hosting environments. Therefore, this release replaces that mechanism with explicit configuration for each state. Looking to application.yaml we can now see the keys

These are the default durations now set. Individual states can be modified either by providing alternate yaml and/or by setting the environment variables DCB_POLLING_DURATIONS_SUBMITTED_TO_DCB=”1h”. Variables will take precedence over additional yaml, which itself has priority over the default application.yaml settings set out here.

The null entries in this list are important as they indicate that requests are in a terminal or paused state and should not be tracked. Setting durations for these states will cause extra and unnecessary(normally) load.

Changes

• May 8, 2024 change the dev duration of tracking for REQUEST_PLACED_AT_SUPPLYING_A… · openlibraryenvironment/dcb-service@fd9aa6e

  • Reduced from 60s to 10ms rather than as 0s appears to be treated as effectively terminating.

• Jun 20, 2024 https://openlibraryfoundation.atlassian.net/browse/DCB-1243

• Jul 19, 2024 DCB-1289 Generalise transition to FINALISE and apply to CANCELLED to extend cleanup

• Jul 23, 2024 https://openlibraryfoundation.atlassian.net/browse/DCB-1230

• Aug 28, 2024 Default to production interval timings

• Sep 18, 2024 Roll backhttps://openlibraryfoundation.atlassian.net/browse/DCB-1517

• Oct 23, 2024 DCB-1102 Rename NO_ITEMS_AVAILABLE_AT_ANY_AGENCY to NO_ITEMS_SELECTABLE_AT_ANY_AGENCY

• DATE TBC DCB-1786 Add supplier renewal