Bug 14512

Summary: Add support for AV field to Koha's SIP2 Server
Product: Koha Reporter: Kyle M Hall <kyle>
Component: SIP2Assignee: Kyle M Hall <kyle>
Status: CLOSED FIXED QA Contact: Testopia <testopia>
Severity: enhancement    
Priority: P5 - low CC: amy, brendan, colin.campbell, crohde, jdemuth, jonathan.druart, jweaver, kyle.m.hall, m.de.rooy, nicole, tubaclarinet
Version: unspecified   
Hardware: All   
OS: All   
Change sponsored?: Sponsored Patch complexity: Small patch
Documentation contact: Documentation submission:
Text to go in the release notes:
Version(s) released in:
Attachments: Bug 14512 - Add support for AV field to Koha's SIP2 Server
Bug 14512 - Add support for AV field to Koha's SIP2 Server
[SIGNED-OFF] Bug 14512 - Add support for AV field to Koha's SIP2 Server
Bug 14512 - Add support for AV field to Koha's SIP2 Server

Description Kyle M Hall 2015-07-09 13:52:57 UTC
Koha's SIP2 server should have support for the AV field ( field items ). The biggest problem with this field is that its' contents are not really defined in SIP2 protocol specification. All it says is "this field should be sent for each fine item". Due to this, I think the contents of the field need to be configurable at the login level, so that the contents can be defined based on the SIP2 devices requirements for the AV field.
Comment 1 Kyle M Hall 2015-07-09 13:58:45 UTC Comment hidden (obsolete)
Comment 2 Kyle M Hall 2015-07-09 14:01:20 UTC Comment hidden (obsolete)
Comment 3 Kyle M Hall 2015-07-30 18:35:20 UTC Comment hidden (obsolete)
Comment 4 Jonathan Druart 2015-10-19 11:36:16 UTC
Kyle,
I don't have any idea what is a AV field, so it's a bit difficult to test this patch.
Could you please detail the step 8
  8) Note your custom AV field is being used!

What am I supposed to see where? :)
Comment 5 Kyle M Hall 2015-10-19 13:10:09 UTC
The AV field is for SIP2 fine items. There should be an AV field returned for each fee/fine in Koha. The specification doesn't actually specify what each AV field should look like, and different SIP2 devices expect different data, which is why I've made the contents of the field configurable.

You should expect to see the AV fields in the SIP2 response for your Patron Information request ( assuming you pass in the flag requesting the fee items ).
Comment 6 Colin Campbell 2015-12-16 12:10:44 UTC
3M machines used to expect an item identifier in AV and would then issue an item information request to get fee amount. That approach can be a bit flawed as not all financial transactions necessarily relate to items and in default settings I dont see AV being requested by most biblioteca/3M units
Comment 7 Kyle M Hall 2016-01-21 12:21:11 UTC
Here is an example AV field from another ILS I received from Comprise Technologies, a company that makes payment systems with work via SIP:

AV31982012795201 188 $0.20 "OVERDUE" Barbie. A fashion fairytale [videorecording]
Comment 8 Christopher Davis 2016-02-09 18:01:06 UTC
This enhancement is for my institution, and so I thank you guys for your work on it.

--

Christopher Davis, MLS
Systems & E-Services Librarian
Uintah County Library
uintahlibrary.org
basinlibraries.org
facebook.com/uintahcountylibrary
Comment 9 Jesse Weaver 2016-03-29 22:14:39 UTC
Created attachment 49657 [details] [review]
Bug 14512 - Add support for AV field to Koha's SIP2 Server

Koha's SIP2 server should have support for the AV field ( field items ).
The biggest problem with this field is that its' contents are not really
defined in SIP2 protocol specification. All it says is "this field
should be sent for each fine item". Due to this, I think the contents of
the field need to be configurable at the login level, so that the
contents can be defined based on the SIP2 devices requirements for the
AV field.

Test Plan:
1) Apply this patch
2) Find a patron with outstanding fines
3) Run a patron information request using misc/sip_cli_emulator.pl using the new -s option with the value "   Y      "
4) Note there is an AV field for each fee containing the description and amount
5) Edit your sip config, add an av_field_template parameter to the login you are using such as
    av_field_template="TEST [% accountline.description %] [% accountline.amountoutstanding | format('%.2f') %]"
6) Restart your SIP server
7) Repeat the patron information request
8) Note your custom AV field is being used!

Signed-off-by: Chris Davis <cgdavis@uintah.utah.gov>

Signed-off-by: Jesse Weaver <jweaver@bywatersolutions.com>
Comment 10 Jesse Weaver 2016-03-29 22:16:17 UTC
Detailed notes:

SIP setup:
  a) Create a Koha patron with 'circulate' permissions and a username/password matching a <login> in SIPconfig.xml (in the case of a git install, username/pw term1/term1 works).
  b) Start the SIP server (adjusting paths as needed):
    perl C4/SIP/SIPserver.pm ~/l/koha/etc/SIPconfig.xml

1) Apply this patch
2) Find a patron with outstanding fines
  JW: On my system this was cardnumber 23529000120056.
3) Run a patron information request using misc/sip_cli_emulator.pl using the new -s option with the value "   Y      "
  JW: $ perl misc/sip_cli_emulator.pl -a localhost -p 6001 -su term1 -sp term1 -l term1 -t CR -m patron_information --patron 23529000120056 -s "   Y      " 
4) Note there is an AV field for each fee containing the description and amount
  JW: Confirmed for multiple fines (in output of above command):
    ...|AVHold waiting too long 292 5.00|AVPatron sucks 7.00|...
  JW: Note the "AVHold waiting too long 292 5.00" and "AVPatron sucks 7.00" parts of the response.
5) Edit your sip config, add an av_field_template parameter to the login you are using such as
    av_field_template="TEST [% accountline.description %] [% accountline.amountoutstanding | format('%.2f') %]"
  JW: The relevant line in SIPconfig.xml now looks like (I used %.3f for the hell of it):
    <login id="term1"  password="term1" delimiter="|" error-detect="enabled" institution="CPL" encoding="ascii" checked_in_ok="1" av_field_template="[% accountline.description %] [% accountline.amountoutstanding | format('%.3f') %]" />
6) Restart your SIP server
7) Repeat the patron information request
8) Note your custom AV field is being used!^
  JW: Confirmed.
    ...|AVHold waiting too long 292 5.000|AVPatron sucks 7.000|...
Comment 11 Brendan Gallagher 2016-03-31 20:30:36 UTC
Pushed to master - Should be in the May 2016 release.  Thanks!