SIP2 configuration

"acsconfig" is the top level of the configuration.

server-params

Server params defines a number of universal SIP server settings.

Settings like min_servers and min_spare_servers are passed to Net::Server::PreFork.

If you are running only one self service station (loan or book return) use this configuration:

Example:

<server-params 
  min_servers="1" 
  min_spare_servers="0" 
  log_file="Sys::Syslog" 
  syslog_ident="koha_sip" 
  syslog_facility="local6" />

In real life you normally have more than one self service station. To allow more stations to connect to the SIP2 service you need higher values for min_servers and min_spare_servers

Example:

<server-params 
  min_servers="10" 
  min_spare_servers="5" 
  log_file="Sys::Syslog" 
  syslog_ident="koha_sip" 
  syslog_facility="local6" />

min_servers

The fewest instances of the SIP server that will always be running.

min_spare_servers

The fewest extra instances of the SIP server that are not in use.

log_file

Which log file should we use? "Sys::Syslog" is the standard.

In Koha V 23.05 you will find the sip logfile here: /var/log/koha/<your-koha-instance-name>/sip.log

Don't search for sip2.log. "locate sip.log" will show to the correct location !

syslog_ident

This is a string that will be included in every line in the log. On a server with more than instance using SIP2 it might be a good idea to add the instance name to the standard string, so you can see the difference between e.g. koha_sip_a and koha_sip_b.

Standard: koha_sip

syslog_facility

Standard: local6

listeners

The <listeners> section defines a set of services that the SIP server makes available for use. Each <service> instance has the following options:

Example:

<listeners>
  <service
    port="127.0.0.1:6001/tcp"
    transport="RAW"
    protocol="SIP/2.00"
    client_timeout="600"
    timeout="60" />
</listeners>

service

port

The port defines what IP protocol, port and ip address this server uses. For example "192.168.1.20:6001/tcp" would listen to port 6001 for the ip address 192.168.1.20 only using tcp. The ip address can be left off to listen on all IP addresses ( e.g. "6001/tcp" )

transport

Defines if this service is used for communication over telnet, or using RAW socket connections. Alternatives:

• http
• telnet
• RAW

protocol

Standard: "SIP/2.00"

client_timeout

Code comment:

client_timeout times out active connections which have not received input from the client. Many persistent connections will send a status request every 5-7 mins so setting this to less than that will add instability to the connection if explicitly set to zero, no timeout is applied to the connection.

timeout

Defines how long the connection will be allowed to stay open without communication before it is closed automatically. This setting defers to the institution timeout setting.

Code comment:

NB the parameter timeout applies to the login process only and should be set to a lower value [than client_timeout] to time out failed connections.

accounts

Example:

<accounts>
  <login id="staff" password="staff" delimiter="|" error-detect="enabled" institution="CPL" encoding="ascii" checked_in_ok="1" payment_type_writeoff="06" disallow_overpayment="1"/>
  <login id="lpl-sc-beacock" 
         password="xyzzy" 
         delimiter="|" 
         error-detect="enabled" 
         institution="LPL" 
         send_patron_home_library_in_af="1" 
         cv_send_00_on_success="1" 
         ct_always_send="1"
         cv_triggers_alert="1"
         allow_empty_passwords="1"
         ae_field_template="[% patron.surname %][% IF patron.firstname %], [% patron.firstname %][% END %]"
         da_field_template="[% patron.surname %][% IF patron.firstname %], [% patron.firstname %][% END %]"
         av_field_template="[% accountline.description %] [% accountline.amountoutstanding | format('%.2f') %]"
         hide_fields="BD,BE,BF,PB"
         register_id=""
         holds_block_checkin="0"
         format_due_date="0"
         inhouse_patron_categories="">
         <screen_msg_regex find="Greetings from Koha." replace="Welcome to your library!"/>
         <screen_msg_regex find="Invalid patron barcode." replace="Barcode not found, are you sure this is your library card?"/>
         <patron_attribute field="XY" code="CODE"/>
         <item_field field="ZY" code="permanent_location"/>
         <syspref_overrides>
           <AllFinesNeedOverride>0</AllFinesNeedOverride>
         </syspref_overrides>
         <custom_patron_field field="DE" template="[% patron.dateexpiry %]"/>
  </login>
