lib/NCIP/ILS/Evergreen.pm

   1 # ---------------------------------------------------------------
   2 # Copyright © 2014 Jason J.A. Stephenson <jason@sigio.com>
   3 #
   4 # This file is part of NCIPServer.
   5 #
   6 # NCIPServer is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # NCIPServer is distributed in the hope that it will be useful, but
  12 # WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with NCIPServer.  If not, see <http://www.gnu.org/licenses/>.
  18 # ---------------------------------------------------------------
  19 package NCIP::ILS::Evergreen;
  20
  21 use Modern::Perl;
  22 use XML::LibXML::Simple qw(XMLin);
  23 use DateTime;
  24 use DateTime::Format::ISO8601;
  25 use Digest::MD5 qw/md5_hex/;
  26 use OpenSRF::System;
  27 use OpenSRF::Utils qw/:datetime/;
  28 use OpenSRF::Utils::SettingsClient;
  29 use OpenILS::Utils::Fieldmapper;
  30 use OpenILS::Utils::CStoreEditor qw/:funcs/;
  31 use OpenILS::Application::AppUtils;
  32 use OpenILS::Const qw/:const/;
  33 use MARC::Record;
  34 use MARC::Field;
  35 use MARC::File::XML;
  36
  37 # We need a bunch of NCIP::* objects.
  38 use NCIP::Response;
  39 use NCIP::Problem;
  40 use NCIP::User;
  41 use NCIP::User::OptionalFields;
  42 use NCIP::User::AddressInformation;
  43 use NCIP::User::Id;
  44 use NCIP::User::BlockOrTrap;
  45 use NCIP::User::Privilege;
  46 use NCIP::User::PrivilegeStatus;
  47 use NCIP::StructuredPersonalUserName;
  48 use NCIP::StructuredAddress;
  49 use NCIP::ElectronicAddress;
  50
  51 # Inherit from NCIP::ILS.
  52 use parent qw(NCIP::ILS);
  53
  54 # Default values we define for things that might be missing in our
  55 # runtime environment or configuration file that absolutely must have
  56 # values.
  57 #
  58 # OILS_NCIP_CONFIG_DEFAULT is the default location to find our
  59 # driver's configuration file.  This location can be overridden by
  60 # setting the path in the OILS_NCIP_CONFIG environment variable.
  61 #
  62 # BIB_SOURCE_DEFAULT is the config.bib_source.id to use when creating
  63 # "short" bibs.  It is used only if no entry is supplied in the
  64 # configuration file.  The provided default is 2, the id of the
  65 # "System Local" source that comes with a default Evergreen
  66 # installation.
  67 use constant {
  68     OILS_NCIP_CONFIG_DEFAULT => '/openils/conf/oils_ncip.xml',
  69     BIB_SOURCE_DEFAULT => 2
  70 };
  71
  72 # A common Evergreen code shortcut to use AppUtils:
  73 my $U = 'OpenILS::Application::AppUtils';
  74
  75 # The usual constructor:
  76 sub new {
  77     my $class = shift;
  78     $class = ref($class) if (ref $class);
  79
  80     # Instantiate our parent with the rest of the arguments.  It
  81     # creates a blessed hashref.
  82     my $self = $class->SUPER::new(@_);
  83
  84     # Look for our configuration file, load, and parse it:
  85     $self->_configure();
  86
  87     # Bootstrap OpenSRF and prepare some OpenILS components.
  88     $self->_bootstrap();
  89
  90     # Initialize the rest of our internal state.
  91     $self->_init();
  92
  93     return $self;
  94 }
  95
  96 sub lookupuser {
  97     my $self = shift;
  98     my $request = shift;
  99
 100     # Check our session and login if necessary.
 101     $self->login() unless ($self->checkauth());
 102
 103     my $message_type = $self->parse_request_type($request);
 104
 105     # Let's go ahead and create our response object. We need this even
 106     # if there is a problem.
 107     my $response = NCIP::Response->new({type => $message_type . "Response"});
 108     $response->header($self->make_header($request));
 109
 110     # Need to parse the request object to get the user barcode.
 111     my ($barcode, $idfield) = $self->find_user_barcode($request);
 112
 113     # If we can't find a barcode, report a problem.
 114     unless ($barcode) {
 115         $idfield = 'AuthenticationInputType' unless ($idfield);
 116         # Fill in a problem object and stuff it in the response.
 117         my $problem = NCIP::Problem->new();
 118         $problem->ProblemType('Needed Data Missing');
 119         $problem->ProblemDetail('Cannot find user barcode in message.');
 120         $problem->ProblemElement($idfield);
 121         $problem->ProblemValue('Barcode');
 122         $response->problem($problem);
 123         return $response;
 124     }
 125
 126     # Look up our patron by barcode:
 127     my $user = $U->simplereq(
 128         'open-ils.actor',
 129         'open-ils.actor.user.fleshed.retrieve_by_barcode',
 130         $self->{session}->{authtoken},
 131         $barcode,
 132         0
 133     );
 134
 135     # Check for a failure, or a deleted, inactive, or expired user,
 136     # and if so, return empty userdata.
 137     if (!$user || $U->event_code($user) || $U->is_true($user->deleted())
 138             || !grep {$_->barcode() eq $barcode && $U->is_true($_->active())} @{$user->cards()}) {
 139
 140         my $problem = NCIP::Problem->new();
 141         $problem->ProblemType('Unknown User');
 142         $problem->ProblemDetail("User with barcode $barcode unknown");
 143         $problem->ProblemElement($idfield);
 144         $problem->ProblemValue($barcode);
 145         $response->problem($problem);
 146         return $response;
 147     }
 148
 149     # We got the information, so lets fill in our userdata.
 150     my $userdata = NCIP::User->new();
 151
 152     # Make an array of the user's active barcodes.
 153     my $ids = [];
 154     foreach my $card (@{$user->cards()}) {
 155         if ($U->is_true($card->active())) {
 156             my $id = NCIP::User::Id->new({
 157                 UserIdentifierType => 'Barcode',
 158                 UserIdentifierValue => $card->barcode()
 159             });
 160             push(@$ids, $id);
 161         }
 162     }
 163     $userdata->UserId($ids);
 164
 165     # Check if they requested any optional fields and return those.
 166     my $elements = $request->{$message_type}->{UserElementType};
 167     if ($elements) {
 168         $elements = [$elements] unless (ref $elements eq 'ARRAY');
 169         my $optionalfields = NCIP::User::OptionalFields->new();
 170
 171         # First, we'll look for name information.
 172         if (grep {$_ eq 'Name Information'} @$elements) {
 173             my $name = NCIP::StructuredPersonalUserName->new();
 174             $name->Surname($user->family_name());
 175             $name->GivenName($user->first_given_name());
 176             $name->Prefix($user->prefix());
 177             $name->Suffix($user->suffix());
 178             $optionalfields->NameInformation($name);
 179         }
 180
 181         # Next, check for user address information.
 182         if (grep {$_ eq 'User Address Information'} @$elements) {
 183             my $addresses = [];
 184
 185             # See if the user has any valid, physcial addresses.
 186             foreach my $addr (@{$user->addresses()}) {
 187                 next if ($U->is_true($addr->pending()));
 188                 my $address = NCIP::User::AddressInformation->new({UserAddressRoleType=>$addr->address_type()});
 189                 my $physical = NCIP::StructuredAddress->new();
 190                 $physical->Line1($addr->street1());
 191                 $physical->Line2($addr->street2());
 192                 $physical->Locality($addr->city());
 193                 $physical->Region($addr->state());
 194                 $physical->PostalCode($addr->post_code());
 195                 $physical->Country($addr->country());
 196                 $address->PhysicalAddress($physical);
 197                 push @$addresses, $address;
 198             }
 199
 200             # Right now, we're only sharing email address if the user
 201             # has it. We don't share phone numbers.
 202             if ($user->email()) {
 203                 my $address = NCIP::User::AddressInformation->new({UserAddressRoleType=>'Email Address'});
 204                 $address->ElectronicAddress(
 205                     NCIP::ElectronicAddress->new({
 206                         Type=>'Email Address',
 207                         Data=>$user->email()
 208                     })
 209                 );
 210                 push @$addresses, $address;
 211             }
 212
 213             $optionalfields->UserAddressInformation($addresses);
 214         }
 215
 216         # Fetch the user's home_ou. We'll need for a couple of things
 217         # below here.
 218         my $aou = $self->editor->retrieve_actor_org_unit($user->home_ou());
 219
 220         # Check for User Privilege.
 221         if (grep {$_ eq 'User Privilege'} @$elements) {
 222             # Get the user's group:
 223             my $pgt = $self->editor->retrieve_permission_grp_tree($user->profile());
 224             if ($pgt) {
 225                 my $privilege = NCIP::User::Privilege->new();
 226                 $privilege->AgencyId($aou->shortname());
 227                 $privilege->AgencyUserPrivilegeType($pgt->name());
 228                 $privilege->ValidToDate($user->expire_date());
 229                 $privilege->ValidFromDate($user->create_date());
 230
 231                 my $status = 'Active';
 232                 if (_expired($user)) {
 233                     $status = 'Expired';
 234                 } elsif ($U->is_true($user->barred())) {
 235                     $status = 'Barred';
 236                 } elsif (!$U->is_true($user->active())) {
 237                     $status = 'Inactive';
 238                 }
 239                 if ($status) {
 240                     $privilege->UserPrivilegeStatus(
 241                         NCIP::User::PrivilegeStatus->new({
 242                             UserPrivilegeStatusType => $status
 243                         })
 244                     );
 245                 }
 246
 247                 $optionalfields->UserPrivilege([$privilege]);
 248             }
 249         }
 250
 251         # Check for Block Or Trap.
 252         if (grep {$_ eq 'Block Or Trap'} @$elements) {
 253             my $blocks = [];
 254
 255             # First, let's check if the profile is blocked from ILL.
 256             if (grep {$_->id() == $user->profile()} @{$self->{blocked_profiles}}) {
 257                 my $block = NCIP::User::BlockOrTrap->new();
 258                 $block->AgencyId($aou->shortname());
 259                 $block->BlockOrTrapType('Block Interlibrary Loan');
 260                 push @$blocks, $block;
 261             }
 262
 263             # Next, we loop through the user's standing penalties
 264             # looking for blocks on CIRC, HOLD, and RENEW.
 265             my ($have_circ, $have_renew, $have_hold) = (0,0,0);
 266             foreach my $penalty (@{$user->standing_penalties()}) {
 267                 next unless($penalty->standing_penalty->block_list());
 268                 my @block_list = split(/\|/, $penalty->standing_penalty->block_list());
 269                 my $ou = $self->editor->retrieve_actor_org_unit($penalty->org_unit());
 270
 271                 # Block checkout.
 272                 if (!$have_circ && grep {$_ eq 'CIRC'} @block_list) {
 273                     my $bot = NCIP::User::BlockOrTrap->new();
 274                     $bot->AgencyId($ou->shortname());
 275                     $bot->BlockOrTrapType('Block Checkout');
 276                     push @$blocks, $bot;
 277                     $have_circ = 1;
 278                 }
 279
 280                 # Block holds.
 281                 if (!$have_hold && grep {$_ eq 'HOLD' || $_ eq 'FULFILL'} @block_list) {
 282                     my $bot = NCIP::User::BlockOrTrap->new();
 283                     $bot->AgencyId($ou->shortname());
 284                     $bot->BlockOrTrapType('Block Holds');
 285                     push @$blocks, $bot;
 286                     $have_hold = 1;
 287                 }
 288
 289                 # Block renewals.
 290                 if (!$have_renew && grep {$_ eq 'RENEW'} @block_list) {
 291                     my $bot = NCIP::User::BlockOrTrap->new();
 292                     $bot->AgencyId($ou->shortname());
 293                     $bot->BlockOrTrapType('Block Renewals');
 294                     push @$blocks, $bot;
 295                     $have_renew = 1;
 296                 }
 297
 298                 # Stop after we report one of each, even if more
 299                 # blocks remain.
 300                 last if ($have_circ && $have_renew && $have_hold);
 301             }
 302
 303             $optionalfields->BlockOrTrap($blocks);
 304         }
 305
 306         $userdata->UserOptionalFields($optionalfields);
 307     }
 308
 309     $response->data($userdata);
 310
 311     return $response;
 312 }
 313
 314 # Implementation functions that might be useful to a subclass.
 315
 316 # Get a CStoreEditor:
 317 sub editor {
 318     my $self = shift;
 319
 320     # If we have an editor, check the validity of the auth session, then
 321     # invalidate the editor if the session is not valid.
 322     if ($self->{editor}) {
 323         undef($self->{editor}) unless ($self->checkauth());
 324     }
 325
 326     # If we don't have an editor, make a new one.
 327     unless (defined($self->{editor})) {
 328         $self->login() unless ($self->checkauth());
 329         $self->{editor} = new_editor(authtoken=>$self->{session}->{authtoken});
 330     }
 331
 332     return $self->{editor};
 333 }
 334
 335 # Login via OpenSRF to Evergreen.
 336 sub login {
 337     my $self = shift;
 338
 339     # Get the authentication seed.
 340     my $seed = $U->simplereq(
 341         'open-ils.auth',
 342         'open-ils.auth.authenticate.init',
 343         $self->{config}->{credentials}->{username}
 344     );
 345
 346     # Actually login.
 347     if ($seed) {
 348         my $response = $U->simplereq(
 349             'open-ils.auth',
 350             'open-ils.auth.authenticate.complete',
 351             {
 352                 username => $self->{config}->{credentials}->{username},
 353                 password => md5_hex(
 354                     $seed . md5_hex($self->{config}->{credentials}->{password})
 355                 ),
 356                 type => 'staff',
 357                 workstation => $self->{config}->{credentials}->{workstation}
 358             }
 359         );
 360         if ($response) {
 361             $self->{session}->{authtoken} = $response->{payload}->{authtoken};
 362             $self->{session}->{authtime} = $response->{payload}->{authtime};
 363         }
 364     }
 365 }
 366
 367 # Return 1 if we have a 'valid' authtoken, 0 if not.
 368 sub checkauth {
 369     my $self = shift;
 370
 371     # We implement our own version of this function, rather than rely
 372     # on CStoreEditor, because we may want to check this at times that
 373     # we don't have a CStoreEditor.
 374
 375     # We use AppUtils to do the heavy lifting.
 376     if (defined($self->{session})) {
 377         if ($U->check_user_session($self->{session}->{authtoken})) {
 378             return 1;
 379         } else {
 380             return 0;
 381         }
 382     }
 383
 384     # If we reach here, we don't have a session, so we are definitely
 385     # not logged in.
 386     return 0;
 387 }
 388
 389 # private subroutines not meant to be used directly by subclasses.
 390 # Most have to do with setup and/or state checking of implementation
 391 # components.
 392
 393 # Find, load, and parse our configuration file:
 394 sub _configure {
 395     my $self = shift;
 396
 397     # Find the configuration file via variables:
 398     my $file = OILS_NCIP_CONFIG_DEFAULT;
 399     $file = $ENV{OILS_NCIP_CONFIG} if ($ENV{OILS_NCIP_CONFIG});
 400
 401     $self->{config} = XMLin($file, NormaliseSpace => 2,
 402                             ForceArray => ['block_profile', 'stat_cat_entry']);
 403 }
 404
 405 # Bootstrap OpenSRF::System, load the IDL, and initialize the
 406 # CStoreEditor module.
 407 sub _bootstrap {
 408     my $self = shift;
 409
 410     my $bootstrap_config = $self->{config}->{bootstrap};
 411     OpenSRF::System->bootstrap_client(config_file => $bootstrap_config);
 412
 413     my $idl = OpenSRF::Utils::SettingsClient->new->config_value("IDL");
 414     Fieldmapper->import(IDL => $idl);
 415
 416     OpenILS::Utils::CStoreEditor->init;
 417 }
 418
 419 # Login and then initialize some object data based on the
 420 # configuration.
 421 sub _init {
 422     my $self = shift;
 423
 424     # Login to Evergreen.
 425     $self->login();
 426
 427     # Create an editor.
 428     my $e = $self->editor();
 429
 430     # Retrieve the work_ou as an object.
 431     my $work_ou = $e->search_actor_org_unit(
 432         {shortname => $self->{config}->{credentials}->{work_ou}}
 433     );
 434     $self->{work_ou} = $work_ou->[0] if ($work_ou && @$work_ou);
 435
 436     # Load the barred groups as pgt objects into a blocked_profiles
 437     # list.
 438     $self->{blocked_profiles} = [];
 439     foreach (@{$self->{config}->{patrons}->{block_profile}}) {
 440         if (ref $_) {
 441             my $pgt = $e->retrieve_permission_grp_tree($_->{grp});
 442             push(@{$self->{blocked_profiles}}, $pgt) if ($pgt);
 443         } else {
 444             my $result = $e->search_permission_grp_tree({name => $_});
 445             if ($result && @$result) {
 446                 map {push(@{$self->{blocked_profiles}}, $_)} @$result;
 447             }
 448         }
 449     }
 450
 451     # Load the bib source if we're not using precats.
 452     unless ($self->{config}->{items}->{use_precats}) {
 453         # Retrieve the default
 454         my $cbs = $e->retrieve_config_bib_source(BIB_SOURCE_DEFAULT);
 455         my $data = $self->{config}->{items}->{bib_source};
 456         if ($data) {
 457             $data = $data->[0] if (ref($data) eq 'ARRAY');
 458             if (ref $data) {
 459                 my $result = $e->retrieve_config_bib_source($data->{cbs});
 460                 $cbs = $result if ($result);
 461             } else {
 462                 my $result = $e->search_config_bib_source({source => $data});
 463                 if ($result && @$result) {
 464                     $cbs = $result->[0]; # Use the first one.
 465                 }
 466             }
 467         }
 468         $self->{bib_source} = $cbs;
 469     }
 470
 471     # Load the required asset.stat_cat_entries:
 472     $self->{stat_cat_entries} = [];
 473     foreach (@{$self->{config}->{items}->{stat_cat_entry}}) {
 474         # Must have the stat_cat attr and the name, so we must have a
 475         # reference.
 476         next unless(ref $_);
 477         # We want to limit the search to the work org and its
 478         # ancestors.
 479         my $ancestors = $U->get_org_ancestors($self->{work_ou}->id());
 480         my $result = $e->search_asset_stat_cat_entry(
 481             {
 482                 stat_cat => $_->{stat_cat},
 483                 value => $_->{content},
 484                 owner => $ancestors
 485             }
 486         );
 487         if ($result && @$result) {
 488             map {push(@{$self->{stat_cat_entries}}, $_)} @$result;
 489         }
 490     }
 491 }
 492
 493 # Standalone, "helper" functions.  These do not take an object or
 494 # class reference.
 495
 496 # Check if a user is past their expiration date.
 497 sub _expired {
 498     my $user = shift;
 499     my $expired = 0;
 500
 501     # Users might not expire.  If so, they have no expire_date.
 502     if ($user->expire_date()) {
 503         my $expires = DateTime::Format::ISO8601->parse_datetime(
 504             cleanse_ISO8601($user->expire_date())
 505         )->epoch();
 506         my $now = DateTime->now()->epoch();
 507         $expired = $now > $expires;
 508     }
 509
 510     return $expired;
 511 }
 512
 513 1;