SIP2 manual (English)
General
Why do certain (self-services) vending machines have more features than others? Or even less in comparison with other vending machines? In this manual you'll find the possibilities and limitations of the SIP2-protocol.
International protocol for exchanging information
SIP2 is an international protocol for exchanging messages between vending machines and library systems. This protocol was developed by 3M (company). The main advantage of this protocol is that most vending-machine and library management software suppliers support this protocol.
However, the company 3M has stopped developing and supporting this protocol. A possible successor is NCIP, which is used by OCLC for - for example - the communication between Wise and the National Royal Library (KB).
SIP2 functionalities
SIP2 offers the following functionalities:
- Selling of depreciated items: when checking out a depreciated item, it is possible to sell it to the patron.
- When the patron checks out an already borrowed item, ask to confirm whether the patron wants to borrow the item again.
- Confirm that items have an attachment.
- Handling attachments as configured in Wise.
- Confirm items are damaged.
- Checking out damaged items as configured in Wise.
- Work with duplicate loan periods.
- Improved error handling.
- Improved design of receipts.
- Separate renewal dialog: see borrowed items, see if item can be renewed, what the new loan period will be and see the renew costs.
- Patron notifications: within Wise you can set individual or general notifications for a patron. These will be shown on a vending machine.
License for SIP2+ module
The functionalities above are available for SIP2-suppliers through a specific SIP2+ license. As these options only work if the software of the SIP2-supplier has been updated, libraries can only purchase these via the SIP2-suppliers.
In The Netherlands there are approximately ten providers of machines/services require communication with a library system via the SIP2 protocol. Wise has several possibilities for communicating with third-party machines/services using the SIP2-protocol. OCLC provides Wise through a licensing model to independent libraries, collaborating organizations and Provincial Service Organizations (called Contract partners). The Contract partner arranges the functional and physical access of the SIP2-machines to the OCLC Wise system (and associated licenses).
The contents and operation of the SIP2-protocol is based on the description by 3M (SIP2 Protocol Definition.pdf version 2.12 – April 2006). The SIP2-protocol defines the various messages and structure of these messages. The operations and usage of these messages is not described in the SIP2-protocol, therefore this manual will explain the practical usage and operations.
Besides the default operation and possibilities within the normal SIP2, OCLC has developed extensions for the protocol (called SIP2+). These extensions must be controlled from Wise and are expected to work within the SIP2 machine: the supplier must have updated the software of their SIP2-machines. Also, to be able to use the extensions the supplier must have enabled the SIP2+-licenses.
Capacity
OCLC advises their Contract partners about the needed server and network capacity. The loan number is an important factor in this advice. The extensions of the services and dialogs have an impact on the performances of the library system. Also, OCLC works under the assumption that the SIP2-suppliers make fair use of the granted access (by Contract partners) of the Wise system. The available capacity is tuned on the expected average usage.
To give the Contract partners an overview of the server load of SIP2-applictions, Wise counts the usage of SIP2-dialogs per branch each day on each port (machine) per dialog number. This way, Contract partners can decide for themselves what the load per SIP2-supplier is. For bigger Wise systems, Contract partners are advised to use a calculation-model where the SIP2-dialogs are included.
SIP2 suppliers
Every SIP2-supplier can be granted access to a Wise system. OCLC is not responsible for the consequences of the operations of the connected SIP2-machines and systems. The license agreement between OCLC and the Contract partner determines to which extent OCLC is responsible for the operations of the Wise systems.
Every SIP2-supplier has access to the default SIP2-dialogs. If the supplier wants to access the payment SIP2-dialogs, they should request a so-called SIP2-supplierscode from OCLC. There's a one-time fee attached to this request. OCLC will instruct and support the SIP2-supplier with configuring this code and logging into the Wise system. Using this code (and number), Wise can identify the SIP2-supplier. A suppliercode will be granted to a requester for the uses in the agreement. Transferring this code is not allowed.
OCLC has the rights to stop the support and operations of this code in case of abuse.
SIP2-suppliers that sign in with a supplier code are granted use of the payment SIP2 dialogs. Of course, the license will be checked. SIP2-suppliers with a code can request SIP2+. OCLC will charge an annual fee for this purpose (contact OCLC for the specifics). OCLC will instruct and support the supplier with configuring and usage of the additional SIP2+ functionality. The SIP2-licences must be activated by the SIP2-supplier for every branch that wants to use a payment terminal.
OCLC reserves the rights to stop the support and operations of SIP2+ in case of abuse or skipping the yearly payments of SIP2+.
Default SIP2-dialogs
From the default SIP2-protocol the following functions are supported:
| Dialog | Description |
|---|---|
|
Dialog 9/10 |
Checking in |
|
Dialog 11/12 |
Checking out |
|
Dialog 17/18 |
Item info |
|
Dialog 23/24 |
Patron status |
|
Dialog 29/30 |
Renewing |
|
Dialog 35/36 |
End of session |
|
Dialog 63/64 |
Patron information |
|
Dialog 65 /66 |
Renew every item |
|
Dialog 97 |
Retry request |
|
Dialog 93/94 |
Sign in / connect |
|
Dialog 99/98 |
Sign in |
SIP2 payment dialogs
For processing payments, OCLC has developed the following dialogs:
|
Dialog 37/38 |
Pay unpaid registrations |
|
Dialog 41/42 |
View paid registrations |
Usage of the dialogs depends on a few things:
- The SIP2-supplier should implement the SIP2 supplier code from OCLC correctly in the dialogs.
- The software of the SIP2-supplier must be able to process the functionality.
- The needed SIP2-licenses must be configured correctly for the library/branch/supplier.
SIP2-Plus (SIP2+)
Actually being able to deliver the SIP2+-functionality is dependent on the following:
- The SIP2-supplier should have implemented SIP2+ by OCLC (and therefore have paid for the license from OCLC).
- Besides that, the usage of SIP2+ is free for libraries.
- The software of the SIP2-supplier must be able to handle the functionality.
- The needed SIP2-licenses must be configured correctly for the library/branch/supplier.
SIP2+ has the following functionality:
- Selling of depreciated items: when checking out a depreciated item, it is possible to sell it to the patron.
- When the patron checks out an already borrowed item, ask to confirm whether the patron wants to borrow the item again.
- Confirm that items have an attachment.
- Handling attachments as configured in Wise.
- Confirm items are damaged.
- Checking out damaged items as configured in Wise.
- Work with duplicate loan periods.
- Improved error handling.
- Improved design of receipts.
- Paying for other patrons.
- Patron language.
- Separate renewal dialog: see borrowed items, see if item can be renewed, what the new loan period will be and see the renew costs.
- Patron notifications: within Wise you can set individual or general notifications for a patron. These will be shown on a vending machine.
See for more information the associated license.
SIP2-Licenses
The SIP2-machine receives access to the additional functionality using these licenses. The following extensions are available and can/must be activated per branch/machine:
ANONIEME_LENERS
-
This machine can be used anonymously (creating/depositing credit).
BETAAL
- Registrations can be paid using the indicated methods. Registrations can be viewed per type and per id (recno). Without this license, dialog 37 won’t be shown.
- Dialog 41 can also be shown (about paid registrations).
DUBBELE_LEENTERMIJN
-
Support for double loan periods.
GEBRUIKERSNAAM
-
Support for saving the username in dialog X1.
FAMILIE
-
Ability to see if other family members have unpaid registrations. These registrations will be shown in the field FM.
ITEM_LENER
- Showing the patron number in field AA in dialog 17/18 if the status of the item is U (loaned), R (on hold) or F (loaned to special patron).
- This license is supplier-independent.
LENERS_MELDINGE N
-
Showing patron notifications in the AF-field.
LEENSTRIPPEN
- Showing payment possibilities of punches and registering sold punches for patron (dialog Y1/Y2, Y3/Y4, Y5/Y6).
- For registering punches, the license BETAAL must be configured as well.
MACHTIGING
- Whether the library supports giving patrons permissions to let others pay unpaid registrations. With this license, this functionality is enabled.
- Showing in dialog 64/64 whether there are unpaid registrations for patrons where you are authorized to pay these registrations for. These are shown in the field FM.
MAKEN_BOEKINGEN
- Allow patrons to create a journal entry within Wise.
- This license is needed for dialog 39 (depositing/creating credit for anonymous users). If a machine only needs to create a journal entry without the ability to pay them, this license is sufficient. Else the license BETAAL is needed.
- The journal entry codes sent to Wise need to be known within the Wise system.
SORT_LIC
- Without this license, Wise will always use the deposits 01 - 04. Every item that can be placed on the shelfs will be placed in deposit 05. Only directly checking in items from patrons will be supported. For branches without this license and with a deposit for a temporary shelf, it will look at the filled deposit. Items from a route collection don’t receive status D but can be placed directly on the shelf. No deposit filled for the temporary shelf? Then it will use deposit 4.
- If this license is configured, all items will be placed in a deposit (no. 05-99) corresponding to the configured shelf when checking in (09/10). Wise will also handle the transport items. For dialog 17/18, it will also show the deposit number if the item is not loaned. If the item is loaned, it won’t show a deposit number.
- Dialog 43/44 (NBD-sorting) is only available in combination with this license.
- The license must be configured for each branch and is independent on the supplier. The license is also available for SIP2-suppliers without SIP2-supplierscode.
VERLENGMOGELIJKHEDEN
-
Support for dialog 70/71 where the renewing options are shown.
VEST_WISSEL
-
Whether the machine is able to send the branch number with journal entries. Can be used for a central machine for the purpose of internet regulation. To create a journal entry, the license ‘MAKEN_BOEKINGEN’ must be configured.
|
License |
Conditions |
Cost |
|---|---|---|
|
ANONIEME_LENERS |
VEST/LEV |
Pricelist |
|
BETAAL |
VEST/LEV |
Pricelist |
|
DUBBELE_LEENTERMIJN |
PLUS/VEST |
None |
|
GEBRUIKERSNAAM |
PLUS/VEST |
None |
|
ITEM_LENER |
VEST/LEV |
Pricelist |
|
LENERS_MELDINGEN |
VEST/PLUS |
None |
|
LEENSTRIPPEN |
VEST/LEV |
Pricelist |
|
MACHTIGING |
PLUS/VEST (from 6.3.2) |
None |
|
MAKEN_BOEKINGEN |
VEST/LEV |
Pricelist |
|
SORT_LIC |
VEST |
Pricelist |
|
VERLENGMOGELIJKHEDEN |
PLUS/VEST |
None |
|
VEST_WISSEL |
VEST/LEV |
Pricelist |
Conditions:
- PLUS = Supplier needs a SIP2+-license.
- PLUS/VEST = Supplier needs a SIP2+-license and the branch must have configured the license.
- VEST/LEV = Supplier needs to share the SIP2-supplierscode and the branch must have configured the license.
- VEST = The branch must have configured the SIP2-license.
The table above refers to a pricelist. This pricelist is included with the offer. The Wise-licensee can request the latest version of the pricelist.
This pricelist will only be sent to Wise-licensees. Other interested parties are referred to this licensee.
SIP2 Connection/response-times
Only SIP2-connections based on socket-connections are supported in Wise. The charset of the data sent is UTF-8. The names of patrons or item descriptions can contain special characters.
In the advice from OCLC about the server and network capacities, the aim is to have an acceptable response-time in the SIP2-dialogs. Here, response time is the same as the response time from the Wise system. For the most important dialogs (9/10, 11/12 and 63/64), one second is the maximum aimed response time. For the signing dialogs (93-99), the aimed response time is less than five seconds. For all other dialogs, the aimed response time is two seconds.
The real response time depends on the network and server load.
Description dialogs
General knowledge about the design and structure of SIP2-dialogs is required. Only the custom-developed functionality by OCLC (SIP2+) is described in this paragraph. The dialogs display a 'patron number' in several places: this is the patron's main card number. The descriptions will use both patron number and card number for this.
Dialog 41/42: View unpaid registrations
Request: field FA of FB of FC should contain a Y, for example FBY. Registrations with invoice status J are sent as well. The machine can decide whether it should show it or not. Also added to the response are:
- Description of the item
- Status: I=invoice, D=debt collection, R=payment arrangement
- Debt collection date, dd-mm-yyyy (with status D)
- Unique identifier of the item: adm_id
- Item type (1-contribution, 2-fines/contribution etc., 3-sales, 4-cash receipts, 6-theater)
- Date payment arrangement. Items with a filled date don’t have to be paid (with status R).
Fields are separated by a tilde instead of a dash.
Field 1 2 3 4 5 6 7 8 9 10
YZ-line: 14-03-2004 ~ Boete ~ ~ 10-03-2004 ~ 0.30 ~ ID ~ 01-10-2008 ~ 10 ~1~ - -
Structure:
| Field | Description |
|---|---|
|
Field 1 |
Creation date of item |
|
Field 2 |
Description of item |
|
Field 3 |
Title or description of journal entry code. |
|
Field 4 |
Date on which calculations are based (e.g. return date of the item) |
|
Field 5 |
Amount |
|
Field 6 |
Status: I=invoice, D=debt collection) Whether the registration is debt collected or if the registration will be paid by invoice. If there are unpaid membership fees, then the invoice status will be shown (when it's configured for a customer that an invoice authorization has been extended for collecting the membership fee). |
|
Field 7 |
Date on which the registration is sent to the debt collector. |
|
Field 8 |
Unique ID of the registration (can be used to pay registration) |
|
Field 9 |
Type |
|
Field 10 |
Date payment arrangement. |
Dialog 41/42: Show paid registrations
Fields are separated by a tilde instead of a dash.
YZ-line: 01-11-2009 ~ Registrations ~ 0.40 ~ Cash ~ Description
Dialog 37/38: Pay open registrations
Added: multiple id’s in field fee_identifier (CG), separated by '+'
CG<id>+<id>+<id>+
Example: CG2500+417+312+
These registrations are paid first. If there is money left, it will be added to the deposit of the patron.
Added: field ‘FX’
This field can be used to gather the payments in a way the payments can be linked to the correct journal. It’s a five-digit number and it is the SIP2-client's responsibility to provide Wise with this number – this number is generated by the SIP-client. A SIP2-client can for example use a session-number for each patron/day.
This number needs to be provided when increasing the deposit and when paying for fines and fees.
Example:
A patron has two outstanding fees, both 1.25 euro. The id’s of these fees are 464305 and 464306 (obtained by dialogue 41/42)
3720200117 1347060100EURBV1.25|AOWise|AA28340011105903|AC|AD|CG|BK|FX12345|FC1.25|AY1AZEAD4
3720200117 1347060101EURBV1.25|AOWise|AA28340011105903|AC|AD|CG|BK|FX12345|FC1.25|AY1AZEAD4
3720200117 1347060109EURBV2.50|AOWise|AA28340011105903|AC|AD|CG464305+464306+|BK|FX12345|FB2.50| AY1AZEAD4
Line 1: make deposit of 1,25. The payment type is cash (paymenttype 00), identification number is 12345 (field FX)
Line 2: make deposit of 1,25. The payment type is bank (paymenttype 01), identification number is 12345 (field FX)
Line 3: pay fees with id’s 464305 and 464306 using deposit (paymenttype 09) and make use of the deposit, done under identification number 12345 (field FX)
What happens in Wise:
Financial record 464305 will be closed and registered in journal Knnn
Financial record 464306 will be closed and registered in journal (Bnnn)
The temporary financial records (the added deposit), will be removed from the database. This is done to make sure they won’t affect the journal anymore. This method only works for deposits on the same day.
If the SIP2 client doesn’t supply the id’s, Wise will automatically start write off the oldest outstanding items until all credit of the patron is used. The id’s of outstanding items can be obtained with dialogue 41/42.
Dialog 63/64: View patron information
If the field FW has the value B, it will be interpreted as retrieving patron information for a payment terminal. In that case, the action won’t be cancelled if the patron has too many registrations. The following fields are sent besides the regular fields.
- Field FN: full patron name
- Field FM: card numbers for other patrons that the patron can pay registrations for.
- Field FO: username of the patron
- Field FU: statistical category of the patron, supplied if BETAAL or MAKEN_BOEKINGEN license is configured.
- Field LF: birthdate as yyyymmdd
- Field AK: for each loaned item: item number, name and return date (as dd-mm-yyyy). example: AK10000021028319 De Terugkeer – 22-03-2012|
For payment terminals with a SIP2+-license, the field FM contains the card numbers of other patrons that the current patron is permitted to pay registrations for. This requires LIC_MACHTIGING to be configured, and the patron needs te be authorized for payment. Card numbers of main/extra subscriptions will also be sent in this dialog.
Increasing and using credits
General workflow
The patron will be authenticated with dialog 63/64 and a pin will be checked (if used). In the response the field FeeLimit (CC) will be returned. This field contains the amount the patron can spend.
The FeeLimit is determined by:
- Total unpaid registrations
- Total credit (added to the patron's card)
- The configuration for the max negative amount a patron can have as credit
Spending limit in that case is (credit + max_negative) – unpaid registrations.
Unpaid membership fees don't affect the FeeLimit. The maximum negative amount is defined in the patron's membership definition. So, various patrons can have different spending limits.
In case the credit/spending limit is insufficient, the patron must increase his credits (deposit). This requires SIP2 dialog 37 which responds with the FeeLimit. After using a printer, browsing the internet, etc. dialog 39 reports to Wise how much of the credits were used. This is subtracted from the patron's deposit. Unused credits won’t be returned.
Negative amounts are not accepted.
Unknown users (in Wise) can’t deposit credits. Their use of facilities like printers etc. can be reported by creating a new dialog 39 where Payment Method Type is set and not equal to 09 (deposit).
Depositing for non-anonymous users
The patron must be known in Wise
Dialog: 37/38
Addition to the SIP2 protocol:
- Field FA,FB of FC to indicate what the money will be used for.
- FA – pay membership fees
- FB – pay registrations
- FC – increase credits
For this solution FC should be used.
Example request
3720091116 0910000000AA29444000001179|AOHKA-Testbibliotheek|BV10.00|FC10.00|AY2AZE1EF
Dialog 37
Transaction date: 16-11-2024 (09:10:00)
Fee type: 00 (unused)
Payment type: 00 (00-cash,01-visa,02-creditcard,03-chipknip)
Patron-id: 29444000001179
Amount: 10.00
Goal: increase credits (FC) with 10.00 euro
Payment method: cash
Tracking number dialog: 2
checksum: E1EF (fake in this example)
The amount is specified in the field BC and FC.
Example response
The standard SIP 38 response contains the new FeeLimit in field CC.
38Y20091116 091000AOHKA-Testbibliotheek|AA29444000001179|AFBetaling agreed|APPayment agreed|CC10.00|AY2AZE1EF
Dialog 38
Payment accepted: Y
Transaction date: 16-11-2009 (09:10:00)
Patron-id: 29444000001179
Current credit: 10.00
Tracking number dialog: 2
Checksum: E1EF (fictional example)
Use of credits for non-anonymous patrons or registering facility usage by anonymous patrons
Dialogs: 39/40
Request
39<transaction date><Patron Identifier><Fee amount><Fiscal Transaction Type><Payment Method Type>
The message will be closed by a sequence number and, if relevant, a checksum.
Response
40<payment accepted><Patron Identifier><dialog message><print line>
|
Field |
Code |
Format |
|---|---|---|
|
Transaction date |
18 pos. Required: YYYYMMDDZZZZHHMMSS |
|
|
Fee Amount |
BV |
Field of variable length, required, numeric format nnnnnn.nn (decimals after the period) |
|
Fiscal Transaction Type |
FH |
Field with a length of 4, required, contains the Wise journal entry code. Dialog will be rejected if the field is empty or if it does not exist in Wise. Only journal entry codes starting with 2,3 or 4 are accepted (2xxx,3xxx,4xxx). |
|
Patron Identifier |
AA |
Field of variable length, optional. If this field is used, the patron must be known in Wise. If the patron is unknown, the dialog will be rejected. If this field is omitted, the patron is anonymous. |
|
Payment Method Type |
FI |
Field with a length of 2, numerical. For known patrons 09 must be used. For anonymous patrons 09 cannot be used, and value should be 00, 01, 02 or 03. Payments with PIN should be 01 or 02 (bank). |
Patron passwords are not used; these happen in dialog 63/64.
Fee Amount
This amount can never be higher than the FeeLimit from dialog 63/64 or 37/38. All amounts are in euros.
Example request
3920091116 091000AA29444000001179|BV1.00|FH2910|FI09|AY3AZE1EF
Dialog 39
Transaction date: 19-03-2003 (09:10:00)
Patron-id: 29444000001179
Amount: 1.00
Action: Internet
Journal entry code: 2910
Payment method: deposit (patron is known)
Tracking number dialog: 3
checksum: E1EF (fictional example)
Example response
40Y20091116 091000AA29444000001179|AF1.00 euro paid|AG1.00 euro paid|CC9.00|AY3AZE1EF
Dialog 40
Payment accepted: Y
Transaction date: 16-11-2009 (09:10:00)
Patron-id: 29444000001179
Dialog notification: 1.00 euro paid
Print notification: 1.00 euro paid
Current limit: 9.00
Tracking number dialog: 3
Checksum: E1EF (fictional example)
Registering credits for anonymous patrons or patrons with a one-day card
The goal is to register credits that were used by an anonymous patron for the use of things like printers or internet access. The main idea is that this patron deposits credit in Wise, and Wise transforms this anonymous patron into a regular patron with a special patron number, which can be used to identify them. After this has happened, the patron can be treated as a regular patron and can increase their credits.
Dialog: 37/38
Addition to the SIP2 protocol: Field FC shows that it concerns increasing credits.
For anonymous users:
Field AA does not contain a patron number but shows **ANONIEM** instead.
For day card users:
Field AA does not contain a patron number but shows **DAGPAS** instead.
The difference between anonymous and one-day card patron is that day card patrons can only use the library facilities for a single a day. Each night the status of these patrons is set to 'bedankt' (status 9). If a pin code is used it will be stored with the anonymous patron. If the wants to increase their credits later, they need to use the same pin code.
Example request
3720180115 1347060000EURBV10.00|AA**ANONIEM**|AOHKA-Testlibrary|FC10.00|AY2AZE1EF
Dialog 37
Transaction date: 15-01-2018 (13:47:06)
Fee type: 00 (unused)
Payment type: 00 (00-cash,01-visa,02-creditcard,03-chipknip)
Patron-id: **ANONIEM**
Amount: 10.00
Goal: increase credits with 10eu
Payment method: cash
Tracking number dialog: 2
checksum: E1EF (fictional example)
Example for day card patrons:
3720180115 1347060000EURBV10.00|AA**DAGPAS**|AOHKA-Testbibliotheek|FC10.00|AY2AZE1EF
Dialog 37
Transaction date: 15-01-2018 (13:47:06)
Fee type: 00 (unused)
Payment type: 00 (00-cash,01-visa,02-creditcard,03-chipknip)
Patron-id: **DAGPAS**
Price: 10.00
Goal: increase credits with 10eu
Payment method: cash
Tracking number dialog: 2
checksum: E1EF (fictional example)
Some remarks:
The amount is sent in field BV and FC. Without FC this dialog won’t work. The payment type cannot be 09. This type is reserved for credits and credits can’t be purchased with credits.
Example response
The default SIP2 response is extended with the new limit in field CC (FeeLimit).
38Y20091116 091000AOOCLC-Test library|AA299970001012345|AFPayment agreed|AGPayment agreed|CC10.00|AY2AZE1EF
Dialog 38
Payment accepted: Y
Transaction date: 16-11-2009 (09:10:00)
Patron-id: 29997000101234. This is a generated number from the transformation from anonymous to regular patron.
New limit: 10.00
Tracking number dialog: 2
Checksum: E1EF (fictional example)
In any further communications the patron number generated here must be used.
This dialog will only work if the functionality is configured by OCLC.
Request payments
This extension is used for viewing payments. The payments are counted per date-type-payment method. Here the payments are counted for the same type and same payment method. Also this dialog can be used to get an overview of unpaid registrations.
Dialogs: 41/42
Request
41<transaction date><Patron Identifier><Date from><Date To><Payment Method Type><Debt type>
The message needs to be closed with a sequence number and a checksum.
|
Field |
Code |
Format |
|---|---|---|
|
Transaction date |
Length of 18, required: YYYYMMDDZZZZHHMMSS |
|
|
Patron Identifier |
AA |
Variable length, required. |
|
Payment Method Type |
FI |
Length of 2, numerical, 00 – cash, 01 – visa, 02 – credit card, 03 – chipknip, 09 – deposit. |
|
Date From |
FJ |
Required. Date from. The shown registrations are handled on or after this date. Format: dd-mm-jjjj |
|
Date To |
FK |
Required. Date to. The shown registrations should be handled before or on this date. Format: dd-mm-yyyy |
|
Debt type |
FA |
Which types should be shown. FA – Contributions, FB – registrations, FC – Deposit. 0, 1 or more can be shown in this dialog. If omitted, all types are shown. Using field FD, only unpaid registrations will be shown. If FA, FB or FC are added, these will be ignored. Field FG will only show the open amount of punches. This can’t be used in combination with other codes. |
Patron passwords are not used; these happen in dialog 63/64.
Field FD determines whether it concerns a 'debt' overview or not. If this is the case, use of Payment Method Type is not relevant and will be ignored.
Response
42[<YZmessage>|]
The non-existing field identifier YZ will be used here.
The response consists of one or more lines with the following structure:
YZDate ~ Type ~ Amount ~ Payment method|
Type can consist of:
Membership fee, registrations, deposit. This can be requested with the field ‘Debt. Type’ in the request. These cannot be requested together.
Payment method can be one of: cash, chip, bank (credit card).
Example request, show payments
4120091116 091000AA29444000001179|FJ01-11-2009|FK30-11-2009|FI00|FAY|AY3AZE1EF
or
4120091116 091000AA29444000001179|FJ01-11-2009|FK30-11-2009|FI00|FBY|AY3AZE1EF
or
4120091116 091000AA29444000001179|FJ01-11-2009|FK30-11-2009|FI00|FCY|AY3AZE1EF
Dialog 41
Transaction date: 16-11-2009 (09:10:00)
Patron-id: 29444000001179
Date from: 01-11-2009
Date to: 30-11-2009
Payment type: 00 (00-cash,01-visa,02-creditcard,03-chipknip)
Debt type: Membership fee or registrations or deposit
Tracking number dialog: 3
Checksum: AZE1EF
Example response
42YZ01-11-2009 ~ Registration ~ 10.00 ~ Cash ~ <description>|YZ01-11-2009 ~ Contribution ~ 15.00 ~ cash ~ <description>|AY3AZE1EF
Response 42
1st payment: 01-11-2009 ~ Registrations ~ 10.00 ~ Munt ~ description
2nd payment: 01-11-2009 ~ Contribution ~ 15.00 ~ Munt ~ description
Tracking number dialog: 3
Checksum: E1EF (fictional example)
Example request, request unpaid registrations
4120100310 091000AA29444000001179|FJ01-01-2009|FK31-12-2010|FDY|AY3AZE1EF
Dialog 41
Transaction date: 10-03-2010 (09:10:00)
Patron-id: 29444000001179
Date from: 01-01-2009
Date to: 31-12-2010
Debt type: Unpaid registrations
Tracking number dialog: 3
Checksum: AZE1EF
Example response
42YZ01-12-2009 ~ Adult 4155 E ~ Subscription ~ 01-01-2010 ~ 41.00 ~ J ~ - - ~ 382 ~ 1 ~ - -|YZ25-02-2010 ~ Damage ~ ~ 01-01-2010 ~ 4.00 ~ ~ - - ~ 393781 ~ 4 ~ 01-04-2010|YZ05-03-2010 ~ Replaced card ~ ~ 05-03-2010 ~ 3.00 ~ ~ - - ~ 393831 ~ 2 ~ - -|AY0
Dialog 42
1st line : 01-12-2009 ~ Adult 4155 E ~ ~ 01-01-2010 ~ 41.00 ~ J ~ - - ~ 382 ~ 1 ~ - -
field 1: 01-12-2009: creation date registration
field 2: Adult 4155 E : description registration
field 3: <empty> : title (empty for membership rules)
field 4: 01-01-2010 : start date membership
field 5: 41.00 : amount
field 6: Y : will be collected by automatic invoice
field 7: - - : date sent to debt collector
field 8: 382 : identifier
field 9: 1 : type of payment, see below for definitions
field 10: - - : date for payment regulation, does not have to be paid before this date
2nd line : 25-02-2010 ~ Damage ~ ~ 01-01-2010 ~ 4.00 ~ ~ - - ~ 393781 ~ 4 ~ 01-04-2010
3rd line : 05-03-2010 ~ Replaced card ~ ~ 05-03-2010 ~ 3.00 ~ ~ - - ~ 393831 ~ 2 ~ - -
Tracking number dialog : 0
Types of payment:
|
1 |
Membership fees |
|
2 |
Registrations |
|
3 |
Store sales |
|
4 |
Other revenue |
Example request, request punches
4120091116 091000AA20105000000011|FGY|AY3AZE1EF
Dialog 41
Transaction date: 16-11-2009 (09:10:00)
Patron-id: 20105000000011
Debt type: Punches
Tracking number dialog: 3
Checksum: AZE1EF
Example response
42FGBookpunches~35|FGPunches-2~75|FGPunches3~Ransomed|AY3AZE1EF
Dialog 42
1st line: Book punches, 35 times
2nd line: Punches3, 75
3rd line: Punches3, ransomed
Tracking number dialog: 3
Checksum: E1EF (fake)
Punches
Only works if the license is activated.
Request possibilities for punch purchase, dialog Y1/Y2
Dialog Y1 can be used to request the purchasable types of punches. The dialog should show the patron number and the punches.
Request: Y1
Y120091116 091000AA20105000000011|AY3AZE1EF
Field AA contains the patron number.
Response:
Y21[FGType ~ Code ~ Description ~ Amount ~ Price|]AF<Text>|seq.n0
If the request could not be processed, the status is 0 (Y20).
Request to purchase punces, Dialog Y3/Y4
Request Y3
Example:
Y320161116 091000AA20105000000011|FG01-40-15.75-4810 ~ 02-35-13.25-4810|FI00|AY0000
Field AA contains: patron number
Field FG contains: type - amount - price - journal entry code
Field FI: payment type
The various items are separated by a tilde.
Attention: the type of punch card originates from dialog Y1. There, it contains a description that can be shown on the dialog.
Response:
Y4[1/0]AF<notifications>
1=ok, 0 = not ok, field AF contains an explanation.
Double loan period
Only works if the license is activated.
Field FE in dialog 11 can only be used to indicate that the patron would like a double loan period, the value must be Y. This can be used for checking out and renewing (dialog 11 and 29 respectively).
Request family members
Only works if the license is activated.
Dialog 63/64 is extended with field FM. This field contains the (main) card number, name, unpaid membership fees, unpaid registrations and open deposits.
The structure is:
[FM<patron number> ~ <name> ~ <contribution> ~ <registrations> ~ <deposit>|]
Request/save username
Only works if the license is activated.
Dialog X1/X2 can be used to register the username of an anonymous patron.
The structure is:
X1<FO<username>|AA<patron number>|AD<pin code>
Example:
X1FPjan12345|AA20105000000011|AD1234
Response:
X2<status>|AA<patron number>|FO<username>|AF<text>
Status:
0 – Ok
1 – Not ok
Which licenses are activated?
Dialog 98 shows which licenses are activated for the SIP2 client:
98YYYYYY30000320110201 1138402.00AO|BXYYYYYYNYYYYNNNYY|AMBibl.Test|GGLIC_SORTEER / LIC_BETAAL / LIC_MAKEN_BOEKINGEN / LIC_VERLENGMOGELIJKHEDEN|AFWelcome <machine>|AY1AZD052
The machine in the example has the following licenses activated:
- SORTEER
- BETAAL
- MAKEN_BOEKINGEN
- VERLENGMOGELIJKHEDEN
SIP2+
Besides the options above, a supplier can activate the following options using SIP2+ by OCLC.
- Selling of depreciated items: when checking out a depreciated item, it is possible to sell it to the patron.
- When the patron checks out an already borrowed item, ask to confirm whether the patron wants to borrow the item again.
- Confirm that items have an attachment.
- Confirm items are damaged.
In the cases above, the patron must confirm something before the loan/sale will be processed. These notifications are shown in field FV. By assigning this field in the request with the value Y, the confirmation will be processed.
The system option LEENHIS must be set before the machine can show the previously loaned items. Wise can indicate the support for each port (machine).
If the SIP+ license is not activated:
- Depreciated items cannot be sold
- Field FV contains the date when the patron has previously borrowed the item. The loan is already processed by then.
- Materials with an attachment are loaned as set in the settings of Wise. Either way, the loan is already processed then.
- Damaged items are able to be loaned.
Example:
Without confirmation:
11YN20110905 09301320110905 093013|AO|AA28340011105903|AB10000021028319|BON|BIN|AY1
Response:
120NNN20110905 092633AOBibl.8340|AA28340011105903|AB10000021028319|AJDe Terugkeer van de dansleraar|AH|BHEUR|BV0.00|BK0|ST0|FVPreviously loaned on: 26-08-2011|AY1
With confirmation:
11YN20110905 09301320110905 093013|AO|AA28340011105903|AB10000021028319|BOY|FVY|BIN|AY1
Response:
121NNY20110905 093013AOBibl.8340|AA28340011105903|AB10000021028319|AJDe Terugkeer van de dansleraar|AH26-09-2011|BHEUR|BV0.10|BK4|ST0|AFUitlening akkoord|AFEUR. 0.10 Leengeld|FQ0337|FQ0342|AGLeengeld|AGEUR. 0.10 Leengeld|AY1
Request renewal possibilities
Only works if the license is activated.
Dialog 70/71 is available for requesting the possibilities to renew specific items.
Request:
7020110907 092600|AA28340011105903|AB|AY1
Response:
71GC8340450365719~Het schateiland : een oud verhaal van R.~11-11-2011~12-12-2011~0.00~0.15~0~0.00~|GC8340450371998~Brandt New York?~28-09-2011~26-10-2011~0.00~0.15~0~0.00~|GC8340450372020~Roebels voor de generaal / Tais Teng ; t~25-07-2011~05-10-2011~4.30~0.15~0~0.00~|GC8340450372053~De wraak van Rachwana / Peter Vervloed ;~25-07-2011~05-10-2011~4.30~0.15~0~0.00~|GC8340450372079~Kinderen gezond grootbrengen : wegwijzer~02-05-2011~05-10-2011~7.50~0.15~0~0.00~|FG0|AY1
Fields are separated by a tilde.
Field 1 2 3 4 5 6 7 8 9
GC-regel: 8340450365719~Het schateiland : een oud verhaal van R.~11-11-2011 ~ 12-12-2011 ~ 0.00 ~ 0.15 ~ 0 ~ 0.00 ~|
Structure:
| Field | Description |
|---|---|
|
Field 1 |
Item number |
|
Field 2 |
Title |
|
Field 3 |
Current return date |
|
Field 4 |
New return date (if renewing is allowed) |
|
Field 5 |
Fine if too late |
|
Field 6 |
Loan costs |
|
Field 7 |
Punches count |
|
Field 8 |
Renewal costs |
|
Field 9 |
Remarks |
Processing attachments with SIP2
Wise can process attachments in different ways. Important for this to work:
- For each machine, the self service settings must be set in Wise (ZUSprofiel / SSS profile).
- Each supplier has different settings for handling attachments.
- Some suppliers can communicate with Wise using SIP2+.
- The way the attachments are registered for an item:
- The main item and attachment have its own RFID-tag
- The main item contains the number of attachments in its RFID-tag.
Based on the settings and possibilities, attachments are handled in several different ways.
Settings of the machine
The settings differ for each supplier/machine. The following settings can be configured one way or another for each supplier:
- Block checking out / checking in if the item is incomplete according to the RFID-tags.
- Have the patron confirm that the item contains attachments if the RFID-tag of the main item indicates that it should contain multiple attachments. The loan/return is continued based on the answer of the patron.
Self service settings
In self service system settings (ZUSprofiel) you can configure the following settings:
- Items with attachments can be borrowed (Y/N)
- Items with attachments can be returned (Y/N)
(if the item contains an attachment code in Wise)
| Option | Description |
|---|---|
|
N = Not |
Wise will block the return. |
|
T = Table |
The attachment code table (TABBIJ) contains information whether an attachment can block returning for each different code. If the table returns true for a specific code and the machine supports this functionality (SIP2+), the dialog with the confirmation will be shown. If the machine does not support this functionality or the table return false, the return will be blocked. |
|
A = Always |
An attachment won’t block the return. |
Sorting
When checking in items (dialog 9/10), Wise will decide whether the item can be placed back on the shelfs immediately or not. If there is a reason when it can’t be placed back immediately, Wise will show this reason in field CL.
01 = Hits
02 = Reservations
03 = Transport
04 = Warehouse / blocked
Items with blocking reasons must always get status D (not-sorted). These items need to be checked in in the Wise Client. When items can be placed back immediately, the item will get the status B (inside) and field CL will have the value 05.
If the library sorts items with status B, the sorting license must be enabled for the specific branch.
Based on the placement in the library, this functionality will determine how this item should be sorted. The values 06 up to and including 99 are available for different sorting deposits. This value will be communicated using the field CL. If this sorting takes place physically, the machine translates this value to the right deposit.
Above is a broad description of the sorting functionality. Besides these possibilities, the following is available as well:
- Determine depositing bin number per item
- Determine depositing bin number based on target branch (transport)
- Possibility to show additional notifications for each material type.
These possibilities should be discussed with the system administrator.
Sending e-mails from SIP2
It is possible to send an e-mail to a patron from a SIP2 machine. Wise provides a default email address in the SIP2 protocol. The email address will be sent in the field BE (dialog 63/64).
SIP2 Two-Factor Authentication (2FA)
You can enable 2FA for adding SIP2 machines in the Wise Manager. Go to Port and profile management > Profiles > Self Service System (SSS) profiles. Select the profile for which you want to configure 2FA must be configured or create a new profile. 2FA is enabled by providing a number in the field ‘2FA token valid’; you configure the duration for which a token is valid.
Optionally: bind a machine to an IP-address. If the IP-address of the machine is not the same as the IP-address of the server, the machines have to go through the authentication process again.
Configuring the email address that receives the One Time Password (OTP)
Wise > Management organizations > Branches > (select a branch) > tab Address details
Fill an e-mail address for ‘Email 2-factor authentication’. If necessary, a carbon copy of this email can be sent to an additional email address by configuring the 'CC 2-factor authentication'. After configuring these settings, an e-mail will be sent to these addresses each time a new SIP2 machine is added. This One Time Password is only valid for 30 minutes and will be saved in the Wise Manager (Wise > Port and profile management > Ports > Sip2 Two Factor Authentication).
The messages containing a One Time Password are so-called PCC-messages. For more information see Publieksberichten (Berichtklasse P).
Handling status D items for 'intelligente kasten'
Items with a hold that are checked in by a customer through a SIP2 machine receive status D (sorted item). Usually these items have to be prepared for the hold shelf through the Wise Client. This step can be simplified using the 'intelligente kast' (smart shelf) functionality.
This functionality allows the items to be placed directly on the smart shelf, which makes them 'hold ready' without having to use the Wise Client. This only applies to items that have been placed on hold in the branch where they were checked out: if the items need to be placed on transport, the smart shelf will decline the items and will show an appropriate error message. You can use this functionality by added the field DR to the 09 dialog:
- If the field DRY is provided in the SIP2 check in request, the server will process the hold the same way as when check in the item through the Wise Client.
- If the field DR is not provided in the SIP2 check in request, then this will be considered DRN.
- If the field DRN is provided in the SIP2 check in request, then checking in the item will be processed according to the behavior of the self service machine.
- You don't need any extra settings, licences or system options for this functionality.
Extra details about the DR field:
Current situation
Option 1
Customer checks in an item with a hold at a SIP2 machine:
- The item receives status D.
- The SIP response contains the exceptions/alternative bin as configured in the ZUSprofiel (02 by default).
Option 2
Staff member checks in the item through the Wise Client:
- If there's a hold that is processed in the current branch:
- The item receives status R.
- Emails etc are sent out.
- The item gets placed on a regular hold shelf.
- If there is no hold being processed in the current branch (item has status D because - for example - it needs to be placed on transport):
- The Wise Client returns a notification.
DRN
Option 1
Customer checks in an item with a hold at a SIP2 machine:
- The item receives status D.
- The SIP response contains the exceptions/alternative bin as configured in the ZUSprofiel (02 by default).
Option 2
Someone checks in an item with status D using a SIP2 client:
- If there's a hold that is processed in the current branch:
- An error notification appears.
- If there is no hold being processed in the current branch (item has status D because - for example - it needs to be placed on transport):
- An error notification appears.
DRY
Option 1
Customer checks in an item with a hold at a SIP2 machine:
- The item receives status D.
- The SIP response contains the exceptions/alternative bin as configured in the ZUSprofiel (02 by default).
Option 2
Staff member checks in the item using a smart shelf (SIP2):
- If there's a hold that is processed in the current branch
- The item receives status R.
- Emails etc are sent out.
- The item gets placed on the smart hold shelf.
- The SIP response contains the exceptions/alternative bin as configured in the ZUSprofiel (02 by default).
- If there is no hold being processed in the current branch (item has status D because - for example - it needs to be placed on transport):
- The check in is declined.
SIP2 over HTTPS
SIP2 machines can communicate over HTTPS. The advantages of HTTPs is that it does not require any configuration in the HostedWise routing or in branches like schools or small libraries. Furthermore, the communication is encrypted. SIP2 over HTTPS is plug and play, so no additional configuration to the network is needed.
The password should be 16 to 20 characters, consisting of letters, numbers and/or @$%^&+=-". There is no filter on IP address for SIP2 HTTPS requests, which means SIP2 is available from any public internet connection. Therefore it is important that user/login/url information is handled carefully.
The password can be set up in the Wise Manager > systemWise > Access codes and authorizations > Access authorizations > tab Users. By searching for “name (with role)”, the Wise user of the SIP2 port can be found (put 'machine' or 'actor' as a prefix for the access code of the port; for example 'actor-PAY1234'). Find the right port in the search results and select it. In the section above, the password can be set at 'Manager login code + https client'.
The url that is used to communicate is:
https://[WISE-URL]/sip2https/services .
To check whether the URL is correct, you can open the URL in the browser of your computer; if you see the following text, the URL is correct:
{"error":"Method not allowed"}
JSON request and response
The sip2https tool offers a means to tunnel clear-text SIP2 commands and replies through secured HTTPS. Each SIP2 command is wrapped in a JSON object and accompanied by a token. This token serves to identify the authenticity of the request.
Below is an example request- and response-pair. Note that initially the token (sent by the client together with a 93 request) will be empty. The server will supply a token after successful login. From that point on the client must issue the last received token on each subsequent request.
JSON Request example:
{
"sip2request":"6300020071001AO|AA21234002896242|ACxyzzy|AD1234|AY3AZEF37",
"token":"rqYtfjBBMOqK+fK7yW0Z1TSyCJ8"
}
JSON Response example:
{
"sip2response":"64Y83838383838AOWisecity|AA21234002896242|AE|BLN|CQY|BHEur|BV0.00|FB0.00|FC0.00|AY3AZBFDE"
"token":"rqYtfjBBMOqK+fK7yW0Z1TSyCJ8"
}
Notes for the (client side) implementation
The sip2https service has a base URL of the format:
https://<hostname>/sip2https/services and accepts only POST requests.
POST-ed data should be op Content-type application/json. Encoding is UTF-8.
For security reasons the SIP service requires a password (CO subfield of command 93) with a length of at least 16 characters. This password must be different from the username (CN subfield).
In a REST-like fashion, the service makes use of HTTP-status codes and error messages for error situations. Status 200 indicates a successful command, status codes in the 4XX series are used for different errors.
In case of Authentication failures, the service increments a failure counter per (client) IP address. When the failure counter reaches a certain predefined limit (typically 10) the IP address will be blocked from accessing the service for a certain predetermined period (typically 1 hour) to defend against abuse. A successful login resets the counter.
The token that is provided after a successful login will expire after a certain amount of idle time (typically 2 hours). If the client makes use of an expired token the server will respond with 401 Unauthorized. A reset of the server may also trigger timeout of a token.
Implementors should automatically re-login (93) in such cases.
Installation notes
sip2https is a CGI script that runs in the same environment as the Wisecat+, i.e. under Apache with mod_perl, and is deployed from the wise-bxmcgi package. Since it is deployed in a different directory (sip2https and not cgi-bin) there are specific ScriptAlias and Allow rules needed to allow functioning within the Apache environment. To enable, the following config should be included with the Apache config associated with the SSL (HTTPS) config:
ScriptAlias /sip2https/services /home/bng/sip2https/sip2https.pl
<Directory /home/bng/sip2https>
SetHandler perl-script
PerlHandler ModPerl::Registry
Options +ExecCGI
PerlOptions +ParseHeaders
Require all granted
</Directory>
Note that it is the responsibility of the host to ensure that this script is only reachable via HTTPS and not via standard HTTP. The script itself does not enforce this (nor has the means to do that). The SSL connection is supposed to be handled by Apache or some other network component (e.g. a firewall) at the hosing side and this is out of scope for the sip2https script. (This script merely relays commands.)
This script makes use of the cache that is available on the Wise web server. By default this is a File-system based cache in tmp/FileCache/sip2https. Like with the CGI Wisecat+, a hazelcast or other memcached protocol capable object store can be used as well. The script stores the failure counters, blocking information and some session state there.
Additional configuration
Checking out and checking in
For checking out and checking in, the field CK will contain the material type of the item. For the machine, the material type can be the motivation to open the locker.
The response for checking out contains the field BV (Fee) and the field ST. The field ST shows the number of punches needed for a loan. Field BV does not show number of punches, but only the amount of money.
Field FR becomes FRY if the item has the status B (available) but is checked in again at the machine.
This process is available for every type of SIP2 machine.
Message numbers (notifications)
For each SIP-response that requires a notification to be shown, the field FQ contains a message number with a length of 4 numbers.
Configuration notes
It is advised to hand out hard passwords to the SIP2 clients. The minimal length is 16 characters. The advise is to make us of some random string generator for this. Thi functionality will eventually be provided in the Wise Manager.
Configuration of the script takes place in /etc/bng.d/sip2https.conf. Minimal contents are (*):
$cfg = {
'CONN' => {
'WISEURL' => 'http://wiseas/bxmas',
},
'DEBUG' => 3,
};
1;
DEBUG level 4 is the minimum that is advised, as this still gives warnings and some statistics. The following options exist for modifying "failure counter" behavior:
$cfg->{'CONN'}{'MAX_TRIES_PER_IP'} with a default of 10
$cfg->{'CONN'}{'BLOCK_TIME'} with a default of '60m' (60 minutes)
(*) without a config file these defaults will be used