DCB Circulation Lifecycle Events

References

Original Writeup: Slack
Workflow Diagram: Miro
Parking Lot: Discussion and Questions

1 Main Success Flow
2 Workflow Diagram

Main Success Flow

Preconditions and Assumptions

The request workflow event triggers and actions that DCB listens for and reacts to are described below in a given. when, then style. The given is the same basic setup for each:

GIVEN that a patron request has been placed in DCB 
AND already been through some transitions.

Assumed as a final when for each is that actions occur also:

WHEN DCB finds out about the event

DCB Circulation Workflow Principles

DCB cares about the circulation status of items over the status of the request

1. Dispatched by Lending Agency

WHEN a librarian at the lending agency *checks in* a DCB paged item
 (which also fulfils the request at the lending agency)
 AND which changes the item status at the lending agency to 
   Sierra: IN-TRANSIT
   Polaris: TRANSFERRED
   FOLIO: ?? 
THEN the status of the patron request (DCB) should change
 to PICKUP_TRANSIT
AND the status of the request at the borrowing agency should change 
  to (the local equivalent of) IN TRANSIT, ie,
   Sierra: IN-TRANSIT
   Polaris: TRANSFERRED
   FOLIO: ??

Technical Notes

Triggering Event: item request at the lending library has been “checked in” and the item is put in a state of “in-transit”.
The ILS status for “in-transit”:

ILS	item has been put “in-transit” source: field: value	Reference

ILS

item has been put “in-transit”
source: field: value

Reference

Sierra

item status:t

staff message: in-transit

API calls

Get an item record by record id

or, for a group of items:

Get a list of item records

User documentation:

Sierra checking in items

Checking in an item that can satisfy a hold

Managing in-transit items

Placing an hold on an item that is not checked out

Polaris

Item status: Transferred

API calls

User documentation:

Polaris Patron Services Admin Guide v7.4 pp203-205

Note: In-transit (between branches within same library/agency) is not the item status field value to trigger circulation change on

FOLIO

Item status: In Transit

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

Updating DCB Status changes:

DCB	field(s)	value(s)

DCB	field(s)	value(s)
request status		`PICKUP_TRANSIT`
???

Updating borrowing agency request

ILS	“in transit” source: field: value(s)	Reference

ILS

“in transit”
source: field: value(s)

Reference

Sierra

Item status: t

message: string

barcode: string

API calls

Update an item record

User Documentation:

Managing in-transit items

Polaris

Item status: Transferred

Polaris Patron Services Admin Guide v7.4 pp203-205

FOLIO

Request status: In Transit

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

locally equivalent of “in transit”
??? barcode
ILS specific fields
- Sierra: ???
- Polaris: ???
- FOLIO:
  - destination (service point) on item
    - this is additional pickup location to the destination initially set when placing the request
  - status of request and item (TBD)
  - ???

@Tim Auger to document authoritative triggering statuses (inferred or explicit) for each ILS, providing links to related technical resources

@Ian Ibbotson (Use this one) to confirm updates to additional field (beyond request status), eg, timestamps, statistics, 3rd party system data expected (eg, by LOCATE)

Variations / Exceptions to Consider

What happens if the status is wrong?
What is the exceptional (unrecognised) state and response?

2. Received at Borrowing Agency

Out of scope for initial implementation of Sierra and Polaris circulation flow

DCB cares more specifically that the item is received at the pickup location at the borrowing agency, ie, the hold shelf, rather than internal transit locations.

Technical Notes

Triggering Event: “has been received at the pickup location” at the borrowing agency
- pickup location should be the same as destination location set when updating request status to IN TRANSIT
- the pickup location is assumed rather than verified by DCB when the status is reacted
- being received at the pickup location is a reliable proxy for being placed on the hold shelf and ready to be collected by a borrowing patron
The ILS status for “item has been on hold shelf pickup location” is:

ILS	“item has been put on hold shelf” source: field: value	Reference

ILS

“item has been put on hold shelf”
source: field: value

Reference

Sierra

item status field: !

API calls

Get an item record by record id

or, for a group of items:

Get a list of item records

User documentation:

Checking in an item that can satisfy a hold

Cancelling items on the holdshelf

Polaris

item status field: Held

Polaris Patron Services Admin Guide v7.4 pp203-205

FOLIO

request status: Awaiting pickup

https://docs.folio.org/docs/access/check-in/checkin/#checking-in-an-item

Updating DCB Status changes:

DCB	field(s)	value(s)

DCB	field(s)	value(s)
request status		`RECEIVED AT BORROWING / PICKUP AGENCY`
???

Updating request at lending agency

ILS	“item has been put on hold shelf” at borrowing agency source: field: value	Reference

ILS

“item has been put on hold shelf” at borrowing agency
source: field: value

Reference

Sierra

item status: #

Delete m-tagged varfield(s) of “In-Transit” type

API

Update an item record

User documentation:

Polaris

item status: Held

