README

   1 README for NCIPServer
   2 =====================
   3
   4 Prerequisites
   5 -------------
   6
   7 NCIPServer is intended to be used with a working Evergreen ILS
   8 installation.  It therefore requires that both
   9 https://evergreen-ils.org/opensrf-downloads/[OpenSRF] and
  10 https://evergreen-ils.org/egdownloads/[Evergreen] be installed.
  11
  12 NCIPServer is also a Perl Dancer application.  It requires additional
  13 packages beyond those which are normally installed on an Evergreen
  14 server.  The following list of packages is appropriate for a
  15 Debian-based distribution (typically Debian or Ubuntu). Those using
  16 other distributions will need to install the equivalent packages.
  17
  18 .Additional Packages
  19 * libfile-slurp-perl
  20 * libmodern-perl-perl
  21 * libconfig-merge-perl
  22 * libdancer-perl
  23 * libobject-tiny-perl
  24 * libxml-libxml-simple-perl
  25 * libplack-perl
  26
  27 [WARNING]
  28 If you are installing on a recent, supported distribution, i.e. Ubuntu
  29 16.04, Debian 8 Jessie, or Debian 9 Stretch, you should be aware of
  30 https://bugs.launchpad.net/ncipserver/+bug/1732485[this bug].  You
  31 will very likely need to apply the patch on that bug to have a working
  32 NCIPServer installation.
  33
  34 After installing the prerequisites above and downloading the patch,
  35 you can apply it with the following command:
  36
  37 [source,sh]
  38 sudo patch -b /usr/share/perl5/HTTP/Body/XForms.pm /path/to/HTTP-Body-XForms.patch
  39
  40 NOTE: The path to /usr/share/perl5/HTTP/Body/XForms.pm may vary by
  41 Linux distribution.
  42
  43 Installation
  44 ------------
  45
  46 Installing the NCIPServer software is as simple as
  47
  48 [source,sh]
  49 git clone git://git.evergreen-ils.org/NCIPServer.git
  50
  51 You should do the above in the opensrf user's home directory for ease
  52 of installation.  If you put it elsewhere, you will need to modify a
  53 couple of the NCIPServer configuration file entries as described in
  54 the next section.
  55
  56 Configuration
  57 -------------
  58
  59 If you use the default installation location of
  60 /home/opensrf/NCIPServer, then you do not need to make any changes to
  61 the NCIPServer configuration files.  If you have installed NCIPServer
  62 to some other location, you will need to modify the path to the
  63 templates in two files:
  64
  65 . The "views" entry on line 8 of config.yml
  66 . The value attribute of the templates tag in t/config_sample/NCIP.xml.
  67
  68 Both locations require the full path to the templates directory.
  69
  70 Configuring Evergreen for NCIPServer
  71 ------------------------------------
  72
  73 NCIPServer integrates very tightly with Evergreen's way of doing
  74 things.  You will need to do some configuration in Evergreen to add
  75 organizational units, users, and circ and hold rules.
  76
  77 NCIP Virtual Organizational Unit
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 Evergreen expects transactions to take place at a given location.
  81 NCIPServer is no exception to this rule, and so an organizational unit
  82 needs to be used as the home for virtual patrons, the working location
  83 for virtual staff, as the location where holds are to be sent, and as
  84 the place where remote circulations happen in Evergreen.  We recommend
  85 creating a new System and Branch in Evergreen for that purpose.  When
  86 you set these up, you should make sure that OPAC visible is set to
  87 false.--You do not want regular patrons seeing this location and trying
  88 to pick up their holds there.--You may, of course, reuse an existing
  89 location that you may have already established for a similar purpose.
  90 You definitely do not want to use an organizational unit associated
  91 with a real branch in your Evergreen.
  92
  93 NCIP Staff User
  94 ~~~~~~~~~~~~~~~
  95
  96 NCIPServer requires an Evergreen account that can conduct basic staff
  97 functions in circulation and cataloging.  These permissions can be
  98 assigned to the user or to a new permission group that is then
  99 assigned as the new user's profile.  This new permission group should
 100 not have a parent group so that the user will not inadvertently
 101 inherit any problematic permissions.
 102
 103 Thes user will need to have its working location (work_ou) set to the
 104 virtual branch that represents the remote locations, and it will need
 105 to have a workstation registered for its use.  This workstation does
 106 not need to be registered via the staff client.  It only needs to exist
 107 in the database.  Registering it via the staff client may be the
 108 easiest way to do it.
 109
 110 Permissions
 111 ^^^^^^^^^^^
 112
 113 The following table shows the permissions required by the NCIPServer
 114 staff user.  The first column is the permission code and the second is
 115 the organizational unit depth it is required to be granted at for
 116 everything to work smoothly.  The depths, of course, assume that you
 117 are using a more or less standard, three-level hierarchy of Consortium
 118 -> System -> Branch.  If not, you may need to adjust the depths of the
 119 permissions accordingly.  Also, the permissions should not be
 120 grantable, since no one should ever switch to this user via the staff
 121 client.
 122
 123 .NCIP Staff User Permissions
 124 [options="header",cols="<,^"]
 125 |===========================
 126 | code | depth
 127 | ABORT_TRANSIT | 2
 128 | CANCEL_HOLDS | 1
 129 | COPY_ALERT_MESSAGE.override | 0
 130 | COPY_CHECKIN | 2
 131 | COPY_CHECKOUT | 2
 132 | COPY_HOLDS | 0
 133 | COPY_HOLDS_FORCE | 2
 134 | COPY_TRANSIT_RECEIVE | 2
 135 | CREATE_COPY | 0*
 136 | CREATE_COPY_STAT_CAT_ENTRY | 2
 137 | CREATE_COPY_STAT_CAT_ENTRY_MAP | 2
 138 | CREATE_COPY_TRANSIT | 0
 139 | CREATE_MARC | 0
 140 | CREATE_TRANSIT | 0
 141 | CREATE_VOLUME | 2
 142 | DELETE_COPY | 0*
 143 | DELETE_VOLUME | 2
 144 | IMPORT_MARC | 0
 145 | PATRON_EXCEEDS_CHECKOUT_COUNT.override | 0
 146 | PATRON_EXCEEDS_FINES.override | 0
 147 | PATRON_EXCEEDS_OVERDUE_COUNT.override | 0
 148 | REQUEST_HOLDS | 0
 149 | STAFF_LOGIN | 0
 150 | TITLE_HOLDS | 0
 151 | UPDATE_COPY | 0*
 152 | UPDATE_MARC | 0
 153 | UPDATE_VOLUME | 2
 154 | VIEW_HOLD | 0
 155 | VIEW_HOLD_PERMIT | 0
 156 | VIEW_PERMIT_CHECKOUT | 0
 157 | VIEW_USER | 0
 158 | VOLUME_HOLDS | 0
 159 |================================
 160
 161 *The depth for create, update and delete copy permissions need to be
 162 set to 0 if you are using the pre-cat copies option.  If not, a depth
 163 of 1 or 2 should be sufficient.
 164
 165 NCIP Virtual Patrons
 166 ~~~~~~~~~~~~~~~~~~~~
 167
 168 NCIPServer expects barcodes in the user ID and other fields when
 169 placing holds and circulating local copies for remote institutions.
 170 You will, of course, need to create these patrons in Evergreen.  Their
 171 home library should be the virtual branch created for the NCIPServer
 172 staff account.  You could use multiple branches, one for each library
 173 for instance, but that could lead to more complication than you may
 174 want to deal with.
 175
 176 Your ILL vendor may provide a list of patrons with barcodes for the
 177 participating member libraries.
 178
 179 The virtual patrons typically require no additional permissions beyond
 180 what is allowed to normal patrons.  It is a good idea to create a new
 181 permission group as a child of your existing Patron group or one of
 182 its descendants.  This makes it clear to any staff that these patrons
 183 are special.
 184
 185 Circulation and Hold Matrix Matchpoints
 186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 187
 188 Remote circulations and holds will take place at the NCIPServer
 189 virtual organizational unit.  This organizational unit will need to
 190 have hold and circ matrix matchpoints that conform to whatever rules
 191 you have worked out with your vendor and other partners.  You may want
 192 to use an extended loan period, perhaps as much as double the normal
 193 interval.  The reason for this is that some ILL software will check
 194 the copy out in Evergreen when the sending library sets it to shipped.
 195
 196 You should not need reciprocal rules for incoming items.  Your normal
 197 circulation matchpoints should work.  You may need matchpoints to
 198 allow the holds depending on how you have configured things already,
 199 i.e. you may have a default that does not allow holds that you will
 200 need to override.
 201
 202 oils_ncip.xml
 203 -------------
 204
 205 The oils_ncip.xml file sets the options for the Evergreen driver.  It
 206 needs to be configured appropriately given your Evergreen settings and
 207 operating environment.
 208
 209 You will need to copy or move the oils_ncip.xml.example file found in
 210 the examples/ subdirectory to your /openils/conf directory or wherever
 211 you store your regular Evergreen configuration files, i.e. where you
 212 put opensrf_core.xml and opensrf.xml.
 213
 214 The example file should be renamed to oils_ncip.xml during the copy
 215 process.  Assuming that you are still in the root of your clone of the
 216 NCIPServer repository, the following command should take care of it:
 217
 218 [source,sh]
 219 cp examples/oils_ncip.xml.example /openils/conf/oils_ncip.xml
 220
 221 The following subsections describe the configuration tags from this
 222 file.
 223
 224 Credentials
 225 ~~~~~~~~~~~
 226
 227 You will need to enter the username, password, work ou., and
 228 workstation for the NCIP virtual staff user for Evergreen in the
 229 credentials section of the oils_ncip.xml file.  The workstation
 230 information needs the work_ou branch's short name prefixed to it with
 231 a dash if you registered the workstation via the staff client or if
 232 you included the shortname when inserting the workstation into the
 233 database.
 234
 235 Bootstrap
 236 ~~~~~~~~~
 237
 238 NCIPServer needs to know where to find the opensrf_core.xml
 239 configuration file.  This is typically /openils/conf/opensrf_core.xml,
 240 but you may have installed it elsewhere.
 241
 242 Items
 243 ~~~~~
 244
 245 use_precats
 246 ^^^^^^^^^^^
 247
 248 Despite what the comment in the config file says, you do not want to
 249 use this setting.  It does not do what is expected in Evergreen at
 250 this time.  The setting remains in the configuration file in
 251 anticipation of the day that it will work properly.
 252
 253 use_force_holds
 254 ^^^^^^^^^^^^^^^
 255
 256 The use_force_holds setting will cause force holds to be placed on
 257 copies created by the AcceptItem message. This will also cause those
 258 copies not to be holdable. The latter only takes effect when
 259 use_precats is not in operation, since there is no other way to place
 260 holds on precat copies.
 261
 262 bib_source
 263 ^^^^^^^^^^
 264
 265 The bib_source setting is recommended if you do not use precat copies.
 266 If it is not present, a default of System Local will be used.
 267
 268 It will be used as the bibliographic record source when the "short"
 269 bibs are created.  Having a unique entry for this in your database
 270 makes it easy to identify bibliographic records created via NCIP.  It
 271 is highly recommended that you create one just for this purpose.
 272
 273 The element can be set up empty with the cbs attribute holding the
 274 database ID of the config.bib_source entry to use.  You can optionally
 275 set the text value of the element to the name of the bib_source.  If
 276 the cbs attribute is omitted, then the text value name must be
 277 provided.  The example provided below will use the System Local
 278 config.bib_source that comes with Evergreen.
 279
 280 stat_cat_entry
 281 ^^^^^^^^^^^^^^
 282
 283 Add a stat_cat_entry element for each stat cat that you wish to fill
 284 in when creating copies. If you aren't using stat_cats or if you don't
 285 wish to create any for these, you don't need to have stat_cat_entry
 286 elements. You could delete the dummy entry in this case.  If you have
 287 any required stat cats, then it is a good idea to have an entry here.
 288
 289 The stat_cat attribute is the numeric id of the stat_cat for the
 290 entry.
 291
 292 The element's text node is used as the asset.stat_cat_entry's value in
 293 the database.
 294
 295 Patrons
 296 ~~~~~~~
 297
 298 block_profile
 299 ^^^^^^^^^^^^^
 300
 301 You can block patrons by profile group in two ways:
 302
 303 The first is to enter a block_profile tag with a grp attribute set to
 304 the value of the profile group's id, for example:
 305
 306 --------------------------------------------------------------------
 307          <block_profile grp="20"/>
 308 --------------------------------------------------------------------
 309
 310 The second is to enter a block_profile tag with a text value equal to
 311 the name of the profile group, for instance:
 312
 313 --------------------------------------------------------------------
 314          <block_profile>Local Use Only</block_profile>
 315 --------------------------------------------------------------------
 316
 317 In this case, the name must match exactly the case, spacing, and
 318 punctuation (if any) of the profile group's name in the
 319 permission.grp_tree table.
 320
 321 If you specify both the grp attribute and a text value with a group
 322 name, then the value of the grp tag is used. The text value will be
 323 ignored:
 324
 325 --------------------------------------------------------------------
 326          <block_profile grp="20">Local Use Only</block_profile>
 327 --------------------------------------------------------------------
 328
 329 You might want to do this in order to have the group name as a
 330 reminder to the person that edits the configuration.
 331
 332 Holds
 333 ~~~~~
 334
 335 abort_transits_on_cancel
 336 ^^^^^^^^^^^^^^^^^^^^^^^^
 337
 338 If you want to have transits aborted when holds are canceled via NCIP,
 339 then move the <abort_transits_on_cancel/> tag outside of the enclosing
 340 XML comment block so that is still inside the <holds> open and close
 341 tags.
 342
 343 WARNING: You may need to delete the comment block in this section if
 344 you do not move the abort_transit_on_cancel setting to be outside of
 345 the comment block.  There appears to be a bug in the config file
 346 parser that uses this comment as a setting value.  This leads to
 347 server errors whenever NCIP is accessed.11
 348
 349 Configuring Apache for NCIPServer
 350 ---------------------------------
 351
 352 You will need to add a configuration block so that Apache is able to
 353 execute the NCIPServer code when the URL is accessed.  The
 354 configuration varies depending on Apache version. Examples for
 355 versions 2.2 and 2.4 are provided.  You could add this to your
 356 eg_vhost.conf and the NCIP location will be available from your
 357 catalog.  You could create a new virtual host for the NCIPServer and
 358 add this configuration there.  If you use load balancing in front of
 359 your Apache server, then you will need to do the installation and
 360 configuration steps on each server that runs Apache.
 361
 362 You will, of course, need to restart Apache after making these
 363 configuration changes.  If all goes well, NCIPServer should be up and
 364 running at a location of /NCIP/ on your server.
 365
 366 Apache 2.2
 367 ~~~~~~~~~~
 368
 369 --------------------------------------------------------------------
 370 <Directory "/home/opensrf/NCIPServer">
 371     AllowOverride None
 372 </Directory>
 373 <Location /NCIP/>
 374     SetHandler perl-script
 375     PerlResponseHandler Plack::Handler::Apache2
 376     PerlSetVar psgi_app /home/opensrf/NCIPServer/bin/ncip_dancing.pl
 377     PerlSetEnv NCIP_CONFIG_DIR "/home/opensrf/NCIPServer/t/config_sample"
 378     PerlSetEnv OILS_NCIP_CONFIG /openils/conf/oils_ncip.xml
 379     PerlSetEnv DANCER_ENVIRONMENT "production"
 380     Order deny,allow
 381     Deny from all
 382     Allow from 10.0.0.0/8
 383 </Location>
 384 --------------------------------------------------------------------
 385
 386 Apache 2.4
 387 ~~~~~~~~~~
 388
 389 --------------------------------------------------------------------
 390 <Directory "/home/opensrf/NCIPServer">
 391     AllowOverride None
 392 </Directory>
 393 <Location /NCIP/>
 394     SetHandler perl-script
 395     PerlResponseHandler Plack::Handler::Apache2
 396     PerlSetVar psgi_app /home/opensrf/NCIPServer/bin/ncip_dancing.pl
 397     PerlSetEnv NCIP_CONFIG_DIR /home/opensrf/NCIPServer/t/config_sample
 398     PerlSetEnv OILS_NCIP_CONFIG /openils/conf/oils_ncip.xml
 399     PerlSetEnv DANCER_ENVIRONMENT "production"
 400     Require ip 10.0.0.0/8
 401  </Location>
 402 --------------------------------------------------------------------
 403
 404 Security
 405 ~~~~~~~~
 406
 407 NCIPServer does not require any authentication from the client, so it
 408 would behoove you to restrict access to the NCIP location to a limited
 409 number of Internet hosts. The configuration examples for Apache 2.2
 410 and 2.4 above restrict access to the 10.0.0.0/8 private network. You
 411 will need to change that entry to whatever your vendor uses.  You can
 412 more Allow from or Require ip entries for other vendors and/or
 413 hosts. It is also a good idea to allow of your own ips to connect for
 414 testing purposes.