Bug 20517: Use the "sort bin" field in SIP2 Checkin Response

This bug adds the SIP2SortBinMapping to make it possible to tell
the Koha SIP2 server to include a sort_bin/CL field in the
Checkin Response, if appropriate.

To test:
- Check out an item and return it via SIP2:
  $ telnet localhost 8023
  9300CNterm1|COterm1|CPCPL|
  09N20200422    12430020200422    124300APCPL|AOCPL|AB001|AC|
  (Where 001 in |AB001| is the barcode of the item in question)
- Check there is no CL field in the last response
- Apply the patch, fill in SIP2SortBinMapping with e.g.:
       CPL:itype:BK:3
- Repeat the first step
- Check the respons contains a CL field with a value of 3 (or what
  you put in the config). The field should look like |CL3|
- Signe ye offe

2020-06-25: Pass an item to _get_sort_bin, not a checkout. Rebase.

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Nick Clemens <nick@bywatersolutions.com>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Fridolin Somers <fridolin.somers@biblibre.com>

C4/SIP/ILS/Transaction/Checkin.pm

@@ -168,6 +168,10 @@ sub do_checkin {
         $self->alert( !$return || defined $self->alert_type );
     }
 
+    # Set sort bin based on info in the item associated with the issue, and the
+    # mapping from SIP2SortBinMapping
+    $self->sort_bin( _get_sort_bin( $self->{item} ) );
+
     $self->ok($return);
 
     return { messages => $messages };
@@ -191,4 +195,60 @@ sub patron_id {
 	return $self->{patron}->id;
 }
 
+=head1 _get_sort_bin
+
+Takes an item represented as a hashref as argument.
+
+Uses the contents of the SIP2SortBinMapping syspref to determine the sort_bin
+value that should be returned for an item checked in via SIP2.
+
+The mapping should be:
+
+ <branchcode>:<item field>:<item field value>:<sort bin number>
+
+For example:
+
+ CPL:itype:BOOK:1
+ CPL:location:OFFICE:2
+
+This will give:
+
+=over 4
+
+=item * sort_bin = "1" for items at the CPL branch with an itemtype of BOOK
+
+=item * sort_bin = "2" for items at the CPL branch with a location of OFFICE
+
+=back
+
+Returns the ID of the appropriate sort_bin, if there is one, or undef.
+
+=cut
+
+sub _get_sort_bin {
+
+    # We should get an item represented as a hashref here
+    my ( $item ) = @_;
+    return undef unless $item;
+
+    # Get the mapping and split on newlines
+    my $raw_map = C4::Context->preference('SIP2SortBinMapping');
+    return unless $raw_map;
+    my @lines = split /\r\n/, $raw_map;
+
+    # Iterate over the mapping. The first hit wins.
+    foreach my $line ( @lines ) {
+        # Split the line into fields
+        my ( $branchcode, $item_property, $value, $sort_bin ) = split /:/, $line;
+        # Check the fields against values in the item
+        if ( ( $item->{homebranch} eq $branchcode ) && ( $item->{$item_property} eq $value ) ) {
+            return $sort_bin;
+        }
+    }
+
+    # Return undef if no hits were found
+    return undef;
+
+}
+
 1;

installer/data/mysql/atomicupdate/bug20517-sort-bin.perl

@@ -0,0 +1,8 @@
+$DBversion = 'XXX'; # will be replaced by the RM
+if( CheckVersion( $DBversion ) ) {
+    $dbh->do(q{
+        INSERT IGNORE INTO systempreferences ( `variable`, `value`, `options`, `explanation`, `type` ) VALUES
+        ('SIP2SortBinMapping','',NULL,'Use the following mappings to determine the sort_bin of a returned item. The mapping should be on the form \"branchcode:item field:item field value:sort bin number\", with one mapping per line.','free'),;
+    });
+    NewVersion( $DBversion, 20517, "Add SIP2SortBinMapping system preference");
+}

installer/data/mysql/mandatory/sysprefs.sql

@@ -621,6 +621,7 @@ INSERT INTO systempreferences ( `variable`, `value`, `options`, `explanation`, `
 ('ShowPatronImageInWebBasedSelfCheck','0','','If ON, displays patron image when a patron uses web-based self-checkout','YesNo'),
 ('ShowReviewer','full','none|full|first|surname|firstandinitial|username','Choose how a commenter\'s identity is presented alongside comments in the OPAC','Choice'),
 ('ShowReviewerPhoto','1','','If ON, photo of reviewer will be shown beside comments in OPAC','YesNo'),
+('SIP2SortBinMapping','',NULL,'Use the following mappings to determine the sort_bin of a returned item. The mapping should be on the form \"branchcode:item field:item field value:sort bin number\", with one mapping per line.','free'),
 ('SkipHoldTrapOnNotForLoanValue','',NULL,'If set, Koha will never trap items for hold with this notforloan value','Integer'),
 ('SlipCSS','',NULL,'Slips CSS url.','free'),
 ('SMSSendDriver','','','Sets which SMS::Send driver is used to send SMS messages.','free'),

koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences/circulation.pref

@@ -1284,3 +1284,10 @@ Circulation:
                   1: Use
                   0: "Don't use"
             - recalls. Make sure you configure <a href="/cgi-bin/koha/admin/smart-rules.pl">circulation and fines rules</a> for recalls once enabled.
+
+    SIP2:
+        -
+            - "Use the following mappings to determine the sort_bin of a returned item. The mapping should be on the form 'branchcode:item field:item field value:sort bin number', with one mapping per line."
+            - pref: SIP2SortBinMapping
+              type: textarea
+              class: long