SIP2 configuration

From Koha Wiki

Jump to: navigation, search
Home > Documentation > SIP2

"acsconfig" is the top level of the configuration.

Contents

server-params

Server params defines a number of universal SIP server settings.

Example:

<server-params 
  min_servers="1" 
  min_spare_servers="0" 
  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.

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">
         <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.

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.

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

ct_always_send

cv_triggers_alert

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

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

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

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. 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

field

code

syspref_overrides

Added in Bug 20954, version 19.11.00.

Example content:

<AllFinesNeedOverride>0</AllFinesNeedOverride>

custom_patron_field

field

template

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 Bug 20954, version 19.11.00.

Personal tools