SIP2 messages
Alma supports sip2 messages according to the SIP2 protocol definitions. Following are the details of each supported message and its fields. Note that messages that are not listed below are not supported by Alma:
| Service | Field | ID | Description |
|---|---|---|---|
| Checkin (09) | noBlock | Indication if the checkin was actually performed, and therefore should not be blocked | |
| transactionDate | Current date | ||
| returnDate | return date | ||
| currentLocation | AP | not supported | |
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| itemIdentifier | AB | The identifier type is defined on the “sef-check” profile in Alma | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| itemProperties | CH | not supported | |
| cancel | BI | Y/N Y indicates that this transaction is used in order to cancel a failed checkout | |
| Checkin response (10) | ok | 0/1 indication if checkin was completed successfully | |
| magenticMedia | indication if the item is magnetic | ||
| desensitize | According to the defined item policy: If the item is for use only within the library – the value will be set to ‘N’ If the item can be removed from the library this field will be set to ‘Y’ | ||
| alert | Relevant if the “self-check” profile in Alma is configured to support alert Alert should be applied in case there is a fulfillment note or existing request | ||
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| itemIdentifier | AB | The item identifier as received in the “checkin” message | |
| PermanentLocation | AQ | The name of the item’s permanent location | |
| titleIdentifier | AJ | The item’s title | |
| Sort bin | CL | According to the configuration defined in Alma | |
| patronIdentifier | AA | The patron identifier as received in the “checkin” message | |
| mediaType | CK | PhysicalMaterialType | |
| itemProperties | CH | not supported |
| Service | Field | ID | Description |
|---|---|---|---|
| Checkout (11) | renewalPolicy | Should match the “Renew Policy” definition defined on the “self-check” profile in Alma. This parameter is not functional, i.e. a checkout action on an already checked out item will trigger a renew (as per Alma defined policies), regardless of this parameter. | |
| noBlock | Indication if the checkout was actually performed, and therefore should not be blocked | ||
| transactionDate | Current date | ||
| nbDueDate | The due date in case a no block checkout is applied | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | Any identifier that is defined in Alma as “unique cross institution” | |
| itemIdentifier | AB | The identifier type is defined on the “sef-check” profile in Alma | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| itemProperties | CH | Not supported | |
| patronPassword | AD | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| feeAcknowledged | BO | Not supported | |
| cancel | BI | Y/N Y indicates that this transaction is used in order to cancel a failed checkin | |
| Checkout response (12) | Ok | 0/1 indication if checkout was completed successfully | |
| renewalOk | Y/N indication if the item was already checked out by the same patron, and therefore actually being renewed | ||
| magenticMedia | Indication if the item is magnetic | ||
| desensitize | According to the defined item policy: If the item is for use only within the library – the value will be set to ‘N’ If the item can be removed from the library this field will be set to ‘Y’ | ||
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | The patron identifieras received in the “checkout” message | |
| itemIdentifier | AB | The item identifier as received in the “checkout” message | |
| titleIdentifier | AJ | The item’s title | |
| dueDate | AH | Loan due date (format is based on the system_date_format parameter and the use_time_format_with_time_zone_in_self_check parameter) | |
| feeType | BT | Not supported | |
| securityInhibit | CI | ‘Y’ | |
| currencyType | BH | Not supported | |
| feeAmount | BV | Not supported | |
| mediaType | CK | PhysicalMaterialType | |
| itemProperties | CH | not supported | |
| transactionId | BK | Not supported |
| Service | Field | ID | Description |
|---|---|---|---|
| Item Information Request (17) | transactionDate | Current date | |
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| itemIdentifier | AB | The identifier type is defined on the “sef-check” profile in Alma | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| Item Information Response (18) | circulationStatus | Possible values according to the item process: ON_ORDER, CHARGED (for loaned /ILL items), ON_HOLD_SHELF, IN_TRANSIT AVAILABLE, MISSING | |
| securityMarker | ’00’ (Other) | ||
| feeType | 01 (other/unknown) | ||
| transactionDate | Current date | ||
| holdQueueLength | CF | The length of the queue of requests on this item | |
| dueDate | AH | DueDate if the item is on loan (format is based on the system_date_format parameter and the use_time_format_with_time_zone_in_self_check parameter) | |
| recallDate | CJ | not supported | |
| holdPickupDate | CM | Request expiration date | |
| itemIdentifier | AB | The item identifier as received in the “item information” message | |
| titleIdentifier | AJ | The item’s title | |
| owner | BG | Owning library name | |
| currencyType | BH | The institution’s currency type | |
| feeAmount | BV | The related item’s total fees anount | |
| mediaType | CK | PhysicalMaterialType | |
| permanentLocation | AQ | Name of the item’s permanent location | |
| currentLocation | AP | Name of the item’s current location | |
| itemProperties | CH | Not supported |
| Service | Field | ID | Description |
|---|---|---|---|
| Patron status (23) | language | The language code Should match the “self-check” profile in Alma | |
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | Any identifier that is defined in Alma as “unique cross institution” | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| patronPassword | AD | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| Patron status response (24) | patronStatus | Supported positions: 0 – Charge privileges (N if the user is blocked, not active or expired) 3 – Hold privileges (N if the user is blocked, not active or expired) 5 – Too many items 6 – Too many items overdue 10,11 – Outstanding fine/fees | |
| language | The language code Ad defined on the “self-check” profile in Alma | ||
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | the patron id as received in the “patron status” message | |
| personalName | AE | Patron’s First Middle and Last Name | |
| validPatron | BL | Y/N indication if the received patron id is valid | |
| validPatronPassword | CQ | Y/N indication if the received patron password is valid | |
| currencyType | BH | Institution currency | |
| feeAmount | BV | Patron’s active balance |
| Service | Field | ID | Description |
|---|---|---|---|
| Renew (29) | thirdPartyAllowed | Not suported | |
| noBlock | Indication if the renew was actually performed, and therefore should not be blocked | ||
| transactionDate | Current date | ||
| nbDueDate | The due date in case a no block checkout is applied | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | Any identifier that is defined in Alma as “unique cross institution” | |
| patronPassword | AD | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| itemIdentifier | AB | The identifier type is defined on the “self-check” profile in Alma | |
| titleIdentifier | AJ | not supported | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| itemProperties | CH | not supported | |
| feeAcknowledged | BO | not supported | |
| Renew response (30) | Ok | 0/1 indication if renew was completed successfully | |
| renewalOk | Y/N indication if the item was already checked out by the same patron | ||
| magenticMedia | Indication if the item is magnetic | ||
| desensitize | According to the defined item policy: If the item is for use only within the library – the value will be set to ‘N’ If the item can be removed from the library this field will be set to ‘Y’ | ||
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | the patron id as received in the “fee paid” message | |
| itemIdentifier | AB | The item identifier as received in the “checkout” message | |
| titleIdentifier | AJ | The item’s title | |
| dueDate | AH | Loan due date (format is based on the system_date_format parameter and the use_time_format_with_time_zone_in_self_check parameter) | |
| feeType | BT | Not supported | |
| securityInhibit | CI | ‘Y’ | |
| currencyType | BH | The institution’s currency type | |
| feeAmount | BV | ||
| mediaType | CK | PhysicalMaterialType | |
| itemProperties | CH | not supported | |
| transactionId | BK | Not supported |
| Service | Field | ID | Description |
|---|---|---|---|
| Fee paid (37) | transactionDate | Current date | |
| paymentType | Method of payment Supported methods:
| ||
| feeType | not supported | ||
| currencyType | The institution’s currency type | ||
| feeAmount | BV | The amount to pay/td> | |
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | Any identifier that is defined in Alma as “unique cross institution” | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| patronPassword | AD | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| feeIdentifier | EK | Id of specific fine/fee to pay (supported if the integration profile is configured with “Extended Fines and Fees” extension) | |
| transactionId | BZ | Payment transaction number to attach to the payment action (supported if the integration profile is configured with “Extended Fines and Fees” extension) | |
| Fee paid Response (38) | paymentAccepted | Y/N indication if the payment was completed successfully | |
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | the patron id as received in the “fee paid” message |
| Service | Field | ID | Description |
|---|---|---|---|
| Patron Information Request (63) | language | The language code Should match the “self-check” profile in Alma | |
| transactionDate | Current date | ||
| Summary | Supported positions: 0 – hold items 1 – overdue items 2 – charged items 3 – fine items | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | Any identifier that is defined in Alma as “unique cross institution” | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| patronPassword | AD | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| startItem | BP | This field specifies the number in that list of the first item to be sent to the SC | |
| endItem | BQ | This field specifies the number in that list of the last item to be sent to the SC | |
| Patron Information Response (64) | patronStatus | Supported positions: 0 – Charge privileges denied (Y if the user is blocked, not active or expired) 3 – Hold privileges denied (Y if the user is blocked, not active or expired) 5 – Too many items 6 – Too many items overdue 10,11 – Outstanding fine/fees | |
| language | The language code Ad defined on the “self-check” profile in Alma | ||
| transactionDate | Current date | ||
| holdItemsCount | The number of Open Hold Requests existing for this patron. This includes all active hold requests for the patron, including requests on the hold shelf and requests that are not yet filled. | ||
| overdueItemsCount | Loans that are overdue for this patron | ||
| chargedItemsCount | Number of loans for this patron | ||
| fineItemsCount | Number of loans with accrued fines (count considers only fines that are linked to a loan i.e. an active loan with accrued fines or a completed loan with generated fines) | ||
| recallItemsCount | not supported | ||
| unavailableHoldsCount | not supported | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | the patron id as received in the “patron status” message | |
| personalName | AE | Patron’s First Middle and Last Name | |
| holdItemsLimit | AE | not supported | |
| overdueItemsLimit | CA | overdue limit of the patron | |
| chargedItemsLimit | CB | not supported | |
| validPatron | BL | Y/N indication if the received patron id is valid | |
| validPatronPassword | CQ | Y/N indication if the received patron password is valid | |
| currencyType | BH | Institution currency | |
| feeAmount | BV | Patron’s active balance | |
| feeLimit | CC | Patron’s cash limit | |
| holdItems | AS | list of relevant items | |
| overdueItems | AT | list of relevant items | |
| chargedItems | AU | list of items loaned by the patron | |
| fineItems | AV | list of relevant items | |
| recallItems | BU | not supported | |
| unavilableHoldItems | CD | not supported | |
| homeAddress | BD | patron’s home address | |
| eMailAddress | BE | Patron’s email address | |
| homePhoneNumber | BF | Patron’s Home Phone number |
| Service | Field | ID | Description |
|---|---|---|---|
| Renew all(65) | transactionDate | Current date | |
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| patronIdentifier | AA | Any identifier that is defined in Alma as “unique cross institution” | |
| patronPassword | AD | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| terminalPassword | AC | As defined on the relevant circulation desk in Alma | |
| feeAcknowledged | BO | not supported | |
| Renew all response (66) | Ok | 0/1 indication if renew was completed successfully | |
| renewedCount | number of renewed items | ||
| unrenewedCount | number of items which were not renewed | ||
| transactionDate | Current date | ||
| institutionId | AO | The institution ID E.g. 01MY_INST |
| Service | Field | ID | Description |
|---|---|---|---|
| Login (93) | UIDAlgorithm | not supported | |
| PWDAlgorithmh | not supported | ||
| loginUserId | CN | Any identifier that is defined in Alma as “unique cross institution” | |
| loginPassword | CO | This is the “PIN number” of the patron Should be sent only if “Authentication Required” is set to “Y” on the self-check protocol in Alma | |
| locationCode | CP | The institution id | |
| Login Response (94) | ok | 1 if login successfully |
| Service | Field | ID | Description |
|---|---|---|---|
| SC status (99) | StatusCode | 0 – SC unit is OK 1 – SC printer is out of paper 2 – SC is about to shut down | |
| maxPrintWidth | This is the maximum number of characters that the SC printer can print in one line | ||
| protocolVersion | 2.00 | ||
| ACS Status (98) | onLineStatus | ‘Y’ | |
| checkInOk | According to the sef-check profile in Alma | ||
| checkOutOk | According to the sef-check profile in Alma. | ||
| renewalPolicy | According to the sef-check profile in Alma | ||
| statusUpdateOk | ‘N’ | ||
| offlineOk | ‘Y’ | ||
| timeoutPeriod | According to the sef-check profile in Alma | ||
| retriesAllowed | According to the sef-check profile in Alma | ||
| dateTimeSync | Alma system date/time | ||
| protocolVersion | 2.00 | ||
| institutionId | AO | The institution ID E.g. 01MY_INST | |
| libraryName | AM | The name of the library of the circulation desk | |
| supportedMessages | BX | Check out End patron session Fee paid Item information Login Patron information Patron status Renew Renew all status | |
| terminalLocation | AN | The circulation desk’s name |
Extensions
Currently, the only extension that Alma supports is Extended Fines and Fees. The following fields will be added for each open charge in the Patron Information Response message :
- EB – Barcode of the item that is linked to the charge (such as for an overdue/lost item)
- ET – Title of the item that is linked to the charge
- EC – Cash transaction type code
- ED – Cash transaction type description
- EF – Sum
- EK – Fee ID
- BZ – Payment transaction number
The Fee paid message will allow paying specific fines using the EK and BZ field –
- EK – Fee ID
- BZ – Payment transaction number
Note that in order to use this option, the “self-check” profile in Alma should be configured accordingly.
Make sure that the self check machine supports this option as well.
Note regarding dates: In general, Alma accepts and returns dates in its date format (system_time_format customer parameter).
It is possible to define Alma to return the due date field (AH) without time zone (use_time_format_with_time_zone_in_self_check customer parameter).