Item hold flow (Lending flow)

In itemHold Inn-reach transaction item originates from FOLIO inventory and must be contributed to Inn-reach before transaction start (+ must be lendable).

This page describes the steps should be taken to move through a complete flow via combination of UI actions in FOLIO apps and API calls to emulate a borrowing Inn-reach library response.

API documentation - https://s3.amazonaws.com/foliodocs/api/mod-inn-reach/s/circulation.html#tag/inn-reach-circulation (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/itemhold/{{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:

• id - and id of transaction

• transactionTime - Unix timestamp, can be converted on https://www.epoch101.com/

• 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

• patronId - FOLIO user’s UUID with removed “-” and converted from HEX to Base32 (with removed “=” symbols at the end, if any)

• patronAgencyCode - artificial 5 symbol code of borrowing Inn-reach library

• itemAgencyCode is a code of FOLIO library, which this item is related to. Can be checked on Central server configuration page

• itemId - existing contributed FOLIO item’s HRID

• needBefore - request expiration date, Unix timestamp

• centralPatronType - type of patron from borrowing library (a code from 200 to 236), as mapped in FOLIO circulation user for INN-Reach patron type setting. Loan, Inn-reach request and circ request are going to be created for the FOLIO user mapped to this code.

• patronName - artificial patron name

• patronHomeLibrary - artificial name of borrowing library

• shippedItemBarcode - real FOLIO item barcode (better not to use spaces in barcode)

• createdDate - transaction creation date in regular date format

Note: parameters in bold are required, the remaining ones are optional.

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 ITEM_HOLD and correct details specified in payload (item and request links included)

• Item level Page or Hold circulation request is created in FOLIO with correct data, depending on initial item status (Available or any other requestable)

• Item status becomes “Paged” if item was Available before transaction. Otherwise item status does not change

Inn-reach request can be cancelled before item is sent to borrowing library via following action on UI:

Open

After that, Inn-reach request and circ request will be cancelled.

If FOLIO lending library wants to replace the requested item with another copy of the same instance using Transfer hold to another item option on UI:

Open

This option is always active until the selected item is checked out to borrowing library - the request can be transferred not only once.

The new item can be selected from the same instance in the opened selection modal - all eligible items are shown here, regardless the holding of this instance they are located. Item is eligible if it is in Available status. There’s no need for item to be contributed to Inn-reach.

After this action item id will change in Inn-reach request record and in corresponding circulation request. In the next calls in steps 3-4 new item’s id should be used instead of the initial one.

When transaction is created, user can check out the requested item to borrowing library using UI action on transaction details pane:

Open

Item checkout to borrowing site is not allowed for not available items (e.g. checked out) - FOLIO staff should check item back into a FOLIO service point and/or fulfill any other request for this item in queue before the Inn-reach one. Then such item can be headed to borrowing library.

Alternative way to do (multiple) check outs to borrowing libraries is to switch Inn-reach app action to Check out to borrowing site on the left pane dropdown and scan items ready for check out:

Open

After this action following happens:

• Transaction status becomes ITEM_SHIPPED, loan link appears in transaction details

• Corresponding request becomes Closed - Filled

• Item status becomes Checked out

• Loan is created for linked FOLIO user according to matching circulation rules.

This action can be skipped, but in this case Item received action becomes required.

Note: highly recommended not to attempt checking out the item to the mapped patron via Check out app - transaction status won’t be updated this way and check out to borrowing library will be unavailable until item is checked back in.

To confirm that borrowing library has received sent item, the following API call can be sent:

Method: PUT

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

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

Body:

Where:

• centralItemType - pick a mapped item type from Central item type setting

• All other parameters remain the same as in first API call.

• Only centralItemType, centralPatronType, transactionTime, patronId, patronAgencyCode and itemId are required.

After this step transaction status is changed to ITEM_RECEIVED.

This action can be skipped along with the next one, if the previous action was completed.

When item has already been sent to borrowing library (statuses ITEM_SHIPPED and ITEM_RECEIVED), it can be recalled by a FOLIO lending library. To do so, one needs to create a Recall type circulation request for the checked out Inn-reach item (for any user).

After this action:

• The transaction changes status to RECALL, this is the final status for this transaction

• Item remains checked out

• Item’s due date can change according to the circulation rules for recall

• When item is back from borrowing library, it will be sent in transit to SP specified in Recall request

Even if Recall request is cancelled later, the Inn-reach transaction status will remain RECALL.

When item was received by borrowing library, they check it out to their patron on their site. Then patron returns the item to borrower library - FOLIO is not aware of these actions and transaction remains in ITEM_RECEIVED or ITEM_SHIPPED status during this period. Item status remains checked out.

When item is ready to be sent back to FOLIO library, borrowing library sends it in transit by following call:

Method: PUT

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

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

Body:

Where all parameters are the same as in previous call. All fields are required.

This triggers the transaction to go into status ITEM_IN_TRANSIT. Item status remains checked out.

Note: this action can not be executed if Item received action has been skipped. However, this action can be skipped regardless of previous action’s presence.

While item is being checked out (statuses ITEM_SHIPPED, ITEM_RECEIVED, ITEM_IN_TRANSIT) the loan can be renewed on user’s page using general renewal rules. Renewal period is determined by loan policy, which are applied as usual - by matching circulation rule.

For now it doesn’t change the transaction status - to be investigated.

Another way is to perform borrower renew, by sending this call:

Method: PUT

To: {{host}}/inn-reach/d2ir/circ/borrowerrenew{{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 inn-reach throws an error, because attempts to recall the item - to be investigated.

When item arrives to its home library in FOLIO, staff checks it in via UI action “Final check-in”.

Open

This button becomes active when transaction status is ITEM_RECEIVED.

This action does the following:

• Transaction status becomes FINAL_CHECKIN

• Loan becomes closed

• Item status becomes Available (if item’s home service point was selected at the moment of final check in, otherwise it becomes In transit)

• Patron name and Patron ID are removed from transaction details

Alternatively, this action can be done as usual Check in by barcode in Check in app (use this option if item received and item in transit steps were skipped).