Patron hold flow (Borrowing flow)

When item is provided by another lending library to FOLIO via Inn-reach - the patron hold transaction should be created. This page includes steps made from FOLIO UI and API calls sent to emulate the lending library response.

API documentation - INN-Reach Circulation API (please refer to endpoints mentioned below)

Note: the mentioned API calls on this page contain only example data to show the format these values are usually passed, for real calls please populate all passed fields with your relevant data.

The paths for these calls are also described for usage of mod-inn-reach, if you are testing via EDGE inn-reach, please replace these values:

• usual kong-URL with edge-URL of environment

• “/inn-reach/d2ir/” with “/innreach/v2/” in path

• “X-D2IR-Authorization” header name to “Authorization”

Also, to access the inn-reach module via edge, the following call should be sent to obtain a temporary token:

Method: PUT

To: {{host}}/innreach/v2/oauth2/token?grant_type=client_credentials&scope=innreach_tp

Use these headers:

• X-To-Code - FOLIO library code (e.g. fli01)

• X-From-Code - Inn-reach server code (e.g. d2irm)

• Authorization - Basic NDRkNWNkMzMtMTY3Ni00NWE1LWEwNDAtYTU4ZmU5ZTA5YjRlOmIyYmYzNTg2LTUxMWEtNDZjOS05YzUwLTY2NDRiYzMwNzdlZg==

The call returns the token, that must be pasted after the “Bearer “ part in the “Authorization” header for any of below calls.

Send the POST API call to following endpoint:

{{host}}/inn-reach/d2ir/circ/patronhold/{{trackingId}}/{{centralCode}}

Where {{trackingId}} is a unique tracking id of transaction - string, recommended to use only lowercase letters and numbers. And {{centralCode}} is central server code from server settings.

Use following headers:

• x-okapi-tenant - tenant of FOLIO env

• X-To-Code - FOLIO library code (e.g. fli01)

• X-From-Code - Inn-reach server code (e.g. d2irm)

• X-D2IR-Authorization - Bearer eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmb2xpbyIsInN1YiI6IjEwZWVkNThkLWMwYzQtNDhjZS1hNmE1LTc4MTYzMDU4NjQ0MCIsImVkZ2VBcGlLZXkiOiJleUp6SWpvaVpXUm5aVjloWkcxcGJpSXNJblFpT2lKa2FXdDFJaXdpZFNJNkltVmtaMlZmWVdSdGFXNGlmUT09IiwiZXhwIjoxNzUyNTIwMzM1fQ.mSoTGiC7I4kyTjEGBZhrbOOsoGhHjSpSGVKHkSX2WwI
  (there’s a space between “Bearer” and the token, not new line)

Use the following body:

Where:

• pickupLocation - combination of “Service point Code + : + Service point name + : + Some name”, where SP code and name can be found in FOLIO settings, on service point details pane

• centralItemType - item type code from Central item type setting. Item will be created with FOLIO material type mapped to this code.

• title, author and callNumber - temporary instance and item will be created with these values

• needBefore - request expiration date, Unix timestamp from Epoch

• transactionTime - Unix timestamp, can be converted on Epoch

• patronId - FOLIO user’s UUID with removed “-” and converted from HEX to Base32 (with removed “=” symbols at the end, if any) - this user will be used for request creation.

• patronAgencyCode - code of FOLIO library, which this patron is related to

• itemAgencyCode - code of FOLIO library, where the temporary item will be created

• itemId - unique non-existing in FOLIO item HRID

After this call is sent and successful response is returned, following happens:

• Inn-reach transaction is created in Inn-reach app in FOLIO with status PATRON_HOLD and correct details specified in payload (item and request links included)

• A temporary instance with holding and item is created, marked as Suppressed from discovery. Item HRID is formed from default item HRID prefix + transaction tracking ID + item agency code. Holding will have the location mapped in Agency to FOLIO location setting. Item has no barcode and has a material type matching the item type code from payload.

• Item level Page circulation request is created in FOLIO for new temporary item and patron matching the code from payload

• Item status is “Paged”

Transaction can be cancelled before the item has arrived to FOLIO library via “Cancel hold” action

Open

This will update transaction status to BORROWING_SITE_CANCEL and item will be headed back to lending library. Linked request will be cancelled, item becomes Available, but not yet deleted.

