Ready to Learn?Ex Libris products all provide open APIs

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:
 
ServiceFieldIDDescription
Checkin (09)noBlock Indication if the checkin was actually performed, and therefore should not be blocked
 transactionDate Current date
 returnDate return date
 currentLocationAPnot supported
 institutionIdAOThe institution ID
E.g. 01MY_INST
 itemIdentifierABThe identifier type is defined on the “sef-check” profile in Alma
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 itemPropertiesCHnot supported
 cancelBIY/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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 itemIdentifierABThe item identifier as received in the "checkin" message
 PermanentLocationAQThe name of the item's permanent location
 titleIdentifierAJThe item's title
 Sort binCLAccording to the configuration defined in Alma
 patronIdentifierAAThe patron identifier as received in the "checkin" message
 mediaTypeCKPhysicalMaterialType
 itemPropertiesCHnot supported
ServiceFieldIDDescription
Checkout (11)renewalPolicy Should match the “Renew Policy” definition defined on the “self-check” profile in Alma
 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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 itemIdentifierABThe identifier type is defined on the “sef-check” profile in Alma
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 itemPropertiesCHNot supported
 patronPasswordADThis 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
 feeAcknowledgedBONot supported
 cancelBIY/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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAThe patron identifieras received in the "checkout" message
 itemIdentifierABThe item identifier as received in the "checkout" message
 titleIdentifierAJThe item's title
 dueDateAHLoan due date
 feeTypeBTNot supported
 securityInhibitCI'Y'
 currencyTypeBHNot supported
 feeAmountBVNot supported
 mediaTypeCKPhysicalMaterialType
 itemPropertiesCHnot supported
 transactionIdBKNot supported

 

 
ServiceFieldIDDescription
Item Information Request (17)transactionDate Current date
 institutionIdAOThe institution ID
E.g. 01MY_INST
 itemIdentifierABThe identifier type is defined on the “sef-check” profile in Alma
 terminalPasswordACAs 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
 holdQueueLengthCFThe length of the queue of requests on this item
 dueDateAHDueDate if the item is on loan
 recallDateCJnot supported
 holdPickupDateCMRequest expiration date
 itemIdentifierABThe item identifier as received in the "item information" message
 titleIdentifierAJThe item's title
 ownerBGOwning library name
 currencyTypeBHThe institution's currency type
 feeAmountBVThe related item's total fees anount
 mediaTypeCKPhysicalMaterialType
 permanentLocationAQName of the item's permanent location
 currentLocationAPName of the item's current location
 itemPropertiesCHNot supported
 
ServiceFieldIDDescription
Patron status (23)language The language code
Should match the “self-check” profile in Alma
 transactionDate Current date
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 patronPasswordADThis 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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAthe patron id as received in the “patron status” message
 personalNameAEPatron’s First Middle and Last Name
 validPatronBLY/N indication if the received patron id is valid
 validPatronPasswordCQY/N indication if the received patron password is valid
 currencyTypeBHInstitution currency
 feeAmountBVPatron's active balance
 
ServiceFieldIDDescription
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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 patronPasswordADThis 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
 itemIdentifierABThe identifier type is defined on the “self-check” profile in Alma
 titleIdentifierAJnot supported
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 itemPropertiesCHnot supported
 feeAcknowledgedBOnot 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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAthe patron id as received in the “fee paid” message
 itemIdentifierABThe item identifier as received in the "checkout" message
 titleIdentifierAJThe item's title
 dueDateAHLoan due date
 feeTypeBTNot supported
 securityInhibitCI'Y'
 currencyTypeBHThe institution's currency type
 feeAmountBV 
 mediaTypeCKPhysicalMaterialType
 itemPropertiesCHnot supported
 transactionIdBKNot supported

 

 
ServiceFieldIDDescription
End Patron Session Request (35)transactionDate Current date
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 patronPasswordADThis 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
End Session Response (36)endSession Y/N indication if end session was completed successfully
 transactionDate Current date
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAThe patron identifier as received in the "end session" message
 
ServiceFieldIDDescription
Fee paid (37)transactionDate Current date
 paymentType Method of payment
 feeType not supported
 currencyType The institution's currency type
 feeAmountBVThe amount to pay/td>
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 patronPasswordADThis 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
 feeIdentifierEKId of specific fine/fee to pay
(supported if the integration profile is configured with "Extended Fines and Fees" extension)
 transactionIdBZPayment 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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAthe patron id as received in the “fee paid” message

 

 
ServiceFieldIDDescription
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
3 - fine items
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 patronPasswordADThis 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
 startItemBPThis field specifies the number in that list of the first item to be sent to the SC
 endItemBQThis 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 (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
 holdItemsCount Number of Open Hold Requests exists for this patron
 overdueItemsCount Loans that are overdue for this patron
 chargedItemsCount Number of loans for this patron
 fineItemsCount Number of loans with accrued fines
 recallItemsCount not supported
 unavailableHoldsCount not supported
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAthe patron id as received in the “patron status” message
 personalNameAEPatron’s First Middle and Last Name
 holdItemsLimitAEnot supported
 overdueItemsLimitCAoverdue limit of the patron
 chargedItemsLimitCBnot supported/td>
 validPatronBLY/N indication if the received patron id is valid
 validPatronPasswordCQY/N indication if the received patron password is valid
 currencyTypeBHInstitution currency
 feeAmountBVPatron's active balance
 feeLimitCCPatron's cash limit
 holdItemsASlist of relevant items
 overdueItemsATlist of relevant items
 chargedItemsAUnot supported
 fineItemsAVlist of relevant items
 recallItemsBUnot supported
 unavilableHoldItemsCDnot supported
 homeAddressBDpatron's home address
 eMailAddressBEPatron's email address
 homePhoneNumberBFPatron’s Home Phone number

 

 
ServiceFieldIDDescription
Renew all(65)transactionDate Current date
 institutionIdAOThe institution ID
E.g. 01MY_INST
 patronIdentifierAAAny identifier that is defined in Alma as “unique cross institution”
 patronPasswordADThis 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
 terminalPasswordACAs defined on the relevant circulation desk in Alma
 feeAcknowledgedBOnot 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
 institutionIdAOThe institution ID
E.g. 01MY_INST

 

ServiceFieldIDDescription
Login (93)UIDAlgorithm not supported
 PWDAlgorithmh not supported
 loginUserIdCNAny identifier that is defined in Alma as “unique cross institution”
 loginPasswordCOThis 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
 locationCodeCPThe institution id
Login Response (94)ok 1 if login successfully
ServiceFieldIDDescription
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 'N'
 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
 institutionIdAOThe institution ID
E.g. 01MY_INST
 libraryNameAMThe name of the library of the circulation desk
 supportedMessagesBXCheck out
End patron session
Fee paid
Item information
Login
Patron information
Patron status
Renew
Renew all
status
 terminalLocationANThe 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 and Fee paid 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

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).