578ca0ea8ba3c4e236f13ce75485b3dc1479ce3a
[working/Evergreen.git] / docs / RELEASE_NOTES_3_2.adoc
1 Evergreen 3.2 Release Notes
2 ===========================
3 :toc:
4 :numbered:
5
6 Upgrade notes
7 -------------
8
9 TODO
10
11 New Features
12 ------------
13
14
15
16 Acquisitions
17 ~~~~~~~~~~~~
18
19
20
21 Auto-Cancel Lineitems When All Copies Are Canceled
22 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
23 When a copy (lineitem detail) is canceled through the Acquisitions interface, 
24 the parent lineitem is also canceled if all copies for that lineitem are also 
25 canceled.  The cancel reason given will come from:
26
27 1. The cancel reason for the just-canceled copy if it's a Keep Debits true 
28    cancel reason.
29 2. The cancel reason from any other copy on the lineitem that has a Keep 
30    Debits true cancel reason.
31 3. The cancel reason for the just-canceled copy if no copies have a Keep
32    Debits true cancel reason.
33   
34
35
36
37
38 Invoice Closed Date and Closed By Fields
39 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
40 Acquisitions invoices have 2 new fields:
41
42 * Close Date -- This is set to the time when the ACQ user clicks the "Close"
43   button in the invoice interface.
44   ** This field 'replaces' the existing 'complete' field.  An invoice is
45      considered complete if a close date value is set.
46 * Closed By -- This is set to the logged in staff user who performs the 
47   "Close" action.
48
49 As with the now-defunct 'complete' field, but new fields are cleared in the 
50 event an invoice is reopened.
51
52 These new fields are visible in the invoice interface under the 
53 'Show Details' action for closed invoices.
54
55 Upgrading Invoice Reports
56 +++++++++++++++++++++++++
57
58 Existing report templates that reference the invoice 'complete' field 
59 should be modified to check whether the new close_date field is NOT NULL
60 instead.
61
62 Other Upgrade Considerations
63 ++++++++++++++++++++++++++++
64
65 At deploy time, all invoices with a 'complete' value of TRUE will have their
66 'close_date' field set to NOW.  A value is required, since this field is
67 now the source of whether an invoice is open or closed.
68
69 However, no values will be applied to the closed_by field for already closed
70 invoices.
71
72
73
74
75
76
77 Patron Acquisitions Requests
78 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
79
80 The existing interface for staff-mediated patron acquisition requests has been replaced in the web staff client with a re-implementation written in AngularJS, with some minor bug fixes (including access from the Patron interface) and other improvements.
81
82
83
84
85
86 Cataloging
87 ~~~~~~~~~~
88
89
90
91 Add UPC to z39.50 search for OCLC and LOC
92 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
93 Add UPC as a search attribute for both OCLC and LOC targets in
94 z39.50 for cataloging.
95
96
97
98
99 Asynchronous Vandelay Imports
100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101
102 Vandelay imports are now monitored from the browser client asynchronously,
103 meaning the client requests updates from the server instead of waiting for 
104 the server to respond to the original import request.  This changes allows 
105 for incremental progress updates in the browser client.
106
107 New Database Table
108 ++++++++++++++++++
109
110 This adds a new database table vandelay.session_tracker for tracking
111 in-progress vandelay upload activity.  A new tracker row is added for
112 each of "upload", "enqueue", and "import" actions, linked for a given
113 session by the value stored in the "session_key" field.
114
115 The table tracks other potentially useful data, like the staff member
116 and workstation where the action was performed.
117
118 Upgrade notes
119 +++++++++++++
120 Users of NGINX as a reverse proxy may need to set a suitable
121 `client_max_body_size` value in the NGINX configuration so that large
122 MARC record uploads are not truncated. Note that this would have
123 always been necessary, but since this feature allows larger files
124 to be more reliably queued and imported, the need to set `client_max_body_size`
125 became more apparent.
126
127
128
129
130 Support for Last Inventory Date
131 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
132 Evergreen now provides an option to add an inventory date to items to facilitate
133 the process of performing inventory in libraries. Staff can add an inventory
134 date to an item in one of the following ways:
135  * From the check in screen, there is now an Update Inventory check in modifier.
136 When selected, scanned barcodes will have the current date/time added as the
137 inventory date while the item is checked in.
138  * From the Item Status screen, an action is available to add the current 
139 date/time as the inventory date to selected items.
140
141 This new feature will also store the workstation that was used when the
142 inventory date was updated.
143
144
145
146
147
148 Parallel Ingest with pingest.pl
149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
150 A program named pingest.pl is now installed to allow faster record
151 ingest.  It performs ingest in parallel so that multiple batches can
152 be done simultaneously.  It operates by splitting the records to be
153 ingested up into batches and running all of the ingest methods on each
154 batch.  You may pass in options to control how many batches are run at
155 the same time, how many records there are per batch, and which ingest
156 operations to skip.
157
158 NOTE: The browse ingest is presently done in a single process over all
159 of the input records as it cannot run in parallel with itself.  It
160 does, however, run in parallel with the other ingests.
161
162 Command Line Options
163 ++++++++++++++++++++
164 pingest.pl accepts the following command line options:
165
166 --host::
167     The server where PostgreSQL runs (either host name or IP address).
168     The default is read from the PGHOST environment variable or
169     "localhost."
170
171 --port::
172     The port that PostgreSQL listens to on host.  The default is read
173     from the PGPORT environment variable or 5432.
174
175 --db::
176     The database to connect to on the host.  The default is read from
177     the PGDATABASE environment variable or "evergreen."
178
179 --user::
180     The username for database connections.  The default is read from
181     the PGUSER environment variable or "evergreen."
182
183 --password::
184     The password for database connections.  The default is read from
185     the PGPASSWORD environment variable or "evergreen."
186
187 --batch-size::
188     Number of records to process per batch.  The default is 10,000.
189
190 --max-child::
191     Max number of worker processes (i.e. the number of batches to
192     process simultaneously).  The default is 8.
193
194 --skip-browse::
195 --skip-attrs::
196 --skip-search::
197 --skip-facets::
198 --skip-display::
199     Skip the selected reingest component.
200
201 --start-id::
202     Start processing at this record ID.
203
204 --end-id::
205     Stop processing when this record ID is reached.
206
207 --pipe::
208     Read record IDs to reingest from standard input.  This option
209     conflicts with --start-id and/or --end-id.
210
211 --max-duration::
212     Stop processing after this many total seconds have passed.  The
213     default is to run until all records have been processed.
214
215 --help::
216     Show the help text.
217
218
219
220
221
222 View Authority Record by Database ID
223 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
224
225 A new interface allows catalogers to retrieve a specific
226 authority record using its database ID.  Catalogers can
227 find those IDs in subfield $0 of matching fields in
228 bibliographic records.
229
230 To use the new authority record viewer:
231
232 . Click *Cataloging -> Retrieve Authority Record by ID*.
233 . Type in the ID number of the authority record you are
234 interested in. Don't include any prefixes, just the ID
235 number.
236 . Click *Submit*.
237 . View or edit the authority record as needed.
238
239
240
241
242
243 Circulation
244 ~~~~~~~~~~~
245
246
247
248 Autorenewal of Loans
249 ^^^^^^^^^^^^^^^^^^^^
250 Circulation policies in Evergreen can now be configured to automatically renew
251 certain items checked out on patron accounts. Circulations will be renewed
252 automatically up to a custom limit (the `max_auto_renewal` field) and patrons
253 will not need to log in to their OPAC accounts or ask library staff to manually
254 renew materials.
255
256 Two new action triggers have been added to Evergreen that permit the Auto-Renew
257 feature. They can be found, configured, and enabled in Administration>Local
258 Administration>Notifications/Action Triggers. They are named **Autorenew** and
259 **AutorenewNotify**.
260
261 The **Autorenew** A/T definition uses the `checkout.due` hook to automatically
262 validate and renew (in the reactor) circulations on the day they are due,
263 grouped by user. The output events of this definition is is the input used by
264 the related **AutorenewNotify** A/T that simply uses a new hook called
265 `autorenewal` to notify patrons via email of their currently due or
266 auto-renewed items.
267
268 In the webstaff's Patron Items Out page, the new column `AutoRenewalsRemaining`
269 indicates how many autorenewals are available for a particular circulation.
270
271
272
273
274
275 Emergency Closing Handler
276 ^^^^^^^^^^^^^^^^^^^^^^^^
277
278 Staff are provided with interfaces and mechanisms to create library closings that, in addition to affecting future circulation and booking due dates, and hold shelf expirations, will automatically move existing circulation and booking due dates and hold shelf expiration times. This new functionality is conceptually described as Emergency Closings and business logic implementing it as the Emergency Closing Handler. It contains additions and adjustments to the user interface, business logic, and database layers. Access to this functionality is available through the Closed Dates Editor interface in the staff client which has been ported to AngularJS.
279
280 Overview
281 ++++++++
282
283 This development has created new business logic code to inspect, in real time, existing circulation, booking, and hold records, and modify such date and time stamps so that the circulation, booking, or hold will end in the same state it would have if the closing had existed at the time the circulation or booking occurred, or the hold was placed and captured. Of specific note, hourly loans will have their due date adjusted to be the end of the day following the closing.
284
285 When the Emergency Closing is saved, any fines accrued during the closing may be voided, as settings dictate, with the exception of circulations that have been marked as LOST or LONG OVERDUE. That is, even for LOST and LONG OVERDUE circulations with due dates that fall within the Emergency Closing, no fine adjustment will be applied. Emergency Closing processing is permanent, and cannot be rolled back.
286
287 This functionality is explicitly initiated by staff action. If staff do not request an Emergency Closing, existing circulations, bookings, and holds will not be processed and adjusted. However, if staff request any Closing that starts nearer in time than the length of the longest circulation duration configured for use in the Evergreen instance they will be prompted with the option to create the closing as an Emergency Closing.
288
289 Action/Trigger hooks have been created for circulations and bookings that are adjusted by the Emergency Closing Handler. These will facilitate the creation of notifications to patrons that the due date has changed and to alert them to potential changes in accrued fines.
290
291 Booking start dates are explicitly ignored in this implementation. Because an Emergency Closing is, by its nature, an unexpected event, it will be up to staff to address any bookings which intersect with a new Emergency Closings. Reports can be used to identify booking start dates that overlap with a closing and that may require staff intervention.
292
293 Staff requsting and Emergency Closing must have the new EMERGENCY_CLOSING permission.
294 Some text describing the feature.
295
296
297
298
299
300 Patron Preferred Name and Name Search Keywords
301 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
302
303 Preferred Name
304 ++++++++++++++
305
306 Adds a new set of patron preferred name fields for prefix, first,
307 middle, last, and suffix allowing patrons to provide preferred name
308 information.  Preferred names are optional and each acts as an overlay
309 to the analogous primary name field, making it possible to provide
310 preferred name values for individual fields.
311
312 For example, a patron named William Erickson may have a preferred first
313 name (pref_first_given_name) of Bill, in which case the preferred name
314 would be Bill Erickson.  Note a preferred last name is not required in
315 this case as the code uses primary name values as defaults when not
316 replaced with a preferred version.
317
318 * Patrons will see primary names displayed in the catalog when set.
319 * Staff will see both primary name and preferred name in the patron
320   summary side bar.
321 * Patron searches for any given name field will search both the primary
322   and preferred name data.
323 * Preferred name fields are available in Action/Trigger templates and
324   are present in various patron-focused print templates.
325
326 Name Keywords
327 ++++++++++++++
328
329 Adds a new field to store miscellaneous patron name search terms.  These
330 values are only for searching and do not appear in any interfaces, apart
331 from the patron summary side bar and the patron edit UI.
332
333 Included is a new search field in the patron search UI which searches
334 keyword values and all other name fields.  It's essentially a global patron
335 name keyword search.
336
337
338
339
340 Client
341 ~~~~~~
342
343
344
345 Permission Group Display Entries
346 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
347 In some cases, it is useful to have the ability to reorder permission, or to make
348 only specific groups available in the permission group selector for specific
349 Org Units. An interface has been made available to allow this.
350
351 Group Tree Display Entry Interface
352 ++++++++++++++++++++++++++++++++++
353
354 Permission Group Display Entries can be reordered, added, or removed via
355 _Administration -> Local Admin -> Permission Tree Display Entries_.
356 Select the Org Unit you wish to edit the entries in.
357
358 Entries may be added using the Add functionality, creating entries based
359 on permission groups that have not been added to the tree for the Org
360 Unit you wish to add them to.
361
362 image::media/pgtde_01.png[Group Tree Display Entry Admin UI]
363
364 Moving an Entry
365 +++++++++++++++
366 Moving an entry will shift its position up or down in the patron profile
367 selector for a given Org Unit.
368
369 * Select an entry
370 * Press either the *Move Up* or *Move Down* button. The entry will be 
371 moved up or down, accordingly.
372 * Click *Save* to save your edits.  
373
374 NOTE: You may only move up or down entries that have sibling entries.
375
376 Removing an Entry
377 +++++++++++++++++
378 If you want a particular Org Unit to not have access to specific
379 entries, you may remove an entry. Removing an entry will remove it from 
380 view. The entry will be removed from the database.
381
382 * Select an entry and press the *Remove* button.
383
384 Adding an Entry
385 +++++++++++++++
386 You may add entries from permission groups that are not currently
387 reflected in the permission group tree. This is useful for moving 
388 entries to different parents, or making them root entries.
389
390 image::media/pgtde_02.png[Add Entry modal]
391
392 * If desired, select an entry to be used as the parent entry. 
393 * Press the *Add* button. 
394 * Select a permission group from the dropdown.
395 * If you've selected a parent entry, you may check the *Add Root Entry*
396 box to override that parent and add the entry on the root level. 
397 * If you did not select a parent entry, the entry will be added on the root 
398 level of the tree.
399
400
401
402 Browser Client Settings & Preferences Stored on the Server
403 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
404 Browser cilent settings and preferences that should persist over time are
405 now stored as settings on the server.  This allows settings to follow
406 users and workstations and reduces problems associated with losing settings 
407 as a result of clearing browser data.
408
409 The browser client honors setting values stored as user settings, workstation
410 settings, and org unit settings, depending on which setting types are
411 locally configured.
412
413 Setting Types
414 +++++++++++++
415
416 * No setting can be both a user and workstation setting.  They are mutually
417   exclusive.
418 * Any setting can be an org unit setting in addition to being a user or
419   workstaion setting.
420
421 Read-Only Settings
422 ++++++++++++++++++
423
424 Read-only settings are useful for defining values that staff can use but
425 not modify.  For example, admins may wish to prevent users from locally
426 modifying the grid configuration for a given interface so it remains
427 consistent for all users.
428
429 A setting is read-only when an org unit setting type exists (regardless of 
430 whether a value is applied) and no user or workstation setting type exists.
431
432 Server-Stored Workstation Settings Workstation Admin View
433 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
434
435 There's a new "Server Workstation Prefs" tab to the stored preferences
436 workstation admin interface.  From here, users can view which
437 preferences are stored as server-stored workstation preferences and
438 delete select values.
439
440 Upgrade Notes
441 +++++++++++++
442
443 A new permission APPLY_WORKSTATION_SETTING has been added to control who
444 may apply values to workstation settings.  Use something like the following
445 to apply the permission to all staff accounts (mileage may vary):
446
447 [source,sh]
448 --------------------------------------------------------------------------
449 INSERT INTO permission.grp_perm_map (grp, perm, depth) 
450 VALUES (
451     (SELECT id FROM permission.grp_tree WHERE name = 'Staff'), -- name may vary
452     (SELECT id FROM permission.perm_list WHERE code = 'APPLY_WORKSTATION_SETTING'),
453     0 -- or 1, 2, etc.
454 );
455 --------------------------------------------------------------------------
456
457 Workstation setting types matching values previously stored in the browser
458 (via localStorage or Hatch) are created as part of this feature.  During
459 upgrade, admins should consider whether any of these new setting types 
460 should be transferred to user and/or org unit settings instead.  Setting
461 type changes can be made at any time, but when a setting type is deleted
462 all of its data is deleted, so a change in type means re-applying the 
463 settings in the browser client.
464
465 Values stored in the browser will automatically migrate to server settings
466 as each setting is accessed in the browser client.  Once migrated, the
467 in-browser copies are deleted.  
468
469 If a setting type does not exist where the browser expects one, the 
470 value is stored in-browser instead and a warning is issued in the console.
471
472
473
474
475
476
477 OPAC
478 ~~~~
479
480
481
482 Batch Actions In the Public Catalog
483 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
484 The public catalog now displays checkboxes on the bibliographic and
485 metarecord constituents results pages. Selecting one or more titles
486 by using the checkboxes will dynamically add those title to the
487 temporary list, which is now renamed the cart.
488
489 Above the results lists there is now a bar with a select-all checkbox,
490 a link to the cart management page that also indicates the number of
491 of titles in the cart, and a link to remove from the cart titles that
492 are selected on the currently displayed results page.
493
494 The search bar now includes an icon of a cart and displays the number
495 of titles currently in the cart. Next to that icon is a menu of cart
496 actions.
497
498 The cart actions available are Place Hold, Print Title Details,
499 Email Title Details, Add Cart to Saved List, and Clear Cart. In the
500 web staff client, the cart actions also include Add Cart to Bucket.
501 When an action is selected from this menu, the user is given an
502 opportunity to confirm the action and to optionally empty the cart
503 when the action is complete. The action is applied to all titles
504 in the cart.
505
506 Clicking on the cart icon brings the user to a page listing the
507 titles in the cart. From there, the user can select specific records
508 to request, print, email, add to a list, or remove from the cart.
509
510 The list of actions on the record details page now provides separate
511 links for adding the title to a cart or to a permanent list.
512
513 The permanent list management page in the public catalog now also
514 includes batch print and email actions.
515
516 Additional information
517 ++++++++++++++++++++++
518 * The checkboxes do not display on the metarecord results page, as
519   metarecords currently cannot be put into carts or lists.
520 * The checkboxes are displayed only if Javascript is enabled. However,
521   users can still add items to the cart and perform batch actions on
522   the cart and on lists.
523 * A template `config.tt2` setting, `ctx.max_cart_size`, can be used to
524   set a soft limit on the number of titles that can be added to the
525   cart. If this limit is reached, checkboxes to add more records to the
526   cart are disabled unless existing titles in the cart are removed
527   first. The default value for this setting is 500.
528
529 Developer notes
530 +++++++++++++++
531
532 This patch adds the the public catalog two routes that return JSON
533 rather than HTML:
534
535 * `GET /eg/opac/api/mylist/add?record=45`
536 * `GET /eg/opac/api/mylist/delete?record=45`
537
538 The JSON response is a hash containing a mylist key pointing to the list
539 of bib IDs of contents of the cart.
540
541 The record parameter can be repeated to allow adding or removing
542 records as an atomic operation. Note that this change also now available
543 to `/eg/opac/mylist/{add,delete}`
544
545 More generally, this adds a way for EGWeb context loaders to specify that
546 a response should be emitted as JSON rather than rendering an HTML
547 page using `Template::Toolkit`.
548
549 Specifically, if the context as munged by the context loader contains
550 a `json_response` key, the contents of that key will to provide a
551 JSON reponse. The `json_response_cookie` key, if present, can be used
552 to set a cookie as part of the response.
553
554 Template Toolkit processing is bypassed entirely when emitting a JSON
555 response, so the context loader would be entirely reponsible for
556 localization of strings in the response meant for direct human
557 consumption.
558
559
560
561
562 New class for searchbar when on the homepage
563 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
564
565 This adds the `.searchbar-home` class to the div that
566 contains the searchbar when on the homepage.  This allows
567 sites to customize the searchbar differently on the
568 homepage than in other places the
569 search bar appears (for example, offering a large,
570 Google-style search bar on the homepage only).
571
572
573
574
575
576 Username Login Hint
577 ^^^^^^^^^^^^^^^^^^^
578 To make customization easier, the username hint on the OPAC login page ("Please
579 include leading zeros...") has been moved to a separate TT2 template.  If you
580 have customized the hint text, you will need to add your modifications to
581 username_hint.tt2.
582
583
584
585 Acknowledgments
586 ---------------
587 The Evergreen project would like to acknowledge the following
588 organizations that commissioned developments in this release of
589 Evergreen:
590
591 TODO
592
593 We would also like to thank the following individuals who contributed
594 code, translations, documentations patches and tests to this release of
595 Evergreen:
596
597 * Eva Cerninakova
598 * Bill Erickson
599 * Jason Etheridge
600 * Francisco J Guel-Mendoza
601 * Jennifer Pringle
602 * Mike Rylander
603 * Jane Sandberg
604 * Stephan Woidowski
605
606 We also thank the following organizations whose employees contributed
607 patches:
608
609 * Equinox Open Library Initiative
610 * King County Library System
611
612 We regret any omissions.  If a contributor has been inadvertently
613 missed, please open a bug at http://bugs.launchpad.net/evergreen/
614 with a correction.
615