</accounts>

login

There should be one login for each self-check machine (or other service) that needs to connect to Koha via SIP2. The id, password and institution must correspond to an actual user defined in the Koha instance. Give the users basic circulation permissions.

Hint: In Koha 23.05 a bad configuration can lead to no entry in the sip.log.

In our case we thought that we had connection problems with our sip2 client but at the end the solution was that id and password were correct but the institution was wrong.

id

Username of a user defined in Koha.

password

Password of a user defined in Koha.

Note: Avoid "&" (ampersand) in the password, as this causes problems with the XML-format of the SIP2 config file.

institution

Branchcode of a user defined in Koha.

delimiter

Which character should be used to delimit fields in SIP2 messages. Standard: "|".

error-detect

Defines if error correction is enabled for this login.

encoding

The character coding to use, default is utf8 but ascii is also available for services that cannot handle utf-8 encoded data.

checked_in_ok

Added in Bug 13411, version 3.22.

If set to 0, checking in an item that is not checked out will:

• Set Alert = Y.
• Give the message "Item not checked out" in the AF field.

If set to 1, checking in an item that is not checked out will not generate any of the responses mentioned above.

send_patron_home_library_in_af

The SIP2 standard has no provision for transmitting a patron's home library code. If this option is enabled, that code will be transmitted as an AF field for Patron Information and Patron Status Requests.

cv_send_00_on_success

Send a CV value of '00' for successful transactions instead of leaving the CV value blank

Added in Bug 22014, version 19.05.00.

ct_always_send

Always send a CT value, even if it would be blank.

Added in Bug 22016, version 19.05.00.

cv_triggers_alert

Only send the alert flag if a CV value is set.

Added in Bug 22043, version 19.05.00.

allow_empty_passwords

Added in Bug 18755, versions 17.11.00, 17.05.02, 16.11.10 and 16.05.15.

Some SIP devices expect an empty password field in a patron info request to be accepted as OK by the server. This parameter lets you set this behaviour explicitly.

Values: 1|0

ae_field_template

Added in Bug 18104, version 17.11.00.

Example:

ae_field_template="[% patron.surname %][% IF patron.firstname %], [% patron.firstname %][% END %]"

da_field_template

Added in Bug 16755, version 17.11.00.

Example:

da_field_template="[% patron.surname %][% IF patron.firstname %], [% patron.firstname %][% END %]"

av_field_template

Added in Bug 14512, version 16.05.00.

Example:

av_field_template="[% accountline.description %] [% accountline.amountoutstanding | format('%.2f') %]"

This template is compatible with Envisonwares eCommerce:

av_field_template='[% accountline.id %] $[% accountline.amountoutstanding | format("%.2f") %] "[% accountline.accounttype %]" [% accountline.description %]'

hide_fields

Added in Bug 20292, version 19.05.08.

Used to filter out SIP fields before sending the response.

Example:

hide_fields="BD,BE,BF,PB"

register_id

Added in Bug 24828, version 20.05.00.

• ID of the register to associate transactions with for this SIP2 login (used with Cash Management)

holds_block_checkin

Added in Bug 25541, version 20.11.00.

• Boolean denoting whether holds on an item should prevent check-in via this SIP2 login

holds_get_captured

Added in Bug 29936, version 22.05.00.

Defaults to enabled, as has been the case since bug Bug 3638 was pushed. However, it allows for disabling hold capture so that items are not automatically assigned to holds at SIP check-in; The alerts messages will continue to show, however, to allow items to be put to one side and then captured by a subsequent staff check-in.

overdues_block_checkout

Added in Bug 25761, version 20.11.00.

• Boolean denoting whether max overdues on the patrons account should prevent checkout via this SIP2 login

override_fine_on_checkout

Added in Bug 32408, version 23.05.00

• Boolean denoting whether to automatically override checkout blocks triggered by patrons fines according to AllFinesNeedOverride and noissuescharges.

prevcheckout_block_checkout

Added in Bug 26591, version 21.05.00.

• Boolean denoting whether previous checkout of the item on the patrons account should prevent checkout via this SIP2 login

screen_msg_regex

Added in Bug 12571, version 3.18.

