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
[WARNING]
If you are installing on a recent, supported distribution, i.e. Ubuntu
16.04, Debian 8 Jessie, or Debian 9 Stretch, you should be aware of
https://bugs.launchpad.net/ncipserver/+bug/1732485[this bug]. You
will very likely need to apply the patch on that bug to have a working
NCIPServer installation.
After installing the prerequisites above and downloading the patch,
you can apply it with the following command:
[source,sh]
sudo patch -b /usr/share/perl5/HTTP/Body/XForms.pm /path/to/HTTP-Body-XForms.patch
NOTE: The path to /usr/share/perl5/HTTP/Body/XForms.pm may vary by
Linux distribution.
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
---------------------------------
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.
Apache 2.2
~~~~~~~~~~
--------------------------------------------------------------------
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
PerlSetEnv DANCER_ENVIRONMENT "production"
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
PerlSetEnv DANCER_ENVIRONMENT "production"
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.