Tracking v3 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. 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

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 DCB-1230: Detect and Terminate Supplier CancellationClosed

• Aug 28, 2024 Default to production interval timings

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

• DATE TBC DCB-1102 Rename NO_ITEMS_AVAILABLE_AT_ANY_AGENCY to NO_ITEMS_SELECTABLE_AT_ANY_AGENCY