ISO ILL

ISO ILL

The InterLibrary Loan Protocol (ISO ILL 10160/10161) was developed to provide uniform procedures for handling  peer-to-peer interlibrary loan operation between two ILL systems. The standard defines a number of messages that can be sent between the requesting site and the supplying site in order for the requester to have access to different services and material that might be offered by the supplying organization.

As of the July 2019 release, Alma supports the ISO workflow also via the ISO 18626 (using ttp://illtransactions.org/schemas/ISO-18626-v1_1.xsd ) protocol.

Workflow

When a request is sent to a library this starts a new transaction. The transaction continues until the item is satisfactorily supplied and, if a loan item, satisfactorily returned, or the supplying library notifies that it cannot supply the item. Transactions may last for a few seconds or minutes, if the supplying library has electronic access to its catalogues and is supplying documents held electronically over the network, or may last for months, for example where a loaned item is renewed.
In general a transaction goes through several stages:
  • Request
  • Failure or notification of shipping of the item
  • Acknowledgement of receipt of the item
  • Reminders to return loaned items
  • Return of item or notification of lost item
  • Acknowledgement of receipt of returned item
The standard formally divides these stages into two phases, namely the processing phase which lasts from request until either shipped notification or notification of failure to supply, followed, for loan items only, by the tracking phase.
The following diagram illustrates the workflow:

 

The following table summaries the technical details of the ISO ILL support in Alma:

Status of ISO ILL Implementation In Production
Protocol Version 2
transaction types Simple
Role Borrower, Lender
Transport Protocol(s) Used Message format: APDU
Character Set: Unicode/UTF-8
Transport Layer: TCP
Messages supported as Borrower ILL-Request
Received
Returned
Cancel
Renew
General Messages
Messages supported as Lender Shipped
Checked-In
Answer – Unfilled
Cancel Reply
Renew Answer
General Messages
Expired
Third Party Tools Used NA

Events Table

Triggering Event Initiator Service Behavior in the receiving application
Patron requests material that does not exist locally Borrower ILL Request Request is created.

Lender checks if material is available

Material exists. Library is willing to supply it, and send it to the requesting library Lender Shipped
Material does not exist, or library is not willing to supply it Lender Answer unfilled Requesting library will pass the request to a different potential supplier
Expiry date of the Lending Request is passed Lender Expired Requesting library will close the request
Material has received in the library Borrower Received
Material was returned by the borrowing patron Borrower Returned
Material is back in the lending library Lender Checked-in transaction is closed
Patron cancels the request Borrower Cancel transaction is closed.

Cancel reply message should be sent

Patron asks to renew the request Borrower Renew Renew Answer message should be sent, indicating whether the lending library agrees to renew
Staff sends a general message manually Borrower or Lender General message staff should review and handle manually

Required and Optional Services

The following table lists required and optional services. ISO services not listed are not used by this profile. In order to communicate with Alma using ISO ILL communication, the required services must be supported:
Service Role Required (R) or Optional (O)
ILL Request Borrower R
Shipped Lender R
Received Borrower R
Returned Borrower R
Checked-In Lender O
Answer – Unfilled Lender R
Expired Lender O
Cancel Borrower R
Cancel Reply Lender O
Renew Borrower O
Renew Answer Lender O
General Messages Borrower and Lender O

 

ISO 10160/10161 Details

The following table describes the fields which are relevant for each service:

Service Field Required (R) or Optional (O) Description
protocol-version-num R 2
Transaction-Id R Unique id of the transaction and the message
service-date-time R Date and time of the service.
Aliases Not supported
APDUDeliveryInfo extension O Messages from Alma includes this extension.
Messages to Alma are not forced to include this extension, however if possible it is recommend to include it. Alma uses it in order to identify the sender and receiver.
transaction-type R 1 (Simple)
ILL-Request delivery-address R Address for delivering the material.
This is usually the library’s address.
Alma might put the requesting patron’s address if the partner supports this option (configured on the partner).
BillingAddress O Address for sending bills
IllServiceType R (1) “loan”, (2) “copy/nonreturnable”
for Electronic send 2.
expiry-flag O Default: 3 (no expiry)
item-id R Information regarding the requested item (including bibliographic information).

  • Note that most of the “Resource Information” fields of the borrowing request Alma form are mapped here. Only the following fields are not mapped: Author initials, Additional person name, Note.
  • Alma match logic is as following: NationalBibliographyNo – if supplied.
    If not supplied – match will be done according to the partner’s configuration. Default is ISBN and Title.
forward-flag Not supported
retry-flag Not supported
requester-note O Free text note
Shipped shipped-service-type R (1) “loan” and (2), “copy/nonreturnable”
date-shipped O Date of shipment
date-due O Due date of the item. Relevant in case of loan.
Note that it is possible to configure Alma to ignore this and use the library’s terms of use.
responder-note O Free text note
ILL-Answer transaction-results R 3 (unfilled) – currently, this is the only supported option
UnfilledResults R The reason for not filling the ILL request
responder-note O Free text note
Cancel requester-note O Free text note
Cancel-Reply answer R True/False. Usually this should be TRUE.
responder-note O Free text note
Renew DesiredDueDate O If not supplied, the lending library will renew according its policy.
note O Free text note
Renew-Answer answer R True/False.
note O Free text note
DateDue O Required if answer=True
Received date-received R Date of recieval
shipped-service-type R (1) “loan” and (2), “copy/nonreturnable”.
requester-note O Free text note
Returned date-returned R Date of return
requester-note O Free text note
Checked-in date-checked-in R Date of check-in
responder-note O Free text note
Message note R Free text note

ISO 18626 Details

Borrower Messages

Request

Message =request.

Header :

  • supplyingAgencyId = requester ISO Symbol
  • requestingAgencyId = lender ISO Sybmol
  • timestamp
  • requestingAgencyRequestId = request Id

bibliographicInfo

publicationInfo

  • From today’s itemId relevant fields

ServiceInfo

  • requestType – ‘New’ or ‘Retry’
  • ServiceType – ‘Copy’ or ‘Loan’ or ‘CopyOrLoan’ if “Allow Other Format” is selected
  • ServiceLevel – like the current level of service. Codes in http://illtransactions.org/opencode/
  • Preferred format – code table should be enriched with values from http://illtransactions.org/opencode/. There should be a mapping of the old values to these values, with additional information sent as note in case old ISO is used. OI
  • needBeforeDate – as today
  • copyrightCompliance – a stoday
  • anyEdition – Yes/No depending on ‘Specific Addition Only
  • note – Request Note

supplierInfo – this will be used for IE and barcode- information obtained from the supplier’s record

  • supplierCode – Institution code when sending IE or barcode
  • supplierDescription – ‘IE’ or ‘barcode’
  • bibliographicRecordId the IE or the barcode

requestedDeliveryInfo – the delivery address, using address/electronicAddress or address/physicalAddress. This is for ADD.

requestingAgencyInfo – The resource sharing library physical and electronic (email) address

patronInfo – if ‘share patron information is on’.

billingInfo – only the maximum costs from ‘Maximum Fee’

 

Received

Message = RequestingAgencyMessage with

  • Header
  • Action – “Received”
  • note

Lender will respond with RequestingAgencyMessageConfirmation. The confirmationHeader is as in the request, and the messageStatus is OK. timestampReceived is the time the message was received (taken from its timestamp).

Action is “Received”

Returned

Message = RequestingAgencyMessage with

  • Header
  • Action – “ShippedReturned”
  • note

Lender will respond with RequestingAgencyMessageConfirmation. The confirmationHeader is as in the request, and the messageStatus is OK. timestampReceived is the time the message was received (taken from its timestamp).

Action is “ShippedReturned”

Renew

Message = RequestingAgencyMessage with

  • Header
  • Action – “Renew”
  • note

Action is “Renew”

Expired

Will be managed as borrower side triggered cancellation, as done for fulfillment network

Cancel

Message = RequestingAgencyMessage with

  • Header
  • Action – “Cancel”
  • note

Action is “Cancel”

General Message

Message = RequestingAgencyMessage with

  • Header
  • Action – “Notification”
  • note

Action is “Notification”

Lender Messages

Shipped

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘RequestResponse’
    • note if filled in
    • reasonUnfilled – as per codes in http://illtransactions.org/opencode/. Code table should be adjusted and mapped to old ISO codes
  • statusInfo
    • status = ‘Loaned’ or ‘CopyCompleted’ or ‘CompletedWithoutReturn’ as per format
    • dueDate – the due date
    • DeliveryInfo
      • dateSent
      • itemId – the barcode
      • sentToPatron Yes\No as per incoming request
      • deliveryCosts/monetaryValue – shipping costs
    • lastChange – timestamp

CheckedIn

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘RequestResponse’
    • note if filled in
  • statusInfo
    • status = ‘LoanCompleted’
    • lastChange – timestamp

reasonforMessage is RequestResponse

Overdue

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘StatusChange’
    • note if filled in
  • statusInfo
    • status = ‘Overdue’
    • lastChange – timestamp

reasonforMessage is StatusChange

 

Recall

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘StatusChange’
    • note if filled in
  • statusInfo
    • status = ‘Recalled’
    • lastChange – timestamp

reasonforMessage is StatusChange

RenewResponse

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘RenewResponse’
    • note if filled in
    • AnswerYesNo – as per whether the renew is done or not.
  • statusInfo
    • status = ‘Loaned’ or real status (such as ‘Loaned’) is cancellation failed.
    • dueDate – the due date
    • lastChange – timestamp

reasonforMessage is RenewResponse

Rejected

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘RequestResponse’
    • note if filled in
    • reasonUnfilled – as per codes in http://illtransactions.org/opencode/. Code table should be adjusted and mapped to old ISO codes
  • statusInfo
    • status = ‘Unfilled’
    • lastChange – timestamp

reasonforMessage is RequestResponse

Cancel Response

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘CancelResponse’
    • note if filled in
    • aswwerYesNo – as per whether the cancallation is done or not.
  • statusInfo
    • status = ‘Cancelled’ or real status (such as ‘Loaned’) is cancellation failed.
    • lastChange – timestamp

reasonforMessage is CancelResponse

Will Supply

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘RequestResponse’
    • note if filled in
  • statusInfo
    • status = ‘WillSupply’
    • lastChange – timestamp

reasonforMessage is RequestResponse

 

General message

Message = supplyingAgencyMessage with

  • Header
  • MessageInfo
    • reasonforMessage – ‘Notification’
    • note if filled in
  • statusInfo
    • status = Real status (such as ‘Loaned’). One of:
      • RequestReceived
      • ExpectToSupply
      • WillSupply
      • Loaned
      • Overdue
      • Recalled
      • Unfilled
      • CopyCompleted
      • LoanCompleted
      • CompletedWithoutReturn
      • Cancelled
  • lastChange – timestamp

reasonforMessage is Notification

 

Security and Privacy

User authentication and authorization is out of scope of this profile. It is assumed that the ILL and Alma applications whose interactions are described in this profile trust each other.

Required Configuration in Alma

An ILL partner of ‘ISO ILL’ type should be defined, representing the institution with which a communication should be enabled. Refer to Alma online help for more information.

Required Configuration in the ILL system integrating with Alma

  • The ISO messages should include the relevant fields and information, as described above.
  • The URL for which ISO messages should be sent to Alma is
    • (ISO ILL 10160/10161) – [Alma domain]:9001, e.g.  na02.alma.exlibrisgroup.com:9001
    • ISO 18626 – [Alma domain]/view/P2PServlet?type=iso18626, e.g.  https://na01.alma.exlibrisgroup.com/view/P2PServlet?type=iso18626