ISO ILL
ISO ILL
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
- 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 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
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).
| |
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
- As today. BibliographicItemIdCode is ISSN or ISBN or ISMN (http://illtransactions.org/opencode/)
- bibliographicRecordId is LCCN/OCLC/MID.
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
- status = Real status (such as ‘Loaned’). One of:
- 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