Each SIP server account may have one or more screen message regular expressions. These regex's allow you to change the language of outgoing AF fields. Example:

 <screen_msg_regex find="Greetings from Koha." replace="Welcome to your library!"/>

Each <screen_msg_regex> has the following options:

find

May be a string or regex for the text on which to match

replace

May be a string with which to replace them match or to transport the match.

patron_attribute

Some libraries need to be able to send additional patron data from the extended patron attributes in made up SIP2 fields for the patron information and patron status responses.

Example:

<patron_attribute field="XY" code="CODE"/>

In this example, the value of the "extended patron attribute" CODE will be sent in the SIP2 field XY.

Added in Bug 17826, version 18.05.00.

field

Code of the SIP2 field to use.

code

Code of the "extended patron attribute" to use.

item_field

Some SIP devices need access to item fields that are not sent as item information in the checkin, checkout and item information responses. It makes sense to allow these fields to be sent in an arbitrary and configurable way, rather than hard code in each special case.

Edit your SIP2 config file, add the following within the login stanza:

  <item_field field="XX" code="<item field 1>" />
  <item_field field="XZ" code="<item fied 2>" />

where <item field 1> and <item field 2> are item table columns of your choosing.

Added in bug Bug 24165, versions 20.11.00, 20.05.03.

field

SIP2 field to send the information in.

code

"item" table column to get the information from.

syspref_overrides

Added in Bug 20954, version 19.11.00.

Example content:

<AllFinesNeedOverride>0</AllFinesNeedOverride>

custom_patron_field

Added in Bug 20816, versions 20.05.00, 19.11.06.

Affected SIP2 messages:

• Patron Status Response (24)
• Patron Information Response (64)

Example content:

 <login id="koha" password="koha" ...>
   <custom_patron_field field="DE" template="[% patron.dateexpiry %]" />
 </login>

With more than one field:

 <custom_patron_field field="EW" template="Phone: [% patron.phone %] Email: [% patron.email %]" />

field

The name of the SIP2-field the data should be returned in.

template

A piece of TT syntax to extract and format the desired data.

format_due_date

Added in Bug 28730, version 21.11.00.

Affected SIP2 messages:

• Checkout response

Example content:

 <login id="koha" password="koha" format_due_date="1">

Enables/Disables date formatting for due date field in checkout response.

inhouse_patron_categories

Added in Bug 26370, version 22.05.00.

Affected SIP2 messages:

• Checkout response

Example content:

 <login id="koha" password="koha" inhouse_patron_categories="CHILD,INHOUSE">

Disables the demagnetization of items at checkout for listed patron categories, preventing said items from being removed from the library by those users.

inhouse_item_types

Added in Bug 31296, version 22.11.00.

Affected SIP2 messages:

• Checkout response

Example content:

 <login id="koha" password="koha" inhouse_item_types="MAP,SCROLL,CHALICE">

Disables the demagnetization of items at checkout for listed item types, preventing said items from being removed from the library by those users.

institutions

Within the <institutions> block must be an instance of <institution> for each institution used in the <accounts> section of the configuration.

Example:

<institutions>
  <institution id="CPL" implementation="ILS" parms="">
    <policy checkin="true" renewal="true" checkout="true" status_update="false" offline="false" timeout="100" retries="5"/>
  </institution>
</institutions>

institution

id

This should correspond to a branchcode in Koha.

implementation

This should always be "ILS". It is related to the part of the SIP2 code in Koha that can be found in C4/SIP/ILS and below.

policy

Each <institution> contains a policy block. The <policy> block has the following options:

checkin

Defines if logins using this institution can check in items.

renewal

Defines if logins using the institution can renew items for patrons.

checkout

Defines if logins using the institution can check out items to patrons.

status_update

Defines if logins using the institution can update patron status ( e.g. block a patron's card ).

offline

Defines if the logins using the institution can process offline operations.

timeout

Defines how long the connection will be allowed to stay open without communication before it is closed automatically. This setting take precedence over the service timeout setting.

retries

Defines the number of retries that are allowed for a specific transaction.

syspref_overrides

Code comment:

This section allows system preferences to be overridden on a global basis. If the same system preference is overridden at the login level, the login version will take precedence.

Example content:

<AllFinesNeedOverride>0</AllFinesNeedOverride>

Added in Bug 20954, version 19.11.00.