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)noBlockIndication if the checkin was actually performed, and therefore should not be blocked
transactionDateCurrent date
returnDatereturn 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)ok0/1 indication if checkin was completed successfully
magenticMediaindication if the item is magnetic
desensitizeAccording 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’
alertRelevant 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
transactionDateCurrent 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)renewalPolicyShould match the “Renew Policy” definition defined on the “self-check” profile in Alma
noBlockIndication if the checkout was actually performed, and therefore should not be blocked
transactionDateCurrent date
nbDueDateThe 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)Ok0/1 indication if checkout was completed successfully
renewalOkY/N indication if the item was already checked out by the same patron, and therefore actually being renewed
magenticMediaIndication if the item is magnetic
desensitizeAccording 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’
transactionDateCurrent 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)transactionDateCurrent 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)circulationStatusPossible values according to the item process:
ON_ORDER, CHARGED (for loaned /ILL items),
ON_HOLD_SHELF, IN_TRANSIT
AVAILABLE, MISSING
securityMarker’00’ (Other)
feeType01 (other/unknown)
transactionDateCurrent 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)languageThe language code
Should match the “self-check” profile in Alma
transactionDateCurrent 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)patronStatusSupported 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
languageThe language code
Ad defined on the “self-check” profile in Alma
transactionDateCurrent 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)thirdPartyAllowedNot suported
noBlockIndication if the renew was actually performed, and therefore should not be blocked
transactionDateCurrent date
nbDueDateThe 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)Ok0/1 indication if renew was completed successfully
renewalOkY/N indication if the item was already checked out by the same patron
magenticMediaIndication if the item is magnetic
desensitizeAccording 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’
transactionDateCurrent 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
Fee paid (37)transactionDateCurrent date
paymentTypeMethod of payment
feeTypenot supported
currencyTypeThe 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)paymentAcceptedY/N indication if the payment was completed successfully
transactionDateCurrent date
institutionIdAOThe institution ID
E.g. 01MY_INST
patronIdentifierAAthe patron id as received in the “fee paid” message

 

ServiceFieldIDDescription
Patron Information Request (63)languageThe language code
Should match the “self-check” profile in Alma
transactionDateCurrent date
SummarySupported 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)patronStatusSupported 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
languageThe language code
Ad defined on the “self-check” profile in Alma
transactionDateCurrent date
holdItemsCountNumber of Open Hold Requests exists for this patron
overdueItemsCountLoans that are overdue for this patron
chargedItemsCountNumber of loans for this patron
fineItemsCountNumber 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)
recallItemsCountnot supported
unavailableHoldsCountnot 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)transactionDateCurrent 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)Ok0/1 indication if renew was completed successfully
renewedCountnumber of renewed items
unrenewedCountnumber of items which were not renewed
transactionDateCurrent date
institutionIdAOThe institution ID
E.g. 01MY_INST

 

ServiceFieldIDDescription
Login (93)UIDAlgorithmnot supported
PWDAlgorithmhnot 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)ok1 if login successfully

 

ServiceFieldIDDescription
SC status (99)StatusCode0 – SC unit is OK
1 – SC printer is out of paper
2 – SC is about to shut down
maxPrintWidthThis is the maximum number of characters that the SC printer can print in one line
protocolVersion2.00
ACS Status (98)onLineStatus‘Y’
checkInOkAccording to the sef-check profile in Alma
checkOutOkAccording to the sef-check profile in Alma.
renewalPolicyAccording to the sef-check profile in Alma
statusUpdateOk‘N’
offlineOk‘N’
timeoutPeriodAccording to the sef-check profile in Alma
retriesAllowedAccording to the sef-check profile in Alma
dateTimeSyncAlma system date/time
protocolVersion2.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).