From ddce1ae2d3c6f838c3da441fe2377bf86b49ac95 Mon Sep 17 00:00:00 2001
From: Jason Stephenson <jason@sigio.com>
Date: Wed, 12 Aug 2020 14:44:00 -0400
Subject: [PATCH] LP 1889628: SIP2 Patron Username Lookup

Allow SIP2 clients to pass the username or barcode in the SIP2 Patron
Identifier field (AA).  This is useful for services, such as
Overdrive, that can send a patron's username.  It is easier for a
patron to remember their username rather than barcode, and this
unifies login for those patrons who use their username to login to the
OPAC.

To make this possible, we modify the OpenILS::SIP::Patron->new method
to accept a usrname key to retrieve patrons by usrname.

We also modify the OpenILS::SIP->find_patron method to accept a
usrname key to look up patrons.  The find_partron method is further
modified to check the patron id against the opac.barcode.regex in more or
less the same manner as the OPAC.

Two helper functions are added to OpenILS::SIP:

1. get_ou_setting: to retrieve org unit settings using the home_ou of
the logged in SIP2 account.

2. get_barcode_regex: To retrieve and cache the opac.barcode_regex
setting.

Testing this requires a working SIP2 installation and a knowledge of
the SIP protocols.  The easiest thing is to install the patch and see
if your SIP client can recognize a patron who has a username different
from their barcode by using both their barcode and then their
username.

Signed-off-by: Jason Stephenson <jason@sigio.com>
Signed-off-by: Bill Erickson <berickxx@gmail.com>
---
 Open-ILS/src/perlmods/lib/OpenILS/SIP.pm      | 23 +++++++++++++++++++
 .../src/perlmods/lib/OpenILS/SIP/Patron.pm    |  6 +++--
 .../SIP/allow_usrname_in_patron_id.adoc       | 13 +++++++++++
 3 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 docs/RELEASE_NOTES_NEXT/SIP/allow_usrname_in_patron_id.adoc

diff --git a/Open-ILS/src/perlmods/lib/OpenILS/SIP.pm b/Open-ILS/src/perlmods/lib/OpenILS/SIP.pm
index 500efa22bc..5393765994 100644
--- a/Open-ILS/src/perlmods/lib/OpenILS/SIP.pm
+++ b/Open-ILS/src/perlmods/lib/OpenILS/SIP.pm
@@ -241,16 +241,39 @@ sub state {
     return { authtoken => $self->{authtoken} };
 }
 
+sub get_ou_setting {
+    my $self = shift;
+    my $setting = shift;
+    my $sess = $self->fetch_session;
+    return $U->ou_ancestor_setting_value($sess->home_ou, $setting);
+}
+
+sub get_barcode_regex {
+    my $self = shift;
+    if (!defined($self->{bc_regex})) {
+        $self->{bc_regex} = $self->get_ou_setting('opac.barcode_regex');
+        $self->{bc_regex} = '^\d' unless ($self->{bc_regex});
+    }
+    return $self->{bc_regex};
+}
+
 #
 # find_patron($barcode);
 # find_patron(barcode => $barcode);   # same as above
 # find_patron(usr => $id);
+# find_patron(usrname => $usrname);
 
 sub find_patron {
     my $self = shift;
     my $key  =  (@_ > 1) ? shift : 'barcode';  # if we have multiple args, the first is the key index (default barcode)
     my $patron_id = shift;
 
+    # Check for usrname or barcode in the same, simple way that the OPAC does.
+    my $bc_regex = $self->get_barcode_regex();
+    if ($key eq 'barcode' && $patron_id !~ /$bc_regex/) {
+        $key = 'usrname';
+    }
+
     $self->verify_session;
     return OpenILS::SIP::Patron->new($key => $patron_id, authtoken => $self->{authtoken}, @_);
 }
diff --git a/Open-ILS/src/perlmods/lib/OpenILS/SIP/Patron.pm b/Open-ILS/src/perlmods/lib/OpenILS/SIP/Patron.pm
index 16cff51aee..c26d8bffb9 100644
--- a/Open-ILS/src/perlmods/lib/OpenILS/SIP/Patron.pm
+++ b/Open-ILS/src/perlmods/lib/OpenILS/SIP/Patron.pm
@@ -36,7 +36,7 @@ sub new {
     my $patron_id = shift;
     my %args = @_;
 
-    if ($key ne 'usr' and $key ne 'barcode') {
+    if ($key ne 'usr' and $key ne 'barcode' and $key ne 'usrname') {
         syslog("LOG_ERROR", "Patron (card) lookup requested by illegeal key '$key'");
         return undef;
     }
@@ -78,7 +78,7 @@ sub new {
 
     # in some cases, we don't need all of this data.  Only fetch the user + barcode
     $usr_flesh = {flesh => 1, flesh_fields => {au => ['card']}} if $args{slim_user};
-    
+
     my $user;
     if($key eq 'barcode') { # retrieve user by barcode
 
@@ -94,6 +94,8 @@ sub new {
 
         $user = $card->usr;
 
+    } elsif ($key eq 'usrname') {
+        $user = $e->search_actor_user([{usrname => $patron_id}, $usr_flesh])->[0];
     } else {
         $user = $e->retrieve_actor_user([$patron_id, $usr_flesh]);
     }
diff --git a/docs/RELEASE_NOTES_NEXT/SIP/allow_usrname_in_patron_id.adoc b/docs/RELEASE_NOTES_NEXT/SIP/allow_usrname_in_patron_id.adoc
new file mode 100644
index 0000000000..c8d1e1d52e
--- /dev/null
+++ b/docs/RELEASE_NOTES_NEXT/SIP/allow_usrname_in_patron_id.adoc
@@ -0,0 +1,13 @@
+Allow Username in Patron ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Evergreen now accepts a patron's username in the SIP2 Patron ID field
+(AA) in addition to the barcode.  This modification is useful for
+vendors, such as Overdrive, who can accept a user's username.
+Additionally, it is easier for a patron to find and remember their
+username over their barcode.
+
+The new feature determines if the value in the Patron ID field is a
+barcode or username by comparing the field value against the
+`opac.barcode_regex` setting for the home organizational unit of the
+logged in SIP2 account as configured in the oils_sip.xml file.  This
+is similar to what the OPAC does when a patron logs in.
-- 
2.43.2