Polaris Patron Services Admin Guide v7.4 pp203-205

FOLIO

request status: Awaiting pickup

Other Notes

When setting the borrowing agency request status to IN TRANSIT, the destination location may not be different to the pickup location set at this transition

@Tim Auger to check on the need for waystations for MOBIUS - Confirmed OUT OF SCOPE

3. Item Checked Out to Patron at Borrowing Agency

Technical Notes

Triggering Event:
- The ILS status for “item has been checked out at borrowing agency” is:

ILS	“has been checked out at borrowing agency” source: field: value	Reference

ILS

“has been checked out at borrowing agency”
source: field: value

Reference

Sierra

item status: -

AND

duedate is set to a date in ISO 8601 format

API calls

Get checkout data by item record ID

or, for a group of checkouts:

Get checkout item data

User documentation:

Checking out items

how Sierra updates records upon checkout

Polaris

Item status field: OUT

Polaris Patron Services Admin Guide v7.4 pp203-205

FOLIO

Item status: Checked out

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

Updating DCB Patron Request Status:

DCB	field(s)	value(s)

DCB	field(s)	value(s)
request status		`LOADED`
???

Updating request at lending agency

ILS	“has been checked out at lending agency” source: field: value	Reference

ILS

“has been checked out at lending agency”
source: field: value

Reference

Sierra

assign the value of date due in ISO 8601 format from the borrowing agency duedate field to the lending agency duedate field

AND

item status: -

AND

Delete corresponding item-level hold

API calls

Update an item record

User documentation:

Checking out items

how Sierra updates records upon checkout

Polaris

Item status: OUT

*tim to check the values required to generate a checkout

Polaris Patron Services Admin Guide v7.4 pp203-205

ItemCheckedoutPost method

FOLIO

Item status: Checked out

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

4. Item Returned by Borrowing Patron

Technical Notes

Triggering Event: “item has been checked back in” at the borrowing agency
- item status being changed to available is the proxy for being checked back in
The ILS status for “item has been checked back in” is:

ILS	“has been checked back in at the borrowing agency” source: field: value	Reference

ILS

“has been checked back in at the borrowing agency”
source: field: value

Reference

Sierra

item status: t

message: string

API calls

Get an item record by record id

or, for a group of items:

Get a list of item records

User documentation:

Checking in an item that can satisfy a hold

Cancelling items on the holdshelf

Polaris

item status: In-Transit

FOLIO

Clears due date and puts into transit to lending agency.

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

Updating DCB patron request

DCB	field(s)	value(s)

DCB	field(s)	value(s)
request status		`RETURN_TRANSIT`
???

Updating request at lending agency

ILS	“in transit” source: field: value(s)	Reference

ILS

“in transit”
source: field: value(s)

Reference

Sierra

t in the item record status field

API calls

Get checkout data by item record ID

or, for a group of checkouts:

Get checkout item data

Polaris

Item status: In-Transit

FOLIO

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

Other Notes

5. Received Back at Lending Agency

Clean up and removal of requests and virtual records is out of scope for initial implementation of Sierra and Polaris

Technical Notes

Triggering Event: “item has been received back at lending agency”
- the item at the lending agency being in the available status is a reliable proxy for being received back at the lending agency
The ILS status for “item has been received back at lending agency” is

ILS	“item has been received back at lending agency” source: field: value	Reference

ILS

“item has been received back at lending agency”
source: field: value

Reference

Sierra

duedate is set to null

in transit message is removed

API

Get an item by record ID

or, for a group of items

Get a list of i

Polaris

Polaris sets item status field to IN

Item status: In

triggers the removal of virtual records

FOLIO

https://docs.folio.org/docs/platform-essentials/item-status/itemstatus/

Updating DCB patron request

DCB	field(s)	value(s)

DCB	field(s)	value(s)
request status		`COMPLETED`

Updating request and virtual records at lending agency

ILS	clean up source: field: value(s)	Reference

ILS	clean up source: field: value(s)	Reference
Sierra	virtual patron is removed IFF no other open DCB transactions for that virtual patron exist.
Polaris	virtual patron is removed IFF no other open DCB transactions for that virtual patron exist.
FOLIO	virtual patron is removed IFF no other open DCB transactions for that virtual patron exist.

Updating request and virtual records at borrowing agency

ILS	clean up source: field: value(s)	Reference

ILS	clean up source: field: value(s)	Reference
Sierra	virtual item and bib are removed IFF no other open DCB transactions for a different patron from the same borrowing agency exists.
Polaris	virtual item and bib are removed IFF no other open DCB transactions for a different patron from the same borrowing agency exists.
FOLIO	virtual item and bib are removed IFF no other open DCB transactions for a different patron from the same borrowing agency exists.

Other Notes

@Tim Auger to determine clean up policy for virtual requests and virtual records at lending or borrowing agency systems (eg, is it safe to do this at the point of item being received back at lending agency?)

Workflow Diagram

Source: Miro