NCIP Version 2
NCIP V.2 specifications
Required and Optional Services
The following table lists required and optional services, messages, and responses required by this profile. NCIP services not listed are not used by this profile:
| Service | Required (R) or Optional (O) |
|---|---|
| LookUpUser | O |
| AcceptItem | R |
| RequestItem | O |
| CheckOutItem | R |
| CheckInItem | R |
| CancelRequestedItem | O |
| RecallItem | O |
| RenewItem | O |
Events Table
| Triggering Event | Initiating Application | Service Initiated | Responding Application |
|---|---|---|---|
| ILL needs to authenticate the user before submitting a request | ILL (Borrowing agency) | LookUpUser | Circulation (Alma) |
| Borrowing request is submitted | ILL (Borrowing agency) | RequestItem | Circulation (Alma) |
| ILL agrees to process the ILL request | ILL (Lending agency) | RequestItem | Circulation (Alma) |
| ILL ships the item to the requester | ILL (Lending agency) | CheckOutItem | Circulation (Alma) |
| ILL Receives the requested item | ILL (Borrowing agency) | AcceptItem | Circulation (Alma) |
| ILL Returns the loaned item to the Lender | ILL (Borrowing agency) | CheckInItem | Circulation (Alma) |
| ILL receives the Item from the Borrower | ILL (Lending agency) | CheckInItem | Circulation (Alma) |
| ILL cancels the request | ILL (Lending agency) | CancelRequestedItem | Circulation (Alma) |
| ILL recalls the request | ILL (Borrowing agency) | RecallItem | Circulation (Alma) |
| ILL renews the request | ILL (Borrowing agency) | RenewItem | Circulation (Alma) |
| ILL receives renew request | ILL (lending agency) | RenewItem | Circulation (Alma) |
The following table describes the fields which are relevant for each service:
| Service | Field | Required (R) or Optional (O) | Description |
|---|---|---|---|
| InitiationHeader | FromAgencyId. AgencyId | R | One of two options:
|
| ToAgencyId. AgencyId | R | One of two options:
| |
| ApplicationProfileType | R | The Partner Code which represents the NCIP ILL application in Alma. | |
| ResponseHeader | FromAgencyId. AgencyId | R | Your Alma institution code, for example: 60univ_inst. |
| ToAgencyId. AgencyId | O | The broker ILL system name (if received in the request message). | |
| LookUpUser | UserId. UserIdentifierValue | R | The user ID to be authenticated. Alma expects the user’s primary id. If identifier type is defined on the partner, that identifier will also be accepted. |
| UserElementType | O | User related information that should be returned. This can be: User Address Information Block Or Trap Name Information User Privilege User ID | |
| AuthenticationInput. AuthenticationInputType | O | Type of the password of the user. Currently supported: Password | |
| AuthenticationInput. AuthenticationInputData | O | Password of the user to be authenticated. This information is required if “Require authentication” is set to Y on the NCIP partner that is defined in Alma. | |
| LookupUserResponse | UserId. UserIdentifierValue | R | The authenticated user ID. |
| UserElementType | O | User related information, if requested. | |
| AcceptItem | RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. This information will be kept on the “external ID” field of the borrowing request in Alma. |
| RequestedActionType | R | Should be ‘Hold For Pickup And Notify’. | |
| UserId. UserIdentifierValue | R | The requesting user’s ID. Alma expects the user identifier type as defined on the partner. | |
| NonReturnableFlag | O | This element indicates that the borrowing request is for digital. | |
| DateForReturn | O | If not supplied, Alma will calculate the due date according to the relevant policies. | |
| ItemOptionalFields. BibliographicDescription | R | All known bibliographic details. Will be used for creating the temporary item. Supported options are: Title, Author, TitleOfComponent, Pagination, BibliographicRecordId, Publisher, PublicationDate, PublicationDateOfComponent, Edition. | |
| PickupLocation | O | A valid pickup location in Alma. This can be a library code in Alma,or HOME_DELIVERY for home delivery. If not supplied, Alma will use default that is defined on the partner. For digital delivery, leave empty. | |
| ItemId. ItemIdentifierValue | O | Item ID in the broker ILL system. If not supplied, a barcode will be generated. Note that auto receive will not work if item identifier was not supplied. | |
| AcceptItemResponse | RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. |
| ItemId. ItemIdentifierValue | O | Item ID in the broker ILL system (if received in the request message). | |
| CheckInItem | ItemId. ItemIdentifierValue | R | Item ID in the broker ILL system. |
| CheckInItemResponse | ItemId. ItemIdentifierValue | R | Item ID in the broker ILL system. |
| RequestItem | RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. This information will be kept on the “external ID” field of the lending request in Alma. |
| BibliographicId. BibliographicRecordId. BibliographicRecordIdentifier | R | Identifier of the requested bibliographic record. The identifier should be of the type specified in BibliographicRecordIdentifierCode. | |
| BibliographicId. BibliographicRecordId. BibliographicRecordIdentifierCode | R | Search can be done based on: LCCN,OCLC,ISBN_ISSN,MMS_ID. Specify the identifier type in this field. | |
| RequestType | R | Should be ‘Loan’ | |
| ItemOptionalFields. BibliographicDescription. MediumType | R | The following value are considered as a request for physical: Audio Tape, Book, Book With Audio Tape, Book With Compact Disc, Book With Diskette, Bound Journal, CD-ROM, Compact Disc (CD), Diskette, Magazine, Microform, Video Tape Any other value is considered as a request for digital . | |
| RequestScopeType | R | Should be ‘Bibliographic Item’ | |
| UserId. UserIdentifierValue | R | Put any value. | |
| NeedBeforeDate | O | The last interesting date. | |
| Ext.Parts | O | If received, this field will be populated in the created lending request in Alma. | |
| Ext.Issues | O | If received, this field will be populated in the created lending request in Alma. | |
| Ext.Chapters | O | If received, this field will be populated in the created lending request in Alma. | |
| Ext.Pages | O | If received, this field will be populated in the created lending request in Alma. | |
| Ext.ItemNote | O | If received, this field will be populated in the created lending request in Alma. | |
| Ext.Volumes | O | If received, this field will be populated in the created lending request in Alma. | |
| RequestItemResponse | RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. |
| UserId. UserIdentifierValue | R | The value received for user in the request message. | |
| RequestType | R | ‘Hold’ | |
| RequestScopeType | R | ‘Bibliographic Item’ | |
| CheckOutItem | RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. This information will be kept on the “external ID” field of the lending request in Alma. |
| UserId. UserIdentifierValue | R | Put any value. | |
| DesiredDateDue | O | The due date. | |
| ItemId. ItemIdentifierValue | O | Item barcode of the shipped item. Required if the request is for physical delivery. | |
| CheckOutItemResponse | ItemId. ItemIdentifierValue | O | Item barcode of the shipped item. Required if the request is for physical delivery. |
| UserId. UserIdentifierValue | R | The value received for user in the request message. | |
| DateDue | R | The due date. | |
| CancelRequestItem | RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. |
| UserId. UserIdentifierValue | R | Put any value. | |
| RequestType | R | Should be ‘Hold’ | |
| CancelRequestItemResponse | ItemId. ItemIdentifierValue | R | Item ID of the shipped item. |
| UserId. UserIdentifierValue | R | The value received for user in the request message. | |
| RequestId. RequestIdentifierValue | R | Request ID in the broker ILL system. | |
| RecallItem | ItemId. ItemIdentifierValue | R | ID of the recalled item |
| DateDue | O | If not supplied, Alma will calculate due date according its policy. | |
| RecallItemResponse | ItemId. ItemIdentifierValue | R | ID of the recalled item |
| DateDue | R | The updated due date | |
| UserId. UserIdentifierValue | R | The user which requested the item | |
| RenewItem | ItemId. ItemIdentifierValue | R | ID of the item to be renewed |
| UserId. UserIdentifierValue | For borrowing: R For lending: O | For borrowing: The user which requested the renewal For lending: leave empty | |
| DateDue | O | If not supplied, Alma will calculate due date according its policy. | |
| RenewItemResponse | ItemId. ItemIdentifierValue | R | ID of the renewed item |
| DateDue | R | The updated due date | |
| UserId. UserIdentifierValue | R | The user which requested the item |
Note that RequestItem message can be sent either to create a borrowing request or a lending request. Alma differentiates the flow based on the agency id of the user.