From 15069fd08e5cf2e0314a40876e625131c4aeccc0 Mon Sep 17 00:00:00 2001 From: Jason Stephenson Date: Wed, 5 Apr 2017 16:22:12 -0400 Subject: [PATCH] LP 1673971: Write a README. Signed-off-by: Jason Stephenson --- README | 394 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 394 insertions(+) diff --git a/README b/README index d896b6e..8f089a6 100644 --- a/README +++ b/README @@ -1,2 +1,396 @@ README for NCIPServer ===================== + +Prerequisites +------------- + +NCIPServer is intended to be used with a working Evergreen ILS +installation. It therefore requires that both +https://evergreen-ils.org/opensrf-downloads/[OpenSRF] and +https://evergreen-ils.org/egdownloads/[Evergreen] be installed. + +NCIPServer is also a Perl Dancer application. It requires additional +packages beyond those which are normally installed on an Evergreen +server. The following list of packages is appropriate for a +Debian-based distribution (typically Debian or Ubuntu). Those using +other distributions will need to install the equivalent packages. + +.Additional Packages +* libfile-slurp-perl +* libmodern-perl-perl +* libconfig-merge-perl +* libdancer-perl +* libobject-tiny-perl +* libxml-libxml-simple-perl +* libplack-perl + +Installation +------------ + +Installing the NCIPServer software is as simple as + +[source,sh] +git clone git://git.evergreen-ils.org/NCIPServer.git + +You should do the above in the opensrf user's home directory for ease +of installation. If you put it elsewhere, you will need to modify a +couple of the NCIPServer configuration file entries as described in +the next section. + +Configuration +------------- + +If you use the default installation location of +/home/opensrf/NCIPServer, then you do not need to make any changes to +the NCIPServer configuration files. If you have installed NCIPServer +to some other location, you will need to modify the path to the +templates in two files: + +. The "views" entry on line 8 of config.yml +. The value attribute of the templates tag in t/config_sample/NCIP.xml. + +Both locations require the full path to the templates directory. + +Configuring Evergreen for NCIPServer +------------------------------------ + +NCIPServer integrates very tightly with Evergreen's way of doing +things. You will need to do some configuration in Evergreen to add +organizational units, users, and circ and hold rules. + +NCIP Virtual Organizational Unit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Evergreen expects transactions to take place at a given location. +NCIPServer is no exception to this rule, and so an organizational unit +needs to be used as the home for virtual patrons, the working location +for virtual staff, as the location where holds are to be sent, and as +the place where remote circulations happen in Evergreen. We recommend +creating a new System and Branch in Evergreen for that purpose. When +you set these up, you should make sure that OPAC visible is set to +false.--You do not want regular patrons seeing this location and trying +to pick up their holds there.--You may, of course, reuse an existing +location that you may have already established for a similar purpose. +You definitely do not want to use an organizational unit associated +with a real branch in your Evergreen. + +NCIP Staff User +~~~~~~~~~~~~~~~ + +NCIPServer requires an Evergreen account that can conduct basic staff +functions in circulation and cataloging. These permissions can be +assigned to the user or to a new permission group that is then +assigned as the new user's profile. This new permission group should +not have a parent group so that the user will not inadvertently +inherit any problematic permissions. + +Thes user will need to have its working location (work_ou) set to the +virtual branch that represents the remote locations, and it will need +to have a workstation registered for its use. This workstation does +not need to be registered via the staff client. It only needs to exist +in the database. Registering it via the staff client may be the +easiest way to do it. + +Permissions +^^^^^^^^^^^ + +The following table shows the permissions required by the NCIPServer +staff user. The first column is the permission code and the second is +the organizational unit depth it is required to be granted at for +everything to work smoothly. The depths, of course, assume that you +are using a more or less standard, three-level hierarchy of Consortium +-> System -> Branch. If not, you may need to adjust the depths of the +permissions accordingly. Also, the permissions should not be +grantable, since no one should ever switch to this user via the staff +client. + +.NCIP Staff User Permissions +[options="header",cols="<,^"] +|=========================== +| code | depth +| ABORT_TRANSIT | 2 +| CANCEL_HOLDS | 1 +| COPY_ALERT_MESSAGE.override | 0 +| COPY_CHECKIN | 2 +| COPY_CHECKOUT | 2 +| COPY_HOLDS | 0 +| COPY_HOLDS_FORCE | 2 +| COPY_TRANSIT_RECEIVE | 2 +| CREATE_COPY | 0* +| CREATE_COPY_STAT_CAT_ENTRY | 2 +| CREATE_COPY_STAT_CAT_ENTRY_MAP | 2 +| CREATE_COPY_TRANSIT | 0 +| CREATE_MARC | 0 +| CREATE_TRANSIT | 0 +| CREATE_VOLUME | 2 +| DELETE_COPY | 0* +| DELETE_VOLUME | 2 +| IMPORT_MARC | 0 +| PATRON_EXCEEDS_CHECKOUT_COUNT.override | 0 +| PATRON_EXCEEDS_FINES.override | 0 +| PATRON_EXCEEDS_OVERDUE_COUNT.override | 0 +| REQUEST_HOLDS | 0 +| STAFF_LOGIN | 0 +| TITLE_HOLDS | 0 +| UPDATE_COPY | 0* +| UPDATE_MARC | 0 +| UPDATE_VOLUME | 2 +| VIEW_HOLD | 0 +| VIEW_HOLD_PERMIT | 0 +| VIEW_PERMIT_CHECKOUT | 0 +| VIEW_USER | 0 +| VOLUME_HOLDS | 0 +|================================ + +*The depth for create, update and delete copy permissions need to be +set to 0 if you are using the pre-cat copies option. If not, a depth +of 1 or 2 should be sufficient. + +NCIP Virtual Patrons +~~~~~~~~~~~~~~~~~~~~ + +NCIPServer expects barcodes in the user ID and other fields when +placing holds and circulating local copies for remote institutions. +You will, of course, need to create these patrons in Evergreen. Their +home library should be the virtual branch created for the NCIPServer +staff account. You could use multiple branches, one for each library +for instance, but that could lead to more complication than you may +want to deal with. + +Your ILL vendor may provide a list of patrons with barcodes for the +participating member libraries. + +The virtual patrons typically require no additional permissions beyond +what is allowed to normal patrons. It is a good idea to create a new +permission group as a child of your existing Patron group or one of +its descendants. This makes it clear to any staff that these patrons +are special. + +Circulation and Hold Matrix Matchpoints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Remote circulations and holds will take place at the NCIPServer +virtual organizational unit. This organizational unit will need to +have hold and circ matrix matchpoints that conform to whatever rules +you have worked out with your vendor and other partners. You may want +to use an extended loan period, perhaps as much as double the normal +interval. The reason for this is that some ILL software will check +the copy out in Evergreen when the sending library sets it to shipped. + +You should not need reciprocal rules for incoming items. Your normal +circulation matchpoints should work. You may need matchpoints to +allow the holds depending on how you have configured things already, +i.e. you may have a default that does not allow holds that you will +need to override. + +oils_ncip.xml +------------- + +The oils_ncip.xml file sets the options for the Evergreen driver. It +needs to be configured appropriately given your Evergreen settings and +operating environment. + +You will need to copy or move the oils_ncip.xml.example file found in +the examples/ subdirectory to your /openils/conf directory or wherever +you store your regular Evergreen configuration files, i.e. where you +put opensrf_core.xml and opensrf.xml. + +The example file should be renamed to oils_ncip.xml during the copy +process. Assuming that you are still in the root of your clone of the +NCIPServer repository, the following command should take care of it: + +[source,sh] +cp examples/oils_ncip.xml.example /openils/conf/oils_ncip.xml + +The following subsections describe the configuration tags from this +file. + +Credentials +~~~~~~~~~~~ + +You will need to enter the username, password, work ou., and +workstation for the NCIP virtual staff user for Evergreen in the +credentials section of the oils_ncip.xml file. The workstation +information needs the work_ou branch's short name prefixed to it with +a dash if you registered the workstation via the staff client or if +you included the shortname when inserting the workstation into the +database. + +Bootstrap +~~~~~~~~~ + +NCIPServer needs to know where to find the opensrf_core.xml +configuration file. This is typically /openils/conf/opensrf_core.xml, +but you may have installed it elsewhere. + +Items +~~~~~ + +use_precats +^^^^^^^^^^^ + +Despite what the comment in the config file says, you do not want to +use this setting. It does not do what is expected in Evergreen at +this time. The setting remains in the configuration file in +anticipation of the day that it will work properly. + +use_force_holds +^^^^^^^^^^^^^^^ + +The use_force_holds setting will cause force holds to be placed on +copies created by the AcceptItem message. This will also cause those +copies not to be holdable. The latter only takes effect when +use_precats is not in operation, since there is no other way to place +holds on precat copies. + +bib_source +^^^^^^^^^^ + +The bib_source setting is recommended if you do not use precat copies. +If it is not present, a default of System Local will be used. + +It will be used as the bibliographic record source when the "short" +bibs are created. Having a unique entry for this in your database +makes it easy to identify bibliographic records created via NCIP. It +is highly recommended that you create one just for this purpose. + +The element can be set up empty with the cbs attribute holding the +database ID of the config.bib_source entry to use. You can optionally +set the text value of the element to the name of the bib_source. If +the cbs attribute is omitted, then the text value name must be +provided. The example provided below will use the System Local +config.bib_source that comes with Evergreen. + +stat_cat_entry +^^^^^^^^^^^^^^ + +Add a stat_cat_entry element for each stat cat that you wish to fill +in when creating copies. If you aren't using stat_cats or if you don't +wish to create any for these, you don't need to have stat_cat_entry +elements. You could delete the dummy entry in this case. If you have +any required stat cats, then it is a good idea to have an entry here. + +The stat_cat attribute is the numeric id of the stat_cat for the +entry. + +The element's text node is used as the asset.stat_cat_entry's value in +the database. + +Patrons +~~~~~~~ + +block_profile +^^^^^^^^^^^^^ + +You can block patrons by profile group in two ways: + +The first is to enter a block_profile tag with a grp attribute set to +the value of the profile group's id, for example: + +-------------------------------------------------------------------- + +-------------------------------------------------------------------- + +The second is to enter a block_profile tag with a text value equal to +the name of the profile group, for instance: + +-------------------------------------------------------------------- + Local Use Only +-------------------------------------------------------------------- + +In this case, the name must match exactly the case, spacing, and +punctuation (if any) of the profile group's name in the +permission.grp_tree table. + +If you specify both the grp attribute and a text value with a group +name, then the value of the grp tag is used. The text value will be +ignored: + +-------------------------------------------------------------------- + Local Use Only +-------------------------------------------------------------------- + +You might want to do this in order to have the group name as a +reminder to the person that edits the configuration. + +Holds +~~~~~ + +abort_transits_on_cancel +^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to have transits aborted when holds are canceled via NCIP, +then move the tag outside of the enclosing +XML comment block so that is still inside the open and close +tags. + +WARNING: You may need to delete the comment block in this section if +you do not move the abort_transit_on_cancel setting to be outside of +the comment block. There appears to be a bug in the config file +parser that uses this comment as a setting value. This leads to +server errors whenever NCIP is accessed.11 + +Configuring Apache for NCIPServer +--------------------------------- + +Apache 2.2 +~~~~~~~~~~ + +You will need to add a configuration block so that Apache is able to +execute the NCIPServer code when the URL is accessed. The +configuration varies depending on Apache version. Examples for +versions 2.2 and 2.4 are provided. You could add this to your +eg_vhost.conf and the NCIP location will be available from your +catalog. You could create a new virtual host for the NCIPServer and +add this configuration there. If you use load balancing in front of +your Apache server, then you will need to do the installation and +configuration steps on each server that runs Apache. + +You will, of course, need to restart Apache after making these +configuration changes. If all goes well, NCIPServer should be up and +running at a location of /NCIP/ on your server. + +-------------------------------------------------------------------- + + AllowOverride None + + + SetHandler perl-script + PerlResponseHandler Plack::Handler::Apache2 + PerlSetVar psgi_app /home/opensrf/NCIPServer/bin/ncip_dancing.pl + PerlSetEnv NCIP_CONFIG_DIR "/home/opensrf/NCIPServer/t/config_sample" + PerlSetENV OILS_NCIP_CONFIG /openils/conf/oils_ncip.xml + Order deny,allow + Deny from all + Allow from 10.0.0.0/8 + +-------------------------------------------------------------------- + +Apache 2.4 +~~~~~~~~~~ + +-------------------------------------------------------------------- + + AllowOverride None + + + SetHandler perl-script + PerlResponseHandler Plack::Handler::Apache2 + PerlSetVar psgi_app /home/opensrf/NCIPServer/bin/ncip_dancing.pl + PerlSetENV NCIP_CONFIG_DIR /home/opensrf/NCIPServer/t/config_sample + PerlSetENV OILS_NCIP_CONFIG /openils/conf/oils_ncip.xml + Require ip 10.0.0.0/8 + +-------------------------------------------------------------------- + +Security +~~~~~~~~ + +NCIPServer does not require any authentication from the client, so it +would behoove you to restrict access to the NCIP location to a limited +number of Internet hosts. The configuration examples for Apache 2.2 +and 2.4 above restrict access to the 10.0.0.0/8 private network. You +will need to change that entry to whatever your vendor uses. You can +more Allow from or Require ip entries for other vendors and/or +hosts. It is also a good idea to allow of your own ips to connect for +testing purposes. -- 2.43.2