To complete cancelled transaction lending library has to perform final check in (described below in step #6).

To confirm that lender library has sent the item to FOLIO borrowing library, send the following API call:

Method: PUT

To: {{host}}/inn-reach/d2ir/circ/itemshipped/{{trackingId}}/{{centralCode}}

Use the same headers, tracking id and central server code as in first step

Body:

Where:

• itemBarcode - enter a unique non-existing in FOLIO barcode. Preferably not to use spaces and special symbols in barcode.

• itemLocation - any string is acceptable, but it doesn’t

• Use the same headers as in the first API call and keep data the same in all fields as in previous call + itemBarcode (its not marked as required in API documentation, but transaction without it won’t be considered valid)

• Required fields are the same as in first call

This will change transaction status to ITEM_SHIPPED, meaning that item has been headed to FOLIO borrowing library.

If some values in payload for this call will differ from the ones sent on transaction creation (e.g. author or callNumber) - they won’t be updated.

To confirm that item has arrived to FOLIO library, receive the item using “Receive item” action in Inn-reach app:

Open

Alternatively, the same thing can be done by scanning received item barcode in “Receive shipped items” option in dropdown:

Open

Note: make sure that correct pickup service point for this request is currently selected, otherwise item and request status will become In transit.

This action does the following:

• Transaction status is changed to ITEM_RECEIVED

• Item is in Awaiting pickup status

• Corresponding request status is changed to Open - Awaiting pickup

If item was not checked out from lending site, but has already arrived to FOLIO, the following action can replace steps #2-3 - Receive unshipped item:

Open

After this action transaction status becomes RECEIVE_UNANNOUNCED and item status becomes Awaiting pickup. Follow step #4 after this one.

Transaction can be also cancelled on this stage, after the item has arrived to FOLIO library, by the same “Cancel hold” action:

Open

This will update transaction status to BORROWING_SITE_CANCEL and item will be headed back to lending library. To complete cancelled transaction lending library has to perform final check in (described below in step #6)

When item reached the pickup service point - it can be checked out to requester. To do so, use the following Inn-reach UI action:

Open

This action will:

• Check out the item to specified FOLIO patron

• Create the loan according to circulation rules

• Close the linked request with status Closed - Filled

Transaction status will remain the same as in step #3 - ITEM_RECEIVED (or RECEIVE_UNANNOUNCED if unshipped item has been received)

Note: transaction can not be cancelled when item is checked out to patron, even though the button is active on this stage - it won’t do any action.

While item is being checked out (statuses ITEM_SHIPPED, ITEM_RECEIVED, ITEM_IN_TRANSIT, RECEIVE_UNANNOUNCED) the loan can be renewed by FOLIO library on user’s page using general renewal rules. Link to the loan is present on Inn-reach transaction details pane and can be opened directly from specified user’s page. Renewal period is determined by loan policy, which are applied as usual - by matching circulation rule.

Transaction status is changed to BORROWER_RENEW.

On the other hand, the item can be renewed from Owner side, to perform it, send the following API call:

Method: PUT

To: {{host}}/inn-reach/d2ir/circ/ownerrenew{{trackingId}}/{{centralCode}}

Use the same headers, tracking id and central server code as in first step

Body:

Specify the new due date in “dueDateTime” using Unix format. Make sure to specify the date that is closer to current due date than supposed new due date according to loan policy. Otherwise regular renewal period will be added to current due date according to circ rule, and the date specified in call won’t take effect.

Use the same values as in previous call to populate the remaining fields. All fields are required.

After this call the due date will be changed on the loan details page, and the transaction status will become OWNER_RENEW.

When patron returns the item to FOLIO, staff must check it in via “Check in” app. It does the following:

• Item status is changed to Available

• Transaction status becomes ITEM_IN_TRANSIT

• Loan is closed

Alternative - click Return item

To confirm that item has reached the lending library, send the following API call:

Method: PUT

To: {{host}}/inn-reach/d2ir/circ/finalcheckin/{{trackingId}}/{{centralCode}}

Use the same headers, tracking id and central server code as in first step

Body:

Use the same values as in previous call to populate body. All fields are required.

After this call:

• Transaction status is changed to FINAL_CHECKIN

• Patron ID and Patron name will be removed from transaction details

• Links to related request and loan will be removed

• Link to temporary item in Item ID field will be removed

• Temporary instance with its holding and item will be removed from Inventory app

After deletion of instance from Inventory, Inn-reach request can be created for the same item again.