Docbook cleanup to address many errors during DocBook processing including fop overfl...
[working/Evergreen.git] / 1.6 / admin / sip.xml
1 <?xml version="1.0" encoding="utf-8"?>\r
2 <chapter xml:id="sipserver" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
4         <info>\r
5                 <title>SIP Server</title>\r
6         </info>\r
7         <para><systemitem class="protocol">SIP</systemitem>, standing for <systemitem class="protocol">Standard Interchange Protocol</systemitem>, was developed by the \r
8         <orgname class="corporation">3M</orgname>corporation to be a common protocol for data transfer between ILS' \r
9         (referred to in <systemitem class="protocol">SIP</systemitem> as an <emphasis>ACS</emphasis>, or <emphasis>Automated Circulation System</emphasis>)\r
10         <indexterm><primary>Automated Circulation System</primary></indexterm> and a \r
11         third party device. Originally, the protocol was developed for \r
12         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 \r
13         <systemitem class="protocol">SIP</systemitem> in use in several other vendors' SelfCheck systems<indexterm><primary>SelfCheck</primary></indexterm>, as well as other non-SelfCheck devices. \r
14         Some examples include:</para>\r
15         <itemizedlist>\r
16                 <listitem>Patron Authentication (computer access, subscription databases)</listitem>\r
17                 <listitem>Automated Material Handling (AMH) <indexterm><primary>Automated Material Handling (AMH)</primary></indexterm>- The automated sorting of items, often to bins or \r
18                 book carts, based on shelving location or other programmable criteria</listitem>\r
19         </itemizedlist>\r
20    \r
21         <section xml:id="Installing_SIP_Server">\r
22                 <info>\r
23                 <title>Installing the <systemitem class="protocol">SIP</systemitem> Server</title>\r
24                 </info>\r
25                   <para>This is a rough intro to installing the <systemitem class="protocol">SIP</systemitem> server for Evergreen.</para>\r
26                 <simplesect xml:id="Gettingthecode">\r
27                             <title>Getting the code</title>\r
28                                 <para>Current <systemitem class="protocol">SIP</systemitem> code lives at github:</para>\r
29                                 <screen><userinput>cd /opt</userinput></screen>\r
30                                 <screen><userinput>git clone git://github.com/atz/SIPServer.git SIPServer</userinput></screen>\r
31                                 <para>Or use the old style:</para>\r
32                                 <screen><userinput>$ cd /opt</userinput></screen>\r
33                                 <screen><userinput>$ sudo cvs -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip login</userinput></screen>\r
34                                 <para>When prompted for the CVS password, just hit Enter (sudo password may be req'd)</para>\r
35                                 <screen><userinput>$ sudo cvs -z3 -d:pserver:anonymous@openncip.cvs.sourceforge.net:/cvsroot/openncip co -P SIPServer</userinput></screen>\r
36                                                          \r
37                 </simplesect>\r
38                 <simplesect xml:id="Configuring_Server">\r
39                         <title>Configuring the Server</title>\r
40                         <procedure>\r
41                         <step>\r
42                                 <para>Type the following commands from the command prompt:</para><indexterm><primary>configuration files</primary><secondary>oils_sip.xml</secondary></indexterm>\r
43                                 <screen><userinput>$ sudo su opensrf</userinput></screen>\r
44                                 <screen><userinput>$ cd /openils/conf</userinput></screen>\r
45                                 <screen><userinput>$ cp oils_sip.xml.example oils_sip.xml</userinput></screen>\r
46                         </step>\r
47                         <step>\r
48                                 <para>Edit <filename>oils_sip.xml</filename><indexterm><primary>configuration files</primary><secondary>oils_sip.xml</secondary></indexterm>. \r
49                                 Change the commented out &lt;server-params&gt; section to this:</para>\r
50 <programlisting>\r
51 &lt;server-params\r
52 min_servers='1'\r
53 min_spare_servers='0'\r
54 max_servers='25'\r
55 /&gt;\r
56 </programlisting>\r
57                         </step>\r
58                         <step>\r
59                                 <para> max_servers will directly correspond to the number of allowed <systemitem class="protocol">SIP</systemitem> clients. Set the number accordingly, but \r
60                                 bear in mind that too many connections can \r
61                                 exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), it is not recommended to exceed 100 \r
62                                 <systemitem class="protocol">SIP</systemitem> client connections.</para>                                \r
63                         </step>\r
64                         </procedure>             \r
65                 </simplesect>\r
66                 <simplesect xml:id="Adding_SIP_users">\r
67                         <title>Adding <systemitem class="protocol">SIP</systemitem> Users</title>\r
68                         <procedure>\r
69                                 <step>\r
70                                         <para>Type the following commands from the command prompt:</para><indexterm><primary>configuration files</primary><secondary>oils_sip.xml</secondary></indexterm>\r
71                                         <screen><userinput>$ sudo su opensrf</userinput></screen>\r
72                                         <screen><userinput>$ cd /openils/conf</userinput></screen>\r
73                                         <screen><userinput>$ cp oils_sip.xml.example oils_sip.xml</userinput></screen>\r
74                                 </step>\r
75                                 <step>\r
76                                         <para> in the &lt;accounts&gt; section, add <systemitem class="protocol">SIP</systemitem> client login information. Make sure that all \r
77                                         <varname>&lt;logins&gt;</varname> use the same institution attribute, and make \r
78                                         sure the institution is listed in <varname>&lt;institutions&gt;</varname>. All attributes in the <varname>&lt;login&gt;</varname> section will be \r
79                                         used by the <systemitem class="protocol">SIP</systemitem> client.</para>\r
80                                 \r
81                                 </step>\r
82                                 <step>\r
83                                         <para> In Evergreen, create a new profile group called <systemitem class="groupname">SIP</systemitem>. \r
84                                         This group should be a sub-group of <systemitem class="groupname">Users</systemitem> \r
85                                         (not <systemitem class="groupname">Staff</systemitem> or <systemitem class="groupname">Patrons</systemitem>). \r
86                                         Set Editing Permission as <emphasis role="bold">group_application.user.sip_client</emphasis> and give the group the following permissions:</para>\r
87                                         <literallayout>\r
88                                         COPY_CHECKIN\r
89                                         COPY_CHECKOUT\r
90                                         RENEW_CIRC      \r
91                                         VIEW_CIRCULATIONS\r
92                                         VIEW_COPY_CHECKOUT_HISTORY      \r
93                                         VIEW_PERMIT_CHECKOUT\r
94                                         VIEW_USER\r
95                                         VIEW_USER_FINES_SUMMARY\r
96                                         VIEW_USER_TRANSACTIONS\r
97                                         </literallayout>\r
98                                         <para>OR use SQL like:</para>\r
99 <screen>\r
100 <userinput>\r
101 INSERT INTO permission.grp_tree (id,name,parent,description,application_perm)\r
102 VALUES (8, 'SIP', 1, 'SIP2 Client Systems', 'group_application.user.sip_client');\r
103 \r
104 INSERT INTO permission.grp_perm_map (grp,perm,depth) \r
105 VALUES (8,15,0),(8,16,0),(8,17,0),(8,31,0),(8,32,0),(8,48,0),(8,54,0),(8,75,0),(8,82,0);\r
106 </userinput>\r
107 </screen>\r
108                                         \r
109                                         <para>Verify:</para>\r
110 <screen>\r
111 <userinput>\r
112 SELECT *\r
113 FROM permission.grp_perm_map JOIN permission.perm_list ON\r
114 permission.grp_perm_map.perm=permission.perm_list.id\r
115 WHERE grp=8;\r
116 </userinput>\r
117 </screen>\r
118                                         \r
119                                         <para>Keep in mind that the id <emphasis role="bold">(8)</emphasis> may not necessarily be available on your system.</para>                             \r
120                                 </step>\r
121                                 <step>\r
122                                         <para>For each account created in the &lt;login&gt; section of <filename>oils_sip.xml</filename>, create a user (via the staff client user editor) \r
123                                         that has the same username \r
124                                         and password and put that user into the <systemitem class="groupname">SIP</systemitem> group.</para>\r
125                                         <note><para>The expiration date will affect the <systemitem class="groupname">SIP</systemitem> users' connection so you might want to make a note of \r
126                                         this somewhere.</para></note>   \r
127                                 </step>\r
128                         </procedure>             \r
129                 </simplesect>\r
130                 <simplesect xml:id="Running_SIP_server">\r
131                         <title>Running the server</title>\r
132                                 <para>To start the <systemitem class="protocol">SIP</systemitem> server type the following commands from the command prompt:</para>\r
133                                 <screen><userinput>$ sudo su opensrf</userinput></screen>\r
134                                 <screen><userinput>$ oils_ctl.sh -d /openils/var/run -s /openils/conf/oils_sip.xml -a [start|stop|restart]_sip</userinput></screen>     \r
135                 </simplesect>\r
136                 <simplesect xml:id="Logging-SIP">\r
137                         <title>Logging-SIP</title><indexterm><primary>SIP</primary></indexterm>\r
138                         <simplesect>\r
139                                 <title><systemitem class="service">Syslog</systemitem></title>\r
140                                 <para>It is useful to log <systemitem class="protocol">SIP</systemitem> requests to a separate file especially during initial setup by modifying your \r
141                                 syslog config file.</para><indexterm><primary>syslog</primary></indexterm>\r
142                                 <procedure>\r
143                                         <step>\r
144                                                 <para>Edit syslog.conf.</para>\r
145                                                 <screen><userinput>$ sudo vi /etc/syslog.conf  # maybe /etc/rsyslog.conf</userinput></screen>   \r
146                                         </step>\r
147                                         <step>\r
148                                                 <para>Add this:</para>\r
149                                                 <programlisting>local6.*                -/var/log/SIP_evergreen.log</programlisting>    \r
150                                         </step>\r
151                                         <step>\r
152                                                 <para><systemitem class="service">Syslog</systemitem> expects the logfile to exist so create the file.</para>\r
153                                                 <screen><userinput>$ sudo touch /var/log/SIP_evergreen.log</userinput></screen> \r
154                                         </step>\r
155                                         <step>\r
156                                                 <para>Restart <systemitem class="service">sysklogd</systemitem>.</para>\r
157                                                 <screen><userinput>$ sudo /etc/init.d/sysklogd restart</userinput></screen>     \r
158                                         </step>\r
159                                 </procedure>            \r
160                         </simplesect>\r
161                         <simplesect>\r
162                                 <title><systemitem class="service">Syslog-NG</systemitem></title>\r
163                                 \r
164                                 <procedure>\r
165                                         <step>\r
166                                                 <para>Edit logging config.</para><indexterm><primary>syslog-NG</primary></indexterm>\r
167                                                 <screen><userinput>sudo vi /etc/syslog-ng/syslog-ng.conf</userinput></screen>   \r
168                                         </step>\r
169                                         <step>\r
170                                                 <para>Add:</para>\r
171 <programlisting>\r
172 # SIP2 for Evergreen\r
173 filter    f_eg_sip { level(warn, err, crit) and facility(local6); };\r
174 destination eg_sip { file("/var/log/SIP_evergreen.log"); };\r
175 log { source(s_all); filter(f_eg_sip); destination(eg_sip); };\r
176 </programlisting>       \r
177                                         </step>\r
178                                         <step>\r
179                                                 <para><systemitem class="service">Syslog-ng</systemitem> expects the logfile to exist so create the file.</para>\r
180                                                 <screen><userinput>$ sudo touch /var/log/SIP_evergreen.log</userinput></screen> \r
181                                         </step>\r
182                                         <step>\r
183                                                 <para>Restart <systemitem class="service">syslog-ng</systemitem></para>\r
184                                                 <screen><userinput>$ sudo /etc/init.d/syslog-ng restart</userinput></screen>    \r
185                                         </step>\r
186                                 </procedure>            \r
187                         </simplesect>\r
188                 </simplesect>   \r
189                 <simplesect xml:id="Testing_SIP_Connection">\r
190                         <title>Testing Your <systemitem class="protocol">SIP</systemitem> Connection</title><indexterm><primary>SIP</primary></indexterm>\r
191                         <itemizedlist>\r
192                                 <listitem>\r
193                                         <para>In the top level CVS checkout of the SIPServer code.</para>\r
194                                         <screen><userinput>$ cd SIPServer/t</userinput></screen>\r
195                                 </listitem>\r
196                                 <listitem>\r
197                                         <para> Edit <filename>SIPtest.pm</filename>, change the <varname>$instid</varname>, <varname>$server</varname>, <varname>$username</varname>, and \r
198                                         <varname>$password</varname> variables. This will be enough to test connectivity. \r
199                                         To run all tests, you'll need to change all the variables in the Configuration section.</para>\r
200                                         <screen><userinput>$ PERL5LIB=../ perl 00sc_status.t</userinput></screen>\r
201                                         <para>This should produce something like:</para>\r
202 <screen>\r
203 1..4\r
204 ok 1 - Invalid username\r
205 ok 2 - Invalid username\r
206 ok 3 - login\r
207 ok 4 - SC status\r
208 </screen>\r
209                                 </listitem>     \r
210                                 <listitem>\r
211                                         <para> Don't be dismayed at <emphasis role="bold">Invalid Username</emphasis>. That's just one of the many tests that are run.</para>\r
212                                 </listitem>                                             \r
213                         </itemizedlist>\r
214                 </simplesect>\r
215                 <simplesect xml:id="SIP-More_Testing">\r
216                         <title>More Testing</title>\r
217                         <procedure>\r
218                                 <step>\r
219                                         <para>Once you have opened up either the <systemitem class="protocol">SIP</systemitem> OR <systemitem class="protocol">SIP2</systemitem> ports to be \r
220                                         accessible from outside you can do some testing via <systemitem class="protocol">telnet</systemitem>. You can try this with localhost \r
221                                         if you so wish, but we want to prove that <systemitem class="protocol">SIP2</systemitem> works from non-localhost. \r
222                                         Replace <varname>$instid</varname>, <varname>$server</varname>, <varname>$barcode</varname>, <varname>$username</varname>, \r
223                                         and <varname>$password</varname> variables below as necessary.</para>\r
224                                         <note><para>We are using <systemitem>6001</systemitem> here which is associated with <systemitem class="protocol">SIP2</systemitem> as per our configuration.</para></note><indexterm><primary>telnet</primary></indexterm>\r
225 <screen>\r
226 <userinput>$ telnet $server 6001</userinput>\r
227 Connected to $server.\r
228 Escape character is '^]'.\r
229 <userinput>9300CN**$username**|CO**$password**|CP**$instid**</userinput>\r
230 </screen>                                       \r
231                                         <para>You should get back.</para>\r
232                                         <screen>941</screen>\r
233                                 </step>\r
234                                 <step>\r
235                                         <para>Now just copy in the following line (with variables replaced) you don't need to hit enter, just paste!</para>\r
236                                         <screen>2300120080623    172148AO**$instid**|AA**$barcode**|AC$password|AD**$password**</screen>\r
237                                         <para>You will get back the patron information for $barcode (something similar to the what's below).</para>\r
238 <screen>24  Y           00120100113    170738AEFirstName MiddleName LastName|AA**$barcode**|BLY|CQY\r
239 |BHUSD|BV0.00|AFOK|AO**$instid**|\r
240 </screen>\r
241                                         <para>The response declares it is a valid patron <varname>BLY</varname> with a valid password <varname>CQY</varname> and shows the user's \r
242                                         <varname>$name</varname>.</para>\r
243                                 </step>\r
244                         </procedure>\r
245                 </simplesect>\r
246         </section>\r
247         <section xml:id="SIP_Communication">\r
248                 <info>\r
249                         <title><systemitem class="protocol">SIP</systemitem> Communication</title><indexterm><primary>SIP</primary></indexterm>\r
250                 </info>\r
251                 <para><systemitem class="protocol">SIP</systemitem> generally communicates over a <systemitem class="protocol">TCP</systemitem> connection (either raw sockets or over \r
252                 <systemitem class="protocol">telnet</systemitem>), but can also communicate via serial connections and other methods. In Evergreen, \r
253                 the most common deployment is a <systemitem class="protocol">RAW</systemitem> socket connection on port <systemitem>6001</systemitem>.</para>\r
254                 <para><systemitem class="protocol">SIP</systemitem> communication consists of strings of messages, each message request and response begin with a 2-digit \r
255                 <quote>command</quote> - Requests usually being an odd \r
256                 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 \r
257                 <emphasis>Message Pair</emphasis> (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 \r
258                 patron status message pair). The table in the next section shows the message pairs and a description of them.</para>\r
259                 <para>For clarification, the <quote>Request</quote> is from the device (selfcheck or otherwise) to the ILS/ACS. The response is… the response \r
260                 to the request ;).</para>\r
261                 <para>Within each request and response, a number of fields (either a fixed width or separated with a <emphasis role="bold">|</emphasis> [pipe symbol] and preceeded with a \r
262                 2-character field identifier) \r
263                 are used. The fields vary between message pairs.</para>\r
264                 <informaltable>\r
265                         <tgroup cols="4">\r
266                                 <colspec colnum="1" colname="pair" colwidth="0.5*"/>\r
267                                 <colspec colnum="2" colname="name" colwidth="1.0*"/>\r
268                                 <colspec colnum="3" colname="supported" colwidth="1.0*"/>\r
269                                 <colspec colnum="4" colname="details" colwidth="3.0*"/>\r
270                                 <thead>\r
271                                         <row>\r
272                                                 <entry>Pair</entry>\r
273                                                 <entry>Name</entry>\r
274                                                 <entry>Supported?</entry>\r
275                                                 <entry>Details</entry>\r
276                                         </row>\r
277                                 </thead>\r
278                                 <tbody>\r
279                                         <row>\r
280                                                 <entry>01</entry>\r
281                                                 <entry>Block Patron</entry>\r
282                                                 <entry>Yes</entry>\r
283                                                 <entry><link linkend='SIP_Block_Patron'>01_Block_Patron</link> - ACS responds with 24 Patron Status Response</entry>\r
284                                         </row>\r
285                                         <row>\r
286                                                 <entry>09/10</entry>\r
287                                                 <entry>Checkin</entry>\r
288                                                 <entry>Yes (with extensions)</entry>\r
289                                                 <entry><link linkend='SIP_Checkin'>09/10_Checkin</link></entry>\r
290                                         </row>\r
291                                         <row>\r
292                                                 <entry>11/12</entry>\r
293                                                 <entry>Checkout</entry>\r
294                                                 <entry>Yes (no renewals)</entry>\r
295                                                 <entry><link linkend='SIP_Checkout'>11/12_Checkout</link></entry>\r
296                                         </row>\r
297                                         <row>\r
298                                                 <entry>15/16</entry>\r
299                                                 <entry>Hold</entry>\r
300                                                 <entry>No</entry>\r
301                                                 <entry><link linkend='SIP_Hold'>15/16_Hold</link></entry>\r
302                                         </row>\r
303                                         <row>\r
304                                                 <entry>17/18</entry>\r
305                                                 <entry>Item Information</entry>\r
306                                                 <entry>Yes (no extensions)</entry>\r
307                                                 <entry><link linkend='SIP_Item_Information'>17/18_Item_Information</link></entry>\r
308                                         </row>\r
309                                         <row>\r
310                                                 <entry>19/20</entry>\r
311                                                 <entry>Item Status Update</entry>\r
312                                                 <entry>No</entry>\r
313                                                 <entry><link linkend='SIP_Item_Status_Update'>19/20_Item_Status_Update</link> - Returns Patron Enable response, but doesn't make any changes in EG</entry>\r
314                                         </row>\r
315                                         <row>\r
316                                                 <entry>23/24</entry>\r
317                                                 <entry>Patron Status</entry>\r
318                                                 <entry>Yes</entry>\r
319                                                 <entry><link linkend='SIP_Patron_Status'>23/24_Patron_Status</link> - 63/64 <quote>Patron Information</quote> preferred</entry>\r
320                                         </row>\r
321                                         <row>\r
322                                                 <entry>25/26</entry>\r
323                                                 <entry>Patron Enable</entry>\r
324                                                 <entry>No</entry>\r
325                                                 <entry><link linkend='SIP_Patron_Enable'>25/26_Patron_Enable</link> - Used during system testing and validation</entry>\r
326                                         </row>\r
327                                         <row>\r
328                                                 <entry>29/30</entry>\r
329                                                 <entry>Renew</entry>\r
330                                                 <entry>NO (maybe?)</entry>\r
331                                                 <entry><link linkend='SIP_Renew'>29/30_Renew</link></entry>\r
332                                         </row>\r
333                                         <row>\r
334                                                 <entry>35/36</entry>\r
335                                                 <entry>End Session</entry>\r
336                                                 <entry>Yes</entry>\r
337                                                 <entry><link linkend='SIP_End_Session'>35/36_End_Session</link></entry>\r
338                                         </row>\r
339                                         <row>\r
340                                                 <entry>37/38</entry>\r
341                                                 <entry>Fee Paid</entry>\r
342                                                 <entry>No</entry>\r
343                                                 <entry><link linkend='SIP_Fee_Paid'>37/38_Fee_Paid</link></entry>\r
344                                         </row>\r
345                                         <row>\r
346                                                 <entry>63/64</entry>\r
347                                                 <entry>Patron Information</entry>\r
348                                                 <entry>Yes (no extensions)</entry>\r
349                                                 <entry><link linkend='SIP_Patron_Information'>63/64_Patron_Information</link></entry>\r
350                                         </row>\r
351                                         <row>\r
352                                                 <entry>65/66</entry>\r
353                                                 <entry>Renew All</entry>\r
354                                                 <entry>No</entry>\r
355                                                 <entry><link linkend='SIP_Renew_All'>65/66_Renew_All</link></entry>\r
356                                         </row>\r
357                                         <row>\r
358                                                 <entry>93/94</entry>\r
359                                                 <entry>Login</entry>\r
360                                                 <entry>Yes</entry>\r
361                                                 <entry><link linkend='SIP_Login'>93/94_Login</link> - Must be first command to Evergreen ACS (via socket) or <systemitem class="protocol">SIP</systemitem> will terminate</entry>\r
362                                         </row>\r
363                                         <row>\r
364                                                 <entry>97/96</entry>\r
365                                                 <entry>Resend last message</entry>\r
366                                                 <entry>Yes</entry>\r
367                                                 <entry><link linkend='SIP_Resend'>97/96_Resend</link></entry>\r
368                                         </row>\r
369                                         <row>\r
370                                                 <entry>99/98</entry>\r
371                                                 <entry>SC/ACS Status</entry>\r
372                                                 <entry>Yes</entry>\r
373                                                 <entry><link linkend='SIP_SC_ACS_Status'>99/98_SC_and_ACS_Status</link></entry>\r
374                                         </row>\r
375                                 </tbody>\r
376                         </tgroup>\r
377                 </informaltable>\r
378                 <simplesect xml:id="SIP_Block_Patron">\r
379                         <title>01 Block Patron</title>\r
380                         <para>A selfcheck will issue a <command>Block Patron</command> command if a patron leaves their card in a selfcheck machine or if the selfcheck detects tampering (such as attempts \r
381                         to disable multiple items during a single item checkout, multiple failed pin entries, etc).</para><indexterm><primary>SelfCheck</primary></indexterm>\r
382                         <para>In Evergreen, this command does the following:</para>\r
383                                 <itemizedlist>\r
384                                         <listitem>User alert message: <emphasis>CARD BLOCKED BY SELF-CHECK MACHINE</emphasis> (this is independent of the AL \r
385                                         <emphasis>Blocked Card Message</emphasis> field).</listitem>\r
386                                         <listitem>Card is marked inactive.</listitem>\r
387                                 </itemizedlist>\r
388                         <para>The request looks like:</para>\r
389                         <screen>01&lt;card retained&gt;&lt;date&gt;[fields AO, AL, AA, AC]</screen>\r
390                         <para><emphasis>Card Retained</emphasis>: A single character field of <emphasis>Y</emphasis> or <emphasis>N</emphasis> - tells the ACS whether the SC has \r
391                         retained the card (ex: left in the machine) or not.</para> \r
392                         <para><emphasis>Date</emphasis>: An 18 character field for the date/time when the block occurred.</para> \r
393                         <para><emphasis>Format</emphasis>: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, <quote> Z</quote> (3 blanks and a Z) represents UTC(GMT/Zulu)</para>\r
394                         <para><emphasis>Fields</emphasis>: See <link linkend='SIP_Fields'>Fields</link> for more details.</para>\r
395                         <para>The response is a 24 <quote>Patron Status Response</quote> with the following:</para>\r
396                         <itemizedlist>\r
397                                         <listitem>Charge privileges denied</listitem>\r
398                                         <listitem>Renewal privileges denied</listitem>\r
399                                         <listitem>Recall privileges denied (hard-coded in every 24 or 64 response)</listitem>\r
400                                         <listitem>hold privileges denied</listitem>\r
401                                         <listitem>Screen Message 1 (AF): <emphasis>blocked</emphasis></listitem>\r
402                                         <listitem>Patron</listitem>\r
403 \r
404                         </itemizedlist>\r
405                 </simplesect>\r
406                 <simplesect xml:id="SIP_Checkin">\r
407                         <title>09/10 Checkin</title>\r
408                         <para>The request looks like:</para>\r
409                         <screen>09&lt;No block (Offline)&gt;&lt;xact date&gt;&lt;return date&gt;[Fields AP,AO,AB,AC,CH,BI]</screen>\r
410                         <para><emphasis>No Block (Offline)</emphasis>: A single character field of <emphasis>Y</emphasis> or <emphasis>N</emphasis> - Offline transactions are not currently \r
411                         supported so send <emphasis>N</emphasis>.</para> \r
412                         <para><emphasis>xact date</emphasis>: an 18 character field for the date/time when the checkin occurred. Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - \r
413                         4 blanks when local time, <quote> Z</quote> (3 blanks and a Z) represents UTC(GMT/Zulu)</para> \r
414                         <para><emphasis>Fields</emphasis>: See <link linkend='SIP_Fields'>Fields</link> for more details.</para>\r
415                         <para>The response is a 10 <quote>Checkin Response</quote> with the following:</para>\r
416                         <screen>10&lt;resensitize>&lt;magnetic media&gt;&lt;alert&gt;&lt;xact date&gt;[Fields AO,AB,AQ,AJ,CL,AA,CK,CH,CR,CS,CT,CV,CY,DA,AF,AG]</screen>\r
417                         <para>Example (with a remote hold):</para>\r
418                         <screen>09N20100507    16593720100507    165937APCheckin Bin 5|AOBR1|AB1565921879|ACsip_01|</screen>\r
419 <screen>\r
420 101YNY20100623    165731AOBR1|AB1565921879|AQBR1|AJPerl 5 desktop reference|CK001|CSQA76.73.P33V76 1996\r
421 |CTBR3|CY373827|DANicholas Richard Woodard|CV02|\r
422 </screen>\r
423                         <para>Here you can see a hold alert for patron <varname>CY</varname> <emphasis>373827</emphasis>, named <varname>DA</varname> <emphasis>Nicholas Richard Woodard</emphasis>, \r
424                         to be picked up at <varname>CT</varname> <quote>BR3</quote>. Since the transaction is happening \r
425                         at <varname>AO</varname> <quote>BR1</quote>, the alert type <varname>CV</varname> is 02 for <emphasis>hold at remote library</emphasis>. \r
426                         The possible values for <varname>CV</varname> are:</para>\r
427                         <itemizedlist>\r
428                                         <listitem>00: unknown</listitem>\r
429                                         <listitem>01: local hold</listitem>\r
430                                         <listitem>02: remote hold</listitem>\r
431                                         <listitem>03: ILL transfer (not used by EG)</listitem>\r
432                                         <listitem>04: transfer</listitem>\r
433                                         <listitem>99: other</listitem>\r
434                         </itemizedlist>\r
435                         <note>\r
436                                 <para>the logic for Evergreen to determine the content is magnetic_media comes from either legacy circ scripts or search_config_circ_modifier. \r
437                                 The default is non-magnetic.<indexterm><primary>magnetic media</primary></indexterm> \r
438                                 The same is true for media_type (default 001). Evergreen does not populate the collection_code because it does not really have any, but it will provide the \r
439                                 call_number where available.</para>\r
440                                 <para>Unlike the <varname>item_id</varname> (barcode), the <varname>title_id</varname> is actually a title string, unless the configuration forces the return of \r
441                                 the bib ID.</para>\r
442                                 <para>Don't be confused by the different branches that can show up in the same response line.</para>\r
443                                 <itemizedlist>\r
444                                         <listitem><varname>AO</varname> is where the transaction took place,</listitem>\r
445                                         <listitem><varname>AQ</varname> is the <quote>permanent location</quote>, and</listitem>\r
446                                         <listitem><varname>CT</varname> is the <emphasis>destination location</emphasis> (i.e., pickup lib for a hold or target lib for a transfer).</listitem>\r
447                                 </itemizedlist>\r
448                         </note>\r
449                 </simplesect>\r
450                 <simplesect xml:id="SIP_Checkout">\r
451                         <title>11/12 Checkout</title>\r
452                 </simplesect>\r
453                 <simplesect xml:id="SIP_Hold">\r
454                         <title>15/16 Hold</title>\r
455                         <para>Not yet supported.</para>\r
456                 </simplesect>\r
457                 <simplesect xml:id="SIP_Item_Information">\r
458                         <title>17/18 Item Information</title>\r
459                         <para>The request looks like:</para>\r
460                         <screen>17&lt;xact_date&gt;[fields: AO,AB,AC]</screen>\r
461                         <para>The request is very terse. <varname>AC</varname> is optional.</para>\r
462                         <para>The following response structure is for <systemitem class="protocol">SIP2</systemitem>. (Version 1 of the protocol had only 6 total fields.)</para>\r
463 <screen>\r
464 18&lt;circulation_status&gt;&lt;security_marker&gt;&lt;fee_type&gt;&lt;xact_date&gt;\r
465 [fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]\r
466 </screen>\r
467                         <para>Example:</para>\r
468                         <screen>1720060110    215612AOBR1|ABno_such_barcode|</screen>\r
469                         <screen>1801010120100609    162510ABno_such_barcode|AJ|</screen>\r
470                         <screen>1720060110    215612AOBR1|AB1565921879|</screen>\r
471 <screen>1810020120100623    171415AB1565921879|AJPerl 5 desktop reference|CK001|AQBR1|APBR1|BGBR1\r
472 |CTBR3|CSQA76.73.P33V76 1996|\r
473 </screen>\r
474                         <para>The first case is with a bogus barcode. The latter shows an item with a circulation_status of <emphasis>10</emphasis> for <emphasis>in transit between libraries</emphasis>. \r
475                         The known values of <varname>circulation_status</varname> are enumerated in the spec.</para>\r
476                         <para>EXTENSIONS: The <varname>CT</varname> field for <emphasis>destination location</emphasis> and <varname>CS</varname> <emphasis>call number</emphasis> are used by \r
477                         Automated Material Handling systems.</para><indexterm><primary>Automated Material Handling (AMH)</primary></indexterm>\r
478                 </simplesect>\r
479                 <simplesect xml:id="SIP_Item_Status_Update">\r
480                         <title>19/20 Item Status Update</title>\r
481                 </simplesect>\r
482                 <simplesect xml:id="SIP_Patron_Status">\r
483                         <title>23/24 Patron Status</title>\r
484                         <para>Example:</para>\r
485                         <screen>2300120060101    084235AOUWOLS|AAbad_barcode|ACsip_01|ADbad_password|</screen>\r
486                         <screen>24YYYY          00120100507    013934AE|AAbad_barcode|BLN|AOUWOLS|</screen>\r
487                         <screen>2300120060101    084235AOCONS|AA999999|ACsip_01|ADbad_password|</screen>\r
488                         <screen>24  Y           00120100507    022318AEDoug Fiander|AA999999|BLY|CQN|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
489                         <screen>2300120060101    084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
490                         <screen>24  Y           00120100507    022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|</screen>\r
491                         <orderedlist>\r
492                                 <listitem>The <varname>BL</varname> field (<systemitem class="protocol">SIP2</systemitem>, optional) is <emphasis>valid patron</emphasis>, so the \r
493                                 <emphasis>N</emphasis> value means \r
494                                 <emphasis>bad_barcode</emphasis> doesn't match a patron, the <emphasis>Y</emphasis> value means 999999 does.</listitem>\r
495                                 <listitem>The <varname>CQ</varname> field (<systemitem class="protocol">SIP2</systemitem>, optional) is <emphasis>valid password</emphasis>, so the <emphasis>N</emphasis> \r
496                                 value means <emphasis>bad_password</emphasis> doesn't match 999999's password, the <emphasis>Y</emphasis> means <emphasis>userpassword</emphasis> \r
497                                 does.</listitem>\r
498                         </orderedlist>\r
499                         <para>So if you were building the most basic <systemitem class="protocol">SIP2</systemitem> authentication client, you would check for \r
500                         <emphasis>|CQY|</emphasis> in the response to know the user's barcode and password \r
501                         are correct (<varname>|CQY|</varname> implies <varname>|BLY|</varname>, since you cannot check the password unless the barcode exists). However, in practice, \r
502                         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 \r
503                         card lost, etc. These limitations are reflected in the 14-character <emphasis>patron status</emphasis> string immediately following the <emphasis>24</emphasis> code. \r
504                         See the field definitions in your copy of the spec.</para>\r
505                 </simplesect>\r
506                 <simplesect xml:id="SIP_Patron_Enable">\r
507                         <title>25/26 Patron Enable</title>\r
508                         <para>Not yet supported.</para>\r
509                 </simplesect>\r
510                 <simplesect xml:id="SIP_Renew">\r
511                         <title>29/30 Renew</title>\r
512                         <para>Evergreen ACS status message indicates <emphasis>renew</emphasis> is supported.</para>\r
513                 </simplesect>\r
514                 <simplesect xml:id="SIP_End_Session">\r
515                         <title>35/36 End Session</title>\r
516                         <screen>3520100505    115901AOBR1|AA999999|</screen>\r
517                         <screen>36Y20100507    161213AOCONS|AA999999|AFThank you!|</screen>\r
518                         <para>The <emphasis>Y/N</emphasis> code immediately after the 36 indicates <emphasis>success/failure</emphasis>. Failure is not particularly meaningful or \r
519                         important in this context, and for evergreen it is hardcoded <emphasis>Y</emphasis>.</para>     \r
520                 </simplesect>\r
521                 <simplesect xml:id="SIP_Fee_Paid">\r
522                         <title>37/38 Fee Paid</title>\r
523                         <para>Not implemented.</para>\r
524                 </simplesect>\r
525                 <simplesect xml:id="SIP_Patron_Information">\r
526                         <title>63/64 Patron Information</title>\r
527                         <para>Attempting to retrieve patron info with a bad barcode:</para>\r
528                         <screen>6300020060329    201700          AOBR1|AAbad_barcode|</screen>\r
529                         <screen>64YYYY          00020100623    141130000000000000000000000000AE|AAbad_barcode|BLN|AOBR1|</screen>\r
530                         <para>Attempting to retrieve patron info with a good barcode (but bad patron password):</para>\r
531                         <screen>6300020060329    201700          AOBR1|AA999999|ADbadpwd|</screen>\r
532 <screen>\r
533 64  Y           00020100623    141130000000000000000000000000AA999999|AEDavid J. Fiander|BHUSD|BV0.00\r
534 |BD2 Meadowvale Dr. St Thomas, ON Canada\r
535 </screen>\r
536 <screen>90210|BEdjfiander@somemail.com|BF(519) 555 1234|AQBR1|BLY|CQN|PB19640925|PCPatrons\r
537 |PIUnfiltered|AFOK|AOBR1|\r
538 </screen>\r
539                         <para>See <link linkend='SIP_Patron_Status'>23/24 Patron Status</link> for info on <varname>BL</varname> and <varname>CQ</varname> fields.</para>\r
540                 </simplesect>\r
541                 <simplesect xml:id="SIP_Renew_All">\r
542                         <title>65/66 Renew All</title>\r
543                         <para>Not yet supported.</para>\r
544                 </simplesect>\r
545                 <simplesect xml:id="SIP_Login">\r
546                         <title>93/94 Login</title>\r
547                         <para>Example:</para>\r
548                         <screen>9300CNsip_01|CObad_value|CPBR1|</screen>\r
549                         <screen>[Connection closed by foreign host.]</screen>\r
550                         <screen>...</screen>\r
551                         <screen>9300CNsip_01|COsip_01|CPBR1|</screen>\r
552                         <screen>941</screen>\r
553                         <para><emphasis>941</emphasis> means successful terminal login. <emphasis>940</emphasis> or getting dropped means failure.</para>\r
554                 </simplesect>\r
555                 <simplesect xml:id="SIP_Resend">\r
556                         <title>97/96 Resend</title>\r
557                 </simplesect>\r
558                 <simplesect xml:id="SIP_SC_ACS_Status">\r
559                         <title>99/98 SC and ACS Status</title>\r
560                         <screen>99&lt;status code&gt;&lt;max print width&gt;&lt;protocol version&gt;</screen>\r
561                         <para>All 3 fields are required:</para>\r
562                         <itemizedlist>\r
563                                         <listitem>status code - 1 character:</listitem>\r
564                                         <itemizedlist>\r
565                                                 <listitem>0: SC is OK</listitem>\r
566                                                 <listitem>1: SC is out of paper</listitem>\r
567                                                 <listitem>2: SC shutting down</listitem>                \r
568                                         </itemizedlist>\r
569                                         <listitem>max print width - 3 characters - the integer number of characters the client can print</listitem>\r
570                                         <listitem>protocol version - 4 characters - x.xx</listitem>\r
571                         </itemizedlist>\r
572 <screen>\r
573 98&lt;on-line status&gt;&lt;checkin ok&gt;&lt;checkout ok&gt;&lt;ACS renewal policy&gt;\r
574 &lt;status update ok&gt;&lt;offline ok&gt;&lt;timeout period&gt;\r
575 </screen>\r
576 <screen>\r
577 &lt;retries allowed&gt;&lt;date/time sync&gt;&lt;protocol version&gt;&lt;institution id&gt;\r
578 &lt;library name&gt;&lt;supported messages&gt;&lt;terminal\r
579 </screen> \r
580                         <screen>location&gt;&lt;screen message&gt;&lt;print line&gt;</screen>\r
581                         <para>Example:</para>\r
582                         <screen>9910302.00</screen>\r
583                         <screen>98YYYYNN60000320100510    1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|</screen>\r
584                         <para>The Supported Messages field <varname>BX</varname> appears only in <systemitem class="protocol">SIP2</systemitem>, and specifies whether 16 different \r
585                         <systemitem class="protocol">SIP</systemitem>  commands are supported by the ACS or not.</para>\r
586                 </simplesect>\r
587                 <simplesect xml:id="SIP_Fields">\r
588                         <title>Fields</title>\r
589                         <para>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 \r
590                         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 \r
591                         unnecessary, since you should know the exact position where that field begins already.</para>\r
592                 </simplesect>\r
593         </section>\r
594 </chapter>\r
595 \r