SIP Support

This page is intended to give an overview of what is supported in the Evergreen SIP stack. This document is not intended to be used as a SIP developers' guide or authoritative document on SIP.

Installation instructions for SIP on Evergreen can be found here.

FIXME We need a new demonstration server for SIP.

Where page numbers are cited, we are referring to the “3M™ Standard Interchange Protocol: Describes 3M Standard Interchange Protocol Version 2.0” document, revision 2.10 updated 9/17/1998.

Background

SIP, standing for Standard Interchange Protocol, was developed by the 3M corporation to be a common protocol for data transfer between ILS' (referred to in SIP as an “ACS”, or “Automated Circulation System”) and a third party device. Originally, the protocol was developed for use with 3M SelfCheck (often abbreviated SC, not to be confused with Staff Client) systems, but has since expanded to other companies and devices. It is now common to find SIP in use in several other vendors' SelfCheck systems, as well as other non-SelfCheck devices. Some examples include:

  • Patron Authentication (computer access, subscription databases)
  • Automated Material Handling (AMH) - The automated sorting of items, often to bins or book carts, based on shelving location or other programmable criteria

The Evergreen SIP stack was was sponsored development to support a base set of features for devices already deployed in a library migrating to Evergreen - thus, the Evergreen SIP stack is not complete.

General Overview

SIP generally communicates over a TCP connection (either raw sockets or over telnet), but can also communicate via serial connections and other methods. In Evergreen, the most common deployment is a RAW socket connection on port 6001.

SIP communication consists of strings of messages, each message request and response begin with a 2-digit “command” - Requests usually being an odd number and responses usually increased by 1 to be an even number. The combination numbers for the request command and response is often referred to as a “Message Pair” (for example, a 23 command is a request for patron status, a 24 response is a patron status, and the message pair 23/24 is patron status message pair). The table in the next section shows the message pairs and a description of them.

For clarification, the “Request” is from the device (selfcheck or otherwise) to the ILS/ACS. The response is… the response to the request ;).

Within each request and response, a number of fields (either a fixed width or separated with a '|' [pipe symbol] and preceeded with a 2-character field identifier) are used. The fields vary between message pairs.

Message Types

For the “Pair” column, the “request” is preceeding the slash ('/'); the “response” is following the slash.

Pair Name Supported? Details
01 Block Patron Yes 01_Block_Patron - ACS responds with 24 Patron Status Response
09/10 Checkin Yes (with extensions) 09/10_Checkin
11/12 Checkout Yes (no renewals) 11/12_Checkout
15/16 Hold NO 15/16_Hold
17/18 Item Information Yes (no extensions) 17/18_Item_Information
19/20 Item Status Update NO 19/20_Item_Status_Update - Returns Patron Enable response, but doesn't make any changes in EG
23/24 Patron Status Yes 23/24_Patron_Status - 63/64 “Patron Information” preferred
25/26 Patron Enable NO 25/26_Patron_Enable - Used during system testing and validation
29/30 Renew NO (maybe?) 29/30_Renew
35/36 End Session Yes 35/36_End_Session
37/38 Fee Paid Yes 37/38_Fee_Paid
63/64 Patron Information Yes (no extensions) 63/64_Patron_Information
65/66 Renew All NO 65/66_Renew_All
93/94 Login Yes 93/94_Login - Must be first command to Evergreen ACS (via socket) or SIP will terminate
97/96 Resend last message Yes 97/96_Resend
99/98 SC/ACS Status Yes 99/98_SC_and_ACS_Status

01 Block Patron

A selfcheck will issue a Block Patron command if a patron leaves their card in a selfcheck machine or if the selfcheck detects tampering (such as attempts to disable multiple items during a single item checkout, multiple failed pin entries, etc).

In Evergreen, this command does the following:

  • User alert message: 'CARD BLOCKED BY SELF-CHECK MACHINE' (this is independent of the AL 'Blocked Card Message' field)
  • Card is marked inactive

