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:
+
+--------------------------------------------------------------------
+ <block_profile grp="20"/>
+--------------------------------------------------------------------
+
+The second is to enter a block_profile tag with a text value equal to
+the name of the profile group, for instance:
+
+--------------------------------------------------------------------
+ <block_profile>Local Use Only</block_profile>
+--------------------------------------------------------------------
+
+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:
+
+--------------------------------------------------------------------
+ <block_profile grp="20">Local Use Only</block_profile>
+--------------------------------------------------------------------
+
+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 <abort_transits_on_cancel/> tag outside of the enclosing
+XML comment block so that is still inside the <holds> 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.
+
+--------------------------------------------------------------------
+<Directory "/home/opensrf/NCIPServer">
+ AllowOverride None
+</Directory>
+<Location /NCIP/>
+ 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
+</Location>
+--------------------------------------------------------------------
+
+Apache 2.4
+~~~~~~~~~~
+
+--------------------------------------------------------------------
+<Directory "/home/opensrf/NCIPServer">
+ AllowOverride None
+</Directory>
+<Location /NCIP/>
+ 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
+ </Location>
+--------------------------------------------------------------------
+
+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.
projects / working / NCIPServer.git / commitdiff