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.
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.
21 * libconfig-merge-perl
24 * libxml-libxml-simple-perl
30 Installing the NCIPServer software is as simple as
33 git clone git://git.evergreen-ils.org/NCIPServer.git
35 You should do the above in the opensrf user's home directory for ease
36 of installation. If you put it elsewhere, you will need to modify a
37 couple of the NCIPServer configuration file entries as described in
43 If you use the default installation location of
44 /home/opensrf/NCIPServer, then you do not need to make any changes to
45 the NCIPServer configuration files. If you have installed NCIPServer
46 to some other location, you will need to modify the path to the
47 templates in two files:
49 . The "views" entry on line 8 of config.yml
50 . The value attribute of the templates tag in t/config_sample/NCIP.xml.
52 Both locations require the full path to the templates directory.
54 Configuring Evergreen for NCIPServer
55 ------------------------------------
57 NCIPServer integrates very tightly with Evergreen's way of doing
58 things. You will need to do some configuration in Evergreen to add
59 organizational units, users, and circ and hold rules.
61 NCIP Virtual Organizational Unit
62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64 Evergreen expects transactions to take place at a given location.
65 NCIPServer is no exception to this rule, and so an organizational unit
66 needs to be used as the home for virtual patrons, the working location
67 for virtual staff, as the location where holds are to be sent, and as
68 the place where remote circulations happen in Evergreen. We recommend
69 creating a new System and Branch in Evergreen for that purpose. When
70 you set these up, you should make sure that OPAC visible is set to
71 false.--You do not want regular patrons seeing this location and trying
72 to pick up their holds there.--You may, of course, reuse an existing
73 location that you may have already established for a similar purpose.
74 You definitely do not want to use an organizational unit associated
75 with a real branch in your Evergreen.
80 NCIPServer requires an Evergreen account that can conduct basic staff
81 functions in circulation and cataloging. These permissions can be
82 assigned to the user or to a new permission group that is then
83 assigned as the new user's profile. This new permission group should
84 not have a parent group so that the user will not inadvertently
85 inherit any problematic permissions.
87 Thes user will need to have its working location (work_ou) set to the
88 virtual branch that represents the remote locations, and it will need
89 to have a workstation registered for its use. This workstation does
90 not need to be registered via the staff client. It only needs to exist
91 in the database. Registering it via the staff client may be the
97 The following table shows the permissions required by the NCIPServer
98 staff user. The first column is the permission code and the second is
99 the organizational unit depth it is required to be granted at for
100 everything to work smoothly. The depths, of course, assume that you
101 are using a more or less standard, three-level hierarchy of Consortium
102 -> System -> Branch. If not, you may need to adjust the depths of the
103 permissions accordingly. Also, the permissions should not be
104 grantable, since no one should ever switch to this user via the staff
107 .NCIP Staff User Permissions
108 [options="header",cols="<,^"]
109 |===========================
113 | COPY_ALERT_MESSAGE.override | 0
117 | COPY_HOLDS_FORCE | 2
118 | COPY_TRANSIT_RECEIVE | 2
120 | CREATE_COPY_STAT_CAT_ENTRY | 2
121 | CREATE_COPY_STAT_CAT_ENTRY_MAP | 2
122 | CREATE_COPY_TRANSIT | 0
129 | PATRON_EXCEEDS_CHECKOUT_COUNT.override | 0
130 | PATRON_EXCEEDS_FINES.override | 0
131 | PATRON_EXCEEDS_OVERDUE_COUNT.override | 0
139 | VIEW_HOLD_PERMIT | 0
140 | VIEW_PERMIT_CHECKOUT | 0
143 |================================
145 *The depth for create, update and delete copy permissions need to be
146 set to 0 if you are using the pre-cat copies option. If not, a depth
147 of 1 or 2 should be sufficient.
152 NCIPServer expects barcodes in the user ID and other fields when
153 placing holds and circulating local copies for remote institutions.
154 You will, of course, need to create these patrons in Evergreen. Their
155 home library should be the virtual branch created for the NCIPServer
156 staff account. You could use multiple branches, one for each library
157 for instance, but that could lead to more complication than you may
160 Your ILL vendor may provide a list of patrons with barcodes for the
161 participating member libraries.
163 The virtual patrons typically require no additional permissions beyond
164 what is allowed to normal patrons. It is a good idea to create a new
165 permission group as a child of your existing Patron group or one of
166 its descendants. This makes it clear to any staff that these patrons
169 Circulation and Hold Matrix Matchpoints
170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172 Remote circulations and holds will take place at the NCIPServer
173 virtual organizational unit. This organizational unit will need to
174 have hold and circ matrix matchpoints that conform to whatever rules
175 you have worked out with your vendor and other partners. You may want
176 to use an extended loan period, perhaps as much as double the normal
177 interval. The reason for this is that some ILL software will check
178 the copy out in Evergreen when the sending library sets it to shipped.
180 You should not need reciprocal rules for incoming items. Your normal
181 circulation matchpoints should work. You may need matchpoints to
182 allow the holds depending on how you have configured things already,
183 i.e. you may have a default that does not allow holds that you will
189 The oils_ncip.xml file sets the options for the Evergreen driver. It
190 needs to be configured appropriately given your Evergreen settings and
191 operating environment.
193 You will need to copy or move the oils_ncip.xml.example file found in
194 the examples/ subdirectory to your /openils/conf directory or wherever
195 you store your regular Evergreen configuration files, i.e. where you
196 put opensrf_core.xml and opensrf.xml.
198 The example file should be renamed to oils_ncip.xml during the copy
199 process. Assuming that you are still in the root of your clone of the
200 NCIPServer repository, the following command should take care of it:
203 cp examples/oils_ncip.xml.example /openils/conf/oils_ncip.xml
205 The following subsections describe the configuration tags from this
211 You will need to enter the username, password, work ou., and
212 workstation for the NCIP virtual staff user for Evergreen in the
213 credentials section of the oils_ncip.xml file. The workstation
214 information needs the work_ou branch's short name prefixed to it with
215 a dash if you registered the workstation via the staff client or if
216 you included the shortname when inserting the workstation into the
222 NCIPServer needs to know where to find the opensrf_core.xml
223 configuration file. This is typically /openils/conf/opensrf_core.xml,
224 but you may have installed it elsewhere.
232 Despite what the comment in the config file says, you do not want to
233 use this setting. It does not do what is expected in Evergreen at
234 this time. The setting remains in the configuration file in
235 anticipation of the day that it will work properly.
240 The use_force_holds setting will cause force holds to be placed on
241 copies created by the AcceptItem message. This will also cause those
242 copies not to be holdable. The latter only takes effect when
243 use_precats is not in operation, since there is no other way to place
244 holds on precat copies.
249 The bib_source setting is recommended if you do not use precat copies.
250 If it is not present, a default of System Local will be used.
252 It will be used as the bibliographic record source when the "short"
253 bibs are created. Having a unique entry for this in your database
254 makes it easy to identify bibliographic records created via NCIP. It
255 is highly recommended that you create one just for this purpose.
257 The element can be set up empty with the cbs attribute holding the
258 database ID of the config.bib_source entry to use. You can optionally
259 set the text value of the element to the name of the bib_source. If
260 the cbs attribute is omitted, then the text value name must be
261 provided. The example provided below will use the System Local
262 config.bib_source that comes with Evergreen.
267 Add a stat_cat_entry element for each stat cat that you wish to fill
268 in when creating copies. If you aren't using stat_cats or if you don't
269 wish to create any for these, you don't need to have stat_cat_entry
270 elements. You could delete the dummy entry in this case. If you have
271 any required stat cats, then it is a good idea to have an entry here.
273 The stat_cat attribute is the numeric id of the stat_cat for the
276 The element's text node is used as the asset.stat_cat_entry's value in
285 You can block patrons by profile group in two ways:
287 The first is to enter a block_profile tag with a grp attribute set to
288 the value of the profile group's id, for example:
290 --------------------------------------------------------------------
291 <block_profile grp="20"/>
292 --------------------------------------------------------------------
294 The second is to enter a block_profile tag with a text value equal to
295 the name of the profile group, for instance:
297 --------------------------------------------------------------------
298 <block_profile>Local Use Only</block_profile>
299 --------------------------------------------------------------------
301 In this case, the name must match exactly the case, spacing, and
302 punctuation (if any) of the profile group's name in the
303 permission.grp_tree table.
305 If you specify both the grp attribute and a text value with a group
306 name, then the value of the grp tag is used. The text value will be
309 --------------------------------------------------------------------
310 <block_profile grp="20">Local Use Only</block_profile>
311 --------------------------------------------------------------------
313 You might want to do this in order to have the group name as a
314 reminder to the person that edits the configuration.
319 abort_transits_on_cancel
320 ^^^^^^^^^^^^^^^^^^^^^^^^
322 If you want to have transits aborted when holds are canceled via NCIP,
323 then move the <abort_transits_on_cancel/> tag outside of the enclosing
324 XML comment block so that is still inside the <holds> open and close
327 WARNING: You may need to delete the comment block in this section if
328 you do not move the abort_transit_on_cancel setting to be outside of
329 the comment block. There appears to be a bug in the config file
330 parser that uses this comment as a setting value. This leads to
331 server errors whenever NCIP is accessed.11
333 Configuring Apache for NCIPServer
334 ---------------------------------
336 You will need to add a configuration block so that Apache is able to
337 execute the NCIPServer code when the URL is accessed. The
338 configuration varies depending on Apache version. Examples for
339 versions 2.2 and 2.4 are provided. You could add this to your
340 eg_vhost.conf and the NCIP location will be available from your
341 catalog. You could create a new virtual host for the NCIPServer and
342 add this configuration there. If you use load balancing in front of
343 your Apache server, then you will need to do the installation and
344 configuration steps on each server that runs Apache.
346 You will, of course, need to restart Apache after making these
347 configuration changes. If all goes well, NCIPServer should be up and
348 running at a location of /NCIP/ on your server.
353 --------------------------------------------------------------------
354 <Directory "/home/opensrf/NCIPServer">
358 SetHandler perl-script
359 PerlResponseHandler Plack::Handler::Apache2
360 PerlSetVar psgi_app /home/opensrf/NCIPServer/bin/ncip_dancing.pl
361 PerlSetEnv NCIP_CONFIG_DIR "/home/opensrf/NCIPServer/t/config_sample"
362 PerlSetEnv OILS_NCIP_CONFIG /openils/conf/oils_ncip.xml
363 PerlSetEnv DANCER_ENVIRONMENT "production"
366 Allow from 10.0.0.0/8
368 --------------------------------------------------------------------
373 --------------------------------------------------------------------
374 <Directory "/home/opensrf/NCIPServer">
378 SetHandler perl-script
379 PerlResponseHandler Plack::Handler::Apache2
380 PerlSetVar psgi_app /home/opensrf/NCIPServer/bin/ncip_dancing.pl
381 PerlSetEnv NCIP_CONFIG_DIR /home/opensrf/NCIPServer/t/config_sample
382 PerlSetEnv OILS_NCIP_CONFIG /openils/conf/oils_ncip.xml
383 PerlSetEnv DANCER_ENVIRONMENT "production"
384 Require ip 10.0.0.0/8
386 --------------------------------------------------------------------
391 NCIPServer does not require any authentication from the client, so it
392 would behoove you to restrict access to the NCIP location to a limited
393 number of Internet hosts. The configuration examples for Apache 2.2
394 and 2.4 above restrict access to the 10.0.0.0/8 private network. You
395 will need to change that entry to whatever your vendor uses. You can
396 more Allow from or Require ip entries for other vendors and/or
397 hosts. It is also a good idea to allow of your own ips to connect for
projects / working / NCIPServer.git / blob