The request looks like:

01<card retained><date>[fields AO, AL, AA, AC]
Card Retained a single character field of 'Y' or 'N' - tells the ACS whether the SC has retained the card (ex: left in the machine) or not
Date an 18 character field for the date/time when the block occurred. Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when 'local time', ' Z' (3 blanks and a Z) represents UTC(GMT/Zulu)
Fields see Fields for more details

The response is a 24 “Patron Status Response” with the following:

  • Charge privileges denied
  • Renewal privileges denied
  • Recall privileges denied (hard-coded in every 24 or 64 response)
  • hold privileges denied
  • Screen Message 1 (AF): 'blocked'
  • Patron

09/10 Checkin

The request looks like:

09<No block (Offline)><xact date><return date>[Fields AP,AO,AB,AC,CH,BI] 
No Block (Offline) A single character field of 'Y' or 'N' - Offline transactions are not currently supported so send 'N'
xact date an 18 character field for the date/time when the checkin occurred. Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when 'local time', ' Z' (3 blanks and a Z) represents UTC(GMT/Zulu)
Fields see Fields for more details

The response is a 10 “Checkin Response” with the following:

10<resensitize><magnetic media><alert><xact date>[Fields AO,AB,AQ,AJ,CL,AA,CK,CH,CR,CS,CT,CV,CY,DA,AF,AG] 

Example (with a remote hold):

09N20100507    16593720100507    165937APCheckin Bin 5|AOBR1|AB1565921879|ACsip_01|
101YNY20100623    165731AOBR1|AB1565921879|AQBR1|AJPerl 5 desktop reference|CK001|CSQA76.73.P33V76 1996|CTBR3|CY373827|DANicholas Richard Woodard|CV02|

Here you can see a hold alert for patron (CY) 373827, named (DA) Nicholas Richard Woodard, to be picked up at (CT) BR3. Since the transaction is happening at (AO) BR1, the alert type (CV) is 02 for “hold at remote library”. The possible values for CV are:

  • 00: unknown
  • 01: local hold
  • 02: remote hold
  • 03: ILL transfer (not used by EG)
  • 04: transfer
  • 99: other

Notes: the logic for EG to determine the content is magnetic_media comes from either legacy circ scripts or search_config_circ_modifier. The default is non-magnetic. The same is true for media_type (default 001). EG does not populate the collection_code because it does not really have any, but it will provide the call_number where available.

Unlike the item_id (barcode), the title_id is actually a title string, unless the configuration forces the return of the bib ID.

Don't be confused by the different branches that can show up in the same response line.

  • AO is where the transaction took place,
  • AQ is the “permanent location”, and
  • CT is the “destination location” (i.e., pickup lib for a hold or target lib for a transfer).

11/12 Checkout

15/16 Hold

Not yet supported.

17/18 Item Information

17<xact_date>[fields: AO,AB,AC]

The request is very terse. AC is optional.

The following response structure is for SIP2. (Version 1 of the protocol had only 6 total fields.)

18<circulation_status><security_marker><fee_type><xact_date>[fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]

Example:

1720060110    215612AOBR1|ABno_such_barcode|
1801010120100609    162510ABno_such_barcode|AJ|
1720060110    215612AOBR1|AB1565921879|
1810020120100623    171415AB1565921879|AJPerl 5 desktop reference|CK001|AQBR1|APBR1|BGBR1|CTBR3|CSQA76.73.P33V76 1996|

The first case is with a bogus barcode. The latter shows an item with a circulation_status of “10” for “in transit between libraries”. The known values of circulation_status are enumerated in the spec.

EXTENSIONS: The CT field for “destination location” and CS “call number” are used by Automated Material Handling systems.

19/20 Item Status Update

23/24 Patron Status

Example:

