Chapter 43. SIP Server

Table of Contents

Installing the SIP Server
Getting the code
Configuring the Server
Adding SIP Users
Running the server
Logging-SIP
Testing Your SIP Connection
More Testing
SIP Communication
01 Block Patron
09/10 Checkin
11/12 Checkout
15/16 Hold
17/18 Item Information
19/20 Item Status Update
23/24 Patron Status
25/26 Patron Enable
29/30 Renew
35/36 End Session
37/38 Fee Paid
63/64 Patron Information
65/66 Renew All
93/94 Login
97/96 Resend
99/98 SC and ACS Status
Fields

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:

Installing the SIP Server

This is a rough intro to installing the SIP server for Evergreen.

Getting the code

Current SIP server code lives at in the Evergreen git repository:

cd /opt
git clone git://git.evergreen-ils.org/SIPServer.git SIPServer

Configuring the Server

  1. Type the following commands from the command prompt:

    $ sudo su opensrf
    $ cd /openils/conf
    $ cp oils_sip.xml.example oils_sip.xml
  2. Edit oils_sip.xml. Change the commented out <server-params> section to this:

    <server-params
       min_spare_servers='1'
       max_spare_servers='2'
       min_servers='3'
       max_servers='25'
                 />
  3. max_servers will directly correspond to the number of allowed SIP clients. Set the number accordingly, but bear in mind that too many connections can exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), it is not recommended to exceed 100 SIP client connections.

Adding SIP Users

  1. Type the following commands from the command prompt:

    $ sudo su opensrf
    $ cd /openils/conf
  2. In the <accounts> section, add SIP client login information. Make sure that all <logins> use the same institution attribute, and make sure the institution is listed in <institutions>. All attributes in the <login> section will be used by the SIP client.
  3. In Evergreen, create a new profile group called SIP. This group should be a sub-group of Users (not Staff or Patrons). Set Editing Permission as group_application.user.sip_client and give the group the following permissions:

    COPY_CHECKIN
    COPY_CHECKOUT
    CREATE_PAYMENT
    RENEW_CIRC
    VIEW_CIRCULATIONS
    VIEW_COPY_CHECKOUT_HISTORY
    VIEW_PERMIT_CHECKOUT
    VIEW_USER
    VIEW_USER_FINES_SUMMARY
    VIEW_USER_TRANSACTIONS

    OR use SQL like:

    INSERT INTO permission.grp_tree (name,parent,description,application_perm)
    VALUES ('SIP', 1, 'SIP2 Client Systems', 'group_application.user.sip_client');
    INSERT INTO
      permission.grp_perm_map (grp, perm, depth, grantable)
    SELECT
      g.id, p.id, 0, FALSE
    FROM
      permission.grp_tree g,
      permission.perm_list p
    WHERE
      g.name = 'SIP' AND
      p.code IN (
        'COPY_CHECKIN',
        'COPY_CHECKOUT',
        'RENEW_CIRC',
        'VIEW_CIRCULATIONS',
        'VIEW_COPY_CHECKOUT_HISTORY',
        'VIEW_PERMIT_CHECKOUT',
        'VIEW_USER',
        'VIEW_USER_FINES_SUMMARY',
        'VIEW_USER_TRANSACTIONS'
     );

    Verify:

    SELECT *
    FROM permission.grp_perm_map pgpm
        INNER JOIN permission.perm_list ppl ON pgpm.perm = ppl.id
        INNER JOIN permission.grp_tree pgt ON pgt.id = pgpm.grp
    WHERE pgt.name = 'SIP';
  4. For each account created in the <login> section of oils_sip.xml, create a user (via the staff client user editor) that has the same username and password and put that user into the SIP group.

Note

The expiration date will affect the SIP users' connection so you might want to make a note of this somewhere.

Running the server

To start the SIP server type the following commands from the command prompt:

$ sudo su opensrf
$ oils_ctl.sh -a [start|stop|restart]_sip

Logging-SIP

Syslog

It is useful to log SIP requests to a separate file especially during initial setup by modifying your syslog config file.

  1. Edit syslog.conf.

    $ sudo vi /etc/syslog.conf  # maybe /etc/rsyslog.conf
  2. Add this:

    local6.*                -/var/log/SIP_evergreen.log
  3. Syslog expects the logfile to exist so create the file.

    $ sudo touch /var/log/SIP_evergreen.log
  4. Restart sysklogd.

    $ sudo /etc/init.d/sysklogd restart

Syslog-NG

  1. Edit logging config.

    sudo vi /etc/syslog-ng/syslog-ng.conf
  2. Add:

    # +SIP2+ for Evergreen
    filter    f_eg_sip { level(warn, err, crit) and facility(local6); };
    destination eg_sip { file("var/log/SIP_evergreen.log"); };
    log { source(s_all); filter(f_eg_sip); destination(eg_sip); };
  3. Syslog-ng expects the logfile to exist so create the file.

    $ sudo touch /var/log/SIP_evergreen.log
  4. Restart syslog-ng

    $ sudo /etc/init.d/syslog-ng restart

Testing Your SIP Connection

  • In the root directory of the SIPServer code:

    $ cd SIPServer/t
  • Edit SIPtest.pm, change the $instid, $server, $username, and $password variables. This will be enough to test connectivity. To run all tests, you’ll need to change all the variables in the Configuration section.

    $ PERL5LIB=../ perl 00sc_status.t

    This should produce something like:

    1..4
    ok 1 - Invalid username
    ok 2 - Invalid username
    ok 3 - login
    ok 4 - SC status
  • Don’t be dismayed at Invalid Username. That’s just one of the many tests that are run.

More Testing

  1. Once you have opened up either the SIP OR SIP2 ports to be accessible from outside you can do some testing via telnet. You can try this with localhost if you so wish, but we want to prove that SIP2 works from non-localhost. Replace $instid, $server, $barcode, $username, and $password variables below as necessary.

    Note

    We are using 6001 here which is associated with SIP2 as per our configuration.

    $ telnet $server 6001
    Connected to $server.
    Escape character is '^]'.
    9300CN**$username**|CO**$password**|CP**$instid**

    You should get back.

    941
  2. Now just copy in the following line (with variables replaced) you don’t need to hit enter, just paste!

    2300120080623    172148AO**$instid**|AA**$barcode**|AC$password|AD**$password**

    You will get back the patron information for $barcode (something similar to the what’s below).

    24  Y           00120100113    170738AEFirstName MiddleName LastName|AA**$barcode**|BLY|CQY
    |BHUSD|BV0.00|AFOK|AO**$instid**|

    The response declares it is a valid patron BLY with a valid password CQY and shows the user’s $name.