4 indexterm:[Automated Circulation System]
6 indexterm:[Automated Material Handling]
8 +SIP+, standing for +Standard Interchange Protocol+, was developed by the +3M corporation+ to be a common
9 protocol for data transfer between ILS' (referred to in +SIP+ as an _ACS_, or _Automated Circulation System_) and a
10 third party device. Originally, the protocol was developed for use with _3M SelfCheck_ (often abbreviated SC, not to
11 be confused with Staff Client) systems, but has since expanded to other companies and devices. It is now common
12 to find +SIP+ in use in several other vendors' SelfCheck systems, as well as other non-SelfCheck devices. Some
15 * Patron Authentication (computer access, subscription databases)
16 * Automated Material Handling (AMH)
17 ** The automated sorting of items, often to bins or book carts, based on shelving location or other programmable
20 Installing the SIP Server
21 ~~~~~~~~~~~~~~~~~~~~~~~~~
25 This is a rough intro to installing the +SIP+ server for Evergreen.
30 Current +SIP+ server code lives at in the Evergreen git repository:
33 git clone git://git.evergreen-ils.org/SIPServer.git SIPServer
36 Configuring the Server
37 ^^^^^^^^^^^^^^^^^^^^^^
39 indexterm:[configuration files, oils_sip.xml]
41 . Type the following commands from the command prompt:
45 $ cp oils_sip.xml.example oils_sip.xml
47 . Edit oils_sip.xml. Change the commented out <server-params> section to this:
56 . max_servers will directly correspond to the number of allowed +SIP+ clients. Set the number accordingly, but
57 bear in mind that too many connections can exhaust memory. On a 4G RAM/4 CPU server (that is also running
58 evergreen), it is not recommended to exceed 100 +SIP+ client connections.
63 indexterm:[configuration files, oils_sip.xml]
65 . Type the following commands from the command prompt:
70 . In the +<accounts>+ section, add +SIP+ client login information. Make sure that all +<logins>+ use the same
71 institution attribute, and make sure the institution is listed in +<institutions>+. All attributes in the
72 +<login>+ section will be used by the +SIP+ client.
74 . In Evergreen, create a new profile group called +SIP+. This group should be a sub-group of +Users+ (not +Staff+
75 or +Patrons+). Set _Editing Permission_ as *group_application.user.sip_client* and give the group the following
83 VIEW_COPY_CHECKOUT_HISTORY
86 VIEW_USER_FINES_SUMMARY
87 VIEW_USER_TRANSACTIONS
92 INSERT INTO permission.grp_tree (name,parent,description,application_perm)
93 VALUES ('SIP', 1, 'SIP2 Client Systems', 'group_application.user.sip_client');
96 permission.grp_perm_map (grp, perm, depth, grantable)
100 permission.grp_tree g,
101 permission.perm_list p
109 'VIEW_COPY_CHECKOUT_HISTORY',
110 'VIEW_PERMIT_CHECKOUT',
112 'VIEW_USER_FINES_SUMMARY',
113 'VIEW_USER_TRANSACTIONS'
120 FROM permission.grp_perm_map pgpm
121 INNER JOIN permission.perm_list ppl ON pgpm.perm = ppl.id
122 INNER JOIN permission.grp_tree pgt ON pgt.id = pgpm.grp
123 WHERE pgt.name = 'SIP';
127 . For each account created in the +<login>+ section of oils_sip.xml, create a user (via the staff client user
128 editor) that has the same username and password and put that user into the +SIP+ group.
132 The expiration date will affect the +SIP+ users' connection so you might want to make a note of this
139 To start the +SIP+ server type the following commands from the command prompt:
144 $ oils_ctl.sh -a [start|stop|restart]_sip
158 It is useful to log +SIP+ requests to a separate file especially during initial setup by modifying your syslog config file.
162 $ sudo vi /etc/syslog.conf # maybe /etc/rsyslog.conf
167 local6.* -/var/log/SIP_evergreen.log
169 . Syslog expects the logfile to exist so create the file.
171 $ sudo touch /var/log/SIP_evergreen.log
175 $ sudo /etc/init.d/sysklogd restart
181 indexterm:[syslog-NG]
183 . Edit logging config.
185 sudo vi /etc/syslog-ng/syslog-ng.conf
189 # +SIP2+ for Evergreen
190 filter f_eg_sip { level(warn, err, crit) and facility(local6); };
191 destination eg_sip { file("var/log/SIP_evergreen.log"); };
192 log { source(s_all); filter(f_eg_sip); destination(eg_sip); };
194 . Syslog-ng expects the logfile to exist so create the file.
196 $ sudo touch /var/log/SIP_evergreen.log
200 $ sudo /etc/init.d/syslog-ng restart
206 Testing Your SIP Connection
207 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
209 * In the root directory of the SIPServer code:
213 * Edit SIPtest.pm, change the $instid, $server, $username, and $password variables. This will be
214 enough to test connectivity. To run all tests, you'll need to change all the variables in the _Configuration_ section.
216 $ PERL5LIB=../ perl 00sc_status.t
218 This should produce something like:
222 ok 1 - Invalid username
223 ok 2 - Invalid username
227 * Don't be dismayed at *Invalid Username*. That's just one of the many tests that are run.
232 . Once you have opened up either the +SIP+ OR +SIP2+ ports to be accessible from outside you can do some testing
233 via +telnet+. You can try this with localhost if you so wish, but we want to prove that +SIP2+ works from
234 non-localhost. Replace +$instid+, +$server+, +$barcode+, +$username+, and +$password+ variables below
238 ======================
239 We are using 6001 here which is associated with +SIP2+ as per our configuration.
240 ======================
242 $ telnet $server 6001
243 Connected to $server.
244 Escape character is '^]'.
245 9300CN**$username**|CO**$password**|CP**$instid**
251 . Now just copy in the following line (with variables replaced) you don't need to hit enter, just paste!
253 2300120080623 172148AO**$instid**|AA**$barcode**|AC$password|AD**$password**
255 You will get back the patron information for $barcode (something similar to the what's below).
257 24 Y 00120100113 170738AEFirstName MiddleName LastName|AA**$barcode**|BLY|CQY
258 |BHUSD|BV0.00|AFOK|AO**$instid**|
260 The response declares it is a valid patron BLY with a valid password CQY and shows the user's +$name+.
268 indexterm:[SIP Server, SIP Communication]
270 +SIP+ generally communicates over a +TCP+ connection (either raw sockets or over +telnet+), but can also
271 communicate via serial connections and other methods. In Evergreen, the most common deployment is a +RAW+ socket
272 connection on port 6001.
274 +SIP+ communication consists of strings of messages, each message request and response begin with a 2-digit
275 ``command'' - Requests usually being an odd number and responses usually increased by 1 to be an even number. The
276 combination numbers for the request command and response is often referred to as a _Message Pair_ (for example,
277 a 23 command is a request for patron status, a 24 response is a patron status, and the message pair 23/24 is patron
278 status message pair). The table in the next section shows the message pairs and a description of them.
280 For clarification, the ``Request'' is from the device (selfcheck or otherwise) to the ILS/ACS. The response is… the
281 response to the request ;).
283 Within each request and response, a number of fields (either a fixed width or separated with a | [pipe symbol] and
284 preceeded with a 2-character field identifier) are used. The fields vary between message pairs.
286 |===========================================================================
287 | *Pair* | *Name* | *Supported?* |*Details*
288 | 01 | Block Patron | Yes |<<01_block_patron, 01/Block_Patron>> - ACS responds with 24 Patron Status Response
289 | 09-10 | Checkin | Yes (with extensions) |<<09-10_checkin, 09/10_Checkin>>
290 | 11-12 | Checkout | Yes (no renewals) |<<11-12_checkout, 11/12_Checkout>>
291 | 15-16 | Hold | Partially supported |<<15-16_hold, 15/16_Hold>>
292 | 17-18 | Item Information | Yes (no extensions) |<<17-18_item_information, 17/18_Item_Information>>
293 | 19-20 | Item Status Update | No |<<19-20_item_status_update, 19/20_Item_Status_Update>> - Returns Patron Enable response, but doesn't make any changes in EG
294 | 23-24 | Patron Status | Yes |<<23-24_patron_status, 23/24_Patron_Status>> - 63/64 ``Patron Information'' preferred
295 | 25-26 | Patron Enable | No |<<25-26_patron_enable, 25/26_Patron_Enable>> - Used during system testing and validation
296 | 29-30 | Renew | Yes |<<29-30_renew, 29/30_Renew>>
297 | 35-36 | End Session | Yes |<<35-36_end_session, 35/36_End_Session>>
298 | 37-38 | Fee Paid | Yes |<<37-38_fee_paid, 37/38_Fee_Paid>>
299 | 63-64 | Patron Information | Yes (no extensions) |<<63-64_patron_information, 63/64_Patron_Information>>
300 | 65-66 | Renew All | Yes |<<65-66_renew_all, 65/66_Renew_All>>
301 | 93-94 | Login | Yes |<<93-94_login, 93/94_Login>> - Must be first command to Evergreen ACS (via socket) or +SIP+ will terminate
302 | 97-96 | Resend last message | Yes |<<97-96_resend, 97/96_Resend>>
303 | 99-98 | SC-ACS Status | Yes |<<99-98_sc_and_acs_status, 99/98_SC_and_ACS_Status>>
304 |===========================================================================
306 anchor:01_block_patron[]
311 indexterm:[SelfCheck]
313 A selfcheck will issue a *Block Patron* command if a patron leaves their card in a selfcheck machine or if the
314 selfcheck detects tampering (such as attempts to disable multiple items during a single item checkout, multiple failed
317 In Evergreen, this command does the following:
319 * User alert message: _CARD BLOCKED BY SELF-CHECK MACHINE_ (this is independent of the AL _Blocked
320 Card Message_ field).
322 * Card is marked inactive.
324 The request looks like:
326 01<card retained><date>[fields AO, AL, AA, AC]
328 _Card Retained_: A single character field of Y or N - tells the ACS whether the SC has retained the card (ex: left in
331 _Date_: An 18 character field for the date/time when the block occurred.
333 _Format_: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, ``Z'' (3 blanks and a Z)
334 represents UTC(GMT/Zulu)
336 _Fields_: See <<fields, Fields>> for more details.
338 The response is a 24 ``Patron Status Response'' with the following:
340 * Charge privileges denied
341 * Renewal privileges denied
342 * Recall privileges denied (hard-coded in every 24 or 64 response)
343 * hold privileges denied
344 * Screen Message 1 (AF): _blocked_
347 anchor:09-10_checkin[]
352 ~The request looks like:
354 09<No block (Offline)><xact date><return date>[Fields AP,AO,AB,AC,CH,BI]
356 _No Block (Offline)_: A single character field of _Y_ or _N_ - Offline transactions are not currently supported so send _N_.
358 _xact date_: an 18 character field for the date/time when the checkin occurred. Format:
359 YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, ``Z'' (3 blanks and a Z) represents
362 _Fields_: See <<fields, Fields>> for more details.
364 The response is a 10 ``Checkin Response'' with the following:
366 10<resensitize><magnetic media><alert><xact date>[Fields AO,AB,AQ,AJ,CL,AA,CK,CH,CR,CS,CT,CV,CY,DA,AF,AG]
368 Example (with a remote hold):
370 09N20100507 16593720100507 165937APCheckin Bin 5|AOBR1|AB1565921879|ACsip_01|
372 101YNY20100623 165731AOBR1|AB1565921879|AQBR1|AJPerl 5 desktop reference|CK001|CSQA76.73.P33V76 1996
373 |CTBR3|CY373827|DANicholas Richard Woodard|CV02|
375 Here you can see a hold alert for patron CY _373827_, named DA _Nicholas Richard Woodard_, to be picked up at CT
376 ``BR3''. Since the transaction is happening at AO ``BR1'', the alert type CV is 02 for _hold at remote library_. The
377 possible values for CV are:
385 * 03: ILL transfer (not used by EG)
391 indexterm:[magnetic media]
395 The logic for Evergreen to determine whether the content is magnetic_media comes from either legacy circ
396 scripts or search_config_circ_modifier. The default is non-magnetic. The same is true for media_type (default
397 001). Evergreen does not populate the collection_code because it does not really have any, but it will provide
398 the call_number where available.
400 Unlike the +item_id+ (barcode), the +title_id+ is actually a title string, unless the configuration forces the
401 return of the bib ID.
403 Don't be confused by the different branches that can show up in the same response line.
405 * AO is where the transaction took place,
407 * AQ is the ``permanent location'', and
409 * CT is the _destination location_ (i.e., pickup lib for a hold or target lib for a transfer).
412 anchor:11-12_checkout[]
423 Evergreen supports the Hold message for the purpose of canceling
424 holds. It does not currently support creating hold requests via SIP2.
427 anchor:17-18_item_information[]
429 17/18 Item Information
430 ^^^^^^^^^^^^^^^^^^^^^^
432 The request looks like:
434 17<xact_date>[fields: AO,AB,AC]
436 The request is very terse. AC is optional.
438 The following response structure is for +SIP2+. (Version 1 of the protocol had only 6 total fields.)
440 18<circulation_status><security_marker><fee_type><xact_date>
441 [fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]
445 1720060110 215612AOBR1|ABno_such_barcode|
447 1801010120100609 162510ABno_such_barcode|AJ|
449 1720060110 215612AOBR1|AB1565921879|
451 1810020120100623 171415AB1565921879|AJPerl 5 desktop reference|CK001|AQBR1|APBR1|BGBR1
452 |CTBR3|CSQA76.73.P33V76 1996|
454 The first case is with a bogus barcode. The latter shows an item with a circulation_status of _10_ for _in transit between
455 libraries_. The known values of +circulation_status+ are enumerated in the spec.
457 indexterm:[Automated Material Handling (AMH)]
459 EXTENSIONS: The CT field for _destination location_ and CS _call number_ are used by Automated Material Handling
463 anchor:19-20_item_status_update[]
465 19/20 Item Status Update
466 ^^^^^^^^^^^^^^^^^^^^^^^^
469 anchor:23-24_patron_status[]
476 2300120060101 084235AOUWOLS|AAbad_barcode|ACsip_01|ADbad_password|
478 24YYYY 00120100507 013934AE|AAbad_barcode|BLN|AOUWOLS|
480 2300120060101 084235AOCONS|AA999999|ACsip_01|ADbad_password|
482 24 Y 00120100507 022318AEDoug Fiander|AA999999|BLY|CQN|BHUSD|BV0.00|AFOK|AOCONS|
484 2300120060101 084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|
486 24 Y 00120100507 022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|
488 . The BL field (+SIP2+, optional) is _valid patron_, so the _N_ value means _bad_barcode_ doesn't match a patron, the
489 _Y_ value means 999999 does.
491 . The CQ field (+SIP2+, optional) is _valid password_, so the _N_ value means _bad_password_ doesn't match 999999's
492 password, the _Y_ means _userpassword_ does.
494 So if you were building the most basic +SIP2+ authentication client, you would check for _|CQY|_ in the response to
495 know the user's barcode and password are correct (|CQY| implies |BLY|, since you cannot check the password
496 unless the barcode exists). However, in practice, depending on the application, there are other factors to consider in
497 authentication, like whether the user is blocked from checkout, owes excessive fines, reported their card lost, etc.
498 These limitations are reflected in the 14-character _patron status_ string immediately following the _24_ code. See the
499 field definitions in your copy of the spec.
502 anchor:25-26_patron_enable[]
515 Evergreen supports the Renew message.
518 anchor:35-36_end_session[]
523 3520100505 115901AOBR1|AA999999|
525 36Y20100507 161213AOCONS|AA999999|AFThank you!|
527 The _Y/N_ code immediately after the 36 indicates _success/failure_. Failure is not particularly meaningful or important
528 in this context, and for evergreen it is hardcoded _Y_.
532 anchor:37-38_fee_paid[]
537 Evergreen supports the Fee Paid message.
540 anchor:63-64_patron_information[]
542 63/64 Patron Information
543 ^^^^^^^^^^^^^^^^^^^^^^^^
545 Attempting to retrieve patron info with a bad barcode:
547 6300020060329 201700 AOBR1|AAbad_barcode|
549 64YYYY 00020100623 141130000000000000000000000000AE|AAbad_barcode|BLN|AOBR1|
551 Attempting to retrieve patron info with a good barcode (but bad patron password):
553 6300020060329 201700 AOBR1|AA999999|ADbadpwd|
555 64 Y 00020100623 141130000000000000000000000000AA999999|AEDavid J. Fiander|BHUSD|BV0.00
556 |BD2 Meadowvale Dr. St Thomas, ON Canada
558 90210|BEdjfiander@somemail.com|BF(519) 555 1234|AQBR1|BLY|CQN|PB19640925|PCPatrons
559 |PIUnfiltered|AFOK|AOBR1|
561 See <<23-24_patron_status, 23/24 Patron Status>> for info on +BL+ and +CQ+ fields.
565 anchor:65-66_renew_all[]
570 Evergreen supports the Renew All message.
580 9300CNsip_01|CObad_value|CPBR1|
582 [Connection closed by foreign host.]
585 9300CNsip_01|COsip_01|CPBR1|
589 _941_ means successful terminal login. _940_ or getting dropped means failure.
592 anchor:97-96_resend[]
598 anchor:99-98_sc_and_acs_status[]
600 99/98 SC and ACS Status
601 ^^^^^^^^^^^^^^^^^^^^^^^
603 99<status code><max print width><protocol version>
605 All 3 fields are required:
609 * 1: SC is out of paper
611 * 2: SC shutting down
613 * status code - 1 character
615 * max print width - 3 characters - the integer number of characters the client can print
617 * protocol version - 4 characters - x.xx
619 98<on-line status><checkin ok><checkout ok><ACS renewal policy>
620 <status update ok><offline ok><timeout period>
622 <retries allowed><date/time sync><protocol version><institution id>
623 <library name><supported messages><terminal
625 location><screen message><print line>
631 98YYYYNN60000320100510 1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|
633 The Supported Messages field +BX+ appears only in +SIP2+, and specifies whether 16 different +SIP+ commands are
634 supported by the +ACS+ or not.
642 All fixed-length fields in a communication will appear before the first variable-length field. This allows for simple
643 parsing. Variable-length fields are by definition delimited, though there will not necessarily be an initial delimiter
644 between the last fixed-length field and the first variable-length one. It would be unnecessary, since you should know
645 the exact position where that field begins already.