2300120060101    084235AOUWOLS|AAbad_barcode|ACsip_01|ADbad_password|
24YYYY          00120100507    013934AE|AAbad_barcode|BLN|AOUWOLS|
2300120060101    084235AOCONS|AA999999|ACsip_01|ADbad_password|
24  Y           00120100507    022318AEDoug Fiander|AA999999|BLY|CQN|BHUSD|BV0.00|AFOK|AOCONS|
2300120060101    084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|
24  Y           00120100507    022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|
  1. The BL field (SIP2, optional) is “valid patron”, so the “N” value means “bad_barcode” doesn't match a patron, the “Y” value means 999999 does.
  2. The CQ field (SIP2, optional) is “valid password”, so the “N” value means “bad_password” doesn't match 999999's password, the “Y” means “userpassword” does.

So if you were building the most basic SIP2 authentication client, you would check for |CQY| in the response to know the user's barcode and password are correct (|CQY| implies |BLY|, since you cannot check the password unless the barcode exists). However, in practice, depending on the application, there are other factors to consider in authentication, like whether the user is blocked from checkout, owes excessive fines, reported their card lost, etc. These limitations are reflected in the 14-character “patron status” string immediately following the “24” code. See the field definitions in your copy of the spec.

25/26 Patron Enable

Not yet supported.

29/30 Renew

EG ACS status message indicates Renew is supported.

35/36 End Session

3520100505    115901AOBR1|AA999999|
36Y20100507    161213AOCONS|AA999999|AFThank you!|

The Y/N code immediately after the 36 indicates success/failure. Failure is not particularly meaningful or important in this context, and for evergreen it is hardcoded Y.

37/38 Fee Paid

Not implemented.

63/64 Patron Information

Attempting to retrieve patron info with a bad barcode:

6300020060329    201700          AOBR1|AAbad_barcode|
64YYYY          00020100623    141130000000000000000000000000AE|AAbad_barcode|BLN|AOBR1|

Attempting to retrieve patron info with a good barcode (but bad patron password):

6300020060329    201700          AOBR1|AA999999|ADbadpwd|
64  Y           00020100623    141130000000000000000000000000AA999999|AEDavid J. Fiander|BHUSD|BV0.00|BD2 Meadowvale Dr. St Thomas, ON Canada 90210|BEdjfiander@somemail.com|BF(519) 555 1234|AQBR1|BLY|CQN|PB19640925|PCPatrons|PIUnfiltered|AFOK|AOBR1|

See 23/24 Patron Status for info on BL and CQ fields.

65/66 Renew All

Not yet supported.

93/94 Login

Example:

9300CNsip_01|CObad_value|CPBR1|
[Connection closed by foreign host.]
...
9300CNsip_01|COsip_01|CPBR1|
941

941 means successful terminal login. 940 or getting dropped means failure.

97/96 Resend

99/98 SC and ACS Status

99<status code><max print width><protocol version>

All 3 fields are required:

  • status code - 1 character:
    • 0: SC is OK
    • 1: SC is out of paper
    • 2: SC shutting down
  • max print width - 3 characters - the integer number of characters the client can print
  • protocol version - 4 characters - x.xx
98<on-line status><checkin ok><checkout ok><ACS renewal policy><status update ok><offline ok><timeout period><retries allowed><date/time sync><protocol version><institution id><library name><supported messages><terminal location><screen message><print line>

Example:

9910302.00
98YYYYNN60000320100510    1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|

The Supported Messages field (BX) appears only in SIP2, and specifies whether 16 different SIP commands are supported by the ACS or not.

Fields

All fixed-length fields in a communication will appear before the first variable-length field. This allows for simple parsing. Variable-length fields are by definition delimited, though there will not necessarily be an initial delimiter between the last fixed-length field and the first variable-length one. It would be unnecessary, since you should know the exact position where that field begins already.

evergreen-admin/sip_support.txt · Last modified: 2012/11/08 13:42 by gmcharlton
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Debian Driven by DokuWiki

© 2008-2013 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.