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. 
===show_checkin_message===
When a document is checked in, a message containing the library location is sent via the "AF" field. Introduced in Bug 25814
===show_outstanding_amount===
When returning a document, send a message containing the fines associated to the user. Introduced in Bug 25812
===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 , 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.
===payment_type_writeoff===
===disallow_overpayment===
===terminator===
===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 , version 19.05.00.
===ct_always_send===
Always send a CT value, even if it would be blank.
Added in , version 19.05.00.
===cv_triggers_alert===
Only send the alert flag if a CV value is set.
Added in , version 19.05.00.
===allow_empty_passwords===
Added in , 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 , version 17.11.00.
Example: 
 ae_field_template="[% patron.surname %][% IF patron.firstname %], [% patron.firstname %][% END %]"
===da_field_template===
Added in , version 17.11.00.
Example: 
 da_field_template="[% patron.surname %][% IF patron.firstname %], [% patron.firstname %][% END %]"
===av_field_template===
Added in , 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 , 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 , 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 , version 20.11.00.
* Boolean denoting whether holds on an item should prevent check-in via this SIP2 login
===holds_get_captured===
Added in , version 22.05.00.
Defaults to enabled, as has been the case since bug 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 , 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 , 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 , 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 , 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 , 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 , 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 , version 19.11.00.
Example content:
 <AllFinesNeedOverride>0</AllFinesNeedOverride>
===custom_patron_field===
Added in , 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 , 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 , 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 , 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.
===parms===
===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 , version 19.11.00.
Category:SIP2