From: Josh Stompro Date: Thu, 23 Feb 2023 17:52:43 +0000 (+0000) Subject: Rename README to README.adoc X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=95bd204d19280696dcb11ab062e57a816c0e9c75;p=NCIPServer.git Rename README to README.adoc Signed-off-by: Josh Stompro --- diff --git a/README b/README deleted file mode 100644 index 08977d2..0000000 --- a/README +++ /dev/null @@ -1,414 +0,0 @@ -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. diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..08977d2 --- /dev/null +++ b/README.adoc @@ -0,0 +1,414 @@ +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.