7c968ca9137ea4087c5c9d67117117b86979b84c
[Evergreen.git] / docs / RELEASE_NOTES_3_1.adoc
1 Evergreen 3.1 Release Notes
2 ===========================
3 :toc:
4 :numbered:
5
6
7 Evergreen 3.1.2
8 ---------------
9 This release contains bug fixes improving on Evergreen 3.1.1.
10
11 * Pins AngularJS support to version 1.6, which prevents unsupported
12 AngularJS versions (such as 1.7) from breaking the build process.
13 * Fixes an issue that caused records with located URIs to be
14 retrieved in Copy Location and Copy Location Group searches.
15 * Fixes an error message that appeared in the search box
16 in the public catalog while placing hold after an advanced search.
17 * Restores the display of copy information for the user's
18 preferred library in the public catalog.
19 * Author and contributor names are no longer highlighted in 
20 search results when the user has turned off highlighting.
21 * Fixes regression errors in the search results page.
22 * Removes redundant call numbers from the Show More Details
23 search results.
24 * Adds spaces between subfields when suggesting a call
25 number for a new volume.
26 * MarcXML exports from the MARC Batch Import/Export ->
27 Export Records screen now downloads the file, rather than opening
28 it in the browser.
29 * Adds some padding to the bottom of Web Client interfaces.
30 * Fixes an issue that prevented users from searching for
31 receivable issues using Database ID or ISSN in the Serials
32 Batch Receive interface.
33 * The Item Status Circulation Library column now displays a
34 shortname rather than the full library name.
35 * The Item Status Remaining Renewals column now displays
36 correctly.
37 * The Item Status now has a "Last Renewal Workstation" column
38 available.
39 * Fixes the circulation counts displayed in Item Status Details.
40 * Fixes an issue with searching patrons by permission group.
41 * Staff members can now manually override the patron juvenile
42 flag value, regardless of the patron's date of birth.
43 * Checkboxes on patron registration screen are now properly aligned
44 with other fields.
45 * The user permission group dropdowns in the patron registration,
46 edit, and search interfaces now have scrollbars.
47 * The Merge Patrons interface now displays the date of birth.
48 * When a patron summary contains an image of the patron,
49 that image tag now has a null alt attribute to remove it from
50 the flow of a screen reader.
51 * The MARC editor now handles 008 fields better.
52 * Fixed field mnemonics in the MARC Editor can now be translated.
53 * Corrects an issue that caused the transit dialog showed the
54 wrong branch.
55 * The cursor in the in-house use screen now automatically goes
56 to the barcode field.
57 * The novelist entry in `eg_vhost.conf` includes two new
58 parameters.
59 * Corrects an issue with the `--max-sleep` argument on the
60 `action_trigger_runner.pl` support script.
61 * Corrects an issue with how the `eg_pbx_allocator.pl` script
62 detects an existing lock file.
63 * The order of the Z39.50 servers on the Z39.50 import screen
64 no longer relies on capitalization.
65 * The 3.0.2-3.0.3 upgrade script disables triggers before
66 recalculating bib visibility.
67 * Fixes an issue where multiple copies with different values for required
68 statistical categories could not be edited and saved in batch.
69
70 Acknowledgements
71 ~~~~~~~~~~~~~~~~
72 We would like to thank the following individuals who contributed code,
73 tests and documentation patches to the 3.1.2 point release of
74 Evergreen:
75
76 * Jason Boyer
77 * Galen Charlton
78 * Jeff Davis
79 * Bill Erickson
80 * Lynn Floyd
81 * Rogan Hamby
82 * Sam Link
83 * Jeanette Lundgren
84 * Kathy Lussier
85 * Katie G. Martin
86 * Terran McCanna
87 * Dan Pearl
88 * Mike Rylander
89 * Jane Sandberg
90 * Chris Sharp
91 * Ben Shum
92 * Remington Steed
93 * Jason Stephenson
94 * Josh Stompro
95 * Cesar Velez
96 * Dan Wells
97 * Bob Wicksall
98
99
100
101 Evergreen 3.1.1
102 ---------------
103 This release contains bug fixes improving on Evergreen 3.1.0.
104
105 * Fixes a performance issue with the Patron Billing History screen and
106 other screens that cause Flattener.pm to re-create joins
107 unnecessarily.
108 * Fixes an issue that prevented patron alerts from showing to staff at
109 other libraries.
110 * Corrects the "Holdable" attribute display on the Item Status detailed
111 view.
112 * Fixes the ability to delete multiple copies from Item Status.
113
114 Acknowledgements
115 ~~~~~~~~~~~~~~~~
116 We would like to thank the following individuals who contributed code,
117 tests and documentation patches to the 3.1.1 point release of
118 Evergreen:
119
120 * Jason Boyer
121 * Bill Erickson
122 * Morkor Quarshie
123 * Jane Sandberg
124 * Remington Steed
125 * Jason Stephenson
126 * Kevin Tran
127 * Dan Wells
128
129
130 3.1.0 Upgrade Notes
131 -------------------
132 Like many major Evergreen upgrades, 3.1 requires a full reingest of your
133 bibliographic records before the system is usable again.  While a basic reingest
134 is included at the end of the upgrade script, it happens after the main
135 COMMIT, so it is safe to cancel that and run the required reingest as you see
136 fit (e.g. via pingest.pl).
137
138
139 3.1.0 New Features
140 ------------------
141
142 Administration
143 ~~~~~~~~~~~~~~
144
145 New Latency Tester Tool
146 ^^^^^^^^^^^^^^^^^^^^^^^
147 The Evergreen Web Staff Client now includes a section called *Tests* linked from
148 *Administration -> Workstation*. The *Tests* page houses a simple tool
149 that can be used to test the latency of the websocket connection between the
150 client and the server (via the `opensrf.echo` service).
151
152 This page displays which Evergreen host server is being queried. Upon hitting
153 the blue "Start Test" button for the first time, it will issue 10 sequentially
154 fired requests in order to get a solid initial average. Clicking the button a
155 second time will take one more measurement and recalculate the average
156 latency. The results can be copied to clipboard for troubleshooting purposes
157 and also cleared from display.
158
159 marc_export --uris option
160 ^^^^^^^^^^^^^^^^^^^^^^^^^
161 The marc_export support script now has a `--uris` option (short form:
162 `-u`) to export records with located URIs (i.e. electronic resources).  When
163 used by itself, it will export only records that have located URIs.  When
164 used in conjunction with `--items`, it will add records with located URIs
165 but no items/copies to the output.  If combined with a `--library` or
166 `--descendants` option, this option will limit its output to those
167 records with URIs at the designated libraries.  The best way to use
168 this option is in combination with the `--items` and one of the
169 `--library` or `--descendants` options to export *all* of a library's
170 holdings both physical and electronic.
171
172
173 Architecture
174 ~~~~~~~~~~~~
175
176 Sample Data Includes Surveys
177 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
178 The Concerto sample data set now includes patron surveys, questions,
179 answers, and responses.
180
181 Virtual Index Definitions
182 ^^^^^^^^^^^^^^^^^^^^^^^^^
183 The practical purpose of Virtual Index Definitions is to supply an Evergreen
184 administrator with the ability to control the weighting and field inclusion of
185 values in the general keyword index, commonly referred to as "the blob,"
186 without requiring tricky configuration that has subtle semantics, an
187 over-abundance of index definitions which can slow search generally, or the
188 need to reingest all records on a regular basis as experiments are performed
189 and the configuration refined. Significant results of recasting keyword indexes
190 as a set of one or more Virtual Index Definitions will be simpler search
191 configuration management, faster search speed overall, and more practical
192 reconfiguration and adjustment as needed.
193
194 Previously, in order to provide field-specific weighting to
195 keyword matches against titles or authors, an administrator must duplicate many
196 other index definitions and supply overriding weights to those duplicates. This
197 not only complicates configuration, but slows down record ingest as well as
198 search. It is also fairly ineffective at achieving the goal of weighted keyword
199 fields. Virtual Index Definitions will substantially alleviate the need for
200 these workarounds and their consequences.
201
202   * A Virtual Index Definition does not require any configuration for
203 extracting bibliographic data from records, but instead can become a sink for
204 data collected by other index definitions, which is then colocated together to
205 supply a search target made up of the separately extracted data. Virtual Index
206 Definitions are effectively treated as aggregate definitions, matching across
207 all values extracted from constituent non-virtual index definitions.  They can
208 further make use of the Combined class functionality to colocate all values in a
209 class together for matching even across virtual fields.
210
211   * Configuration allows for weighting of constituent index definitions that
212 participate in a Virtual Index Definition. This weighting is separate from the
213 weighting supplied when the index definition itself is a search target.
214
215   * The Evergreen QueryParser driver returns the list of fields actually
216 searched using every user-supplied term set, including constituent expansion
217 when a Virtual Index Definition is searched. In particular, this will facilitate
218 Search Term Highlighting described below.
219
220   * Stock configuration changes make use of pre-existing, non-virtual index
221 definitions mapped to new a Virtual Index Definition that implements the
222 functionality provided by the `keyword|keyword` index definition. The
223 `keyword|keyword` definition is left in place for the time being, until more data
224 can be gathered about the real-world effect of removing it entirely and
225 replacing it with Virtual Index Definition mappings.
226
227   * New system administration functions will be created to facilitate
228 modification of Virtual Index Definition mapping, avoiding the need for a full
229 reingest when existing index definitions are added or removed from a virtual
230 field.
231
232 Increased use of Metabib Display Fields
233 +++++++++++++++++++++++++++++++++++++++
234 We use Metabib Display Fields (newly available in 3.0) to render catalog search
235 results, intermediate metarecord results, and record detail pages. This requires
236 the addition of several new Metabib Display Field definitions, as well as Perl
237 services to gather and render the data.
238
239 We also use more Metabib Display Fields in the client. As a result,
240 bibliographic fields will display in proper case in more client interfaces and
241 in Evergreen reports.
242
243 Interfaces
244 ++++++++++
245 A new AngularJS "MARC Search/Facet Fields" interface has been created to replace
246 the Dojo version, and both have been extended to support Virtual Index
247 Definition data supplier mapping and weighting.
248
249 Settings & Permissions
250 ++++++++++++++++++++++
251 The new Virtual Index Definition data supplier mapping table,
252 `config.metabib_field_virtual_map`, requires the same permissions as the
253 MARC Search/Facet Fields interface: CREATE_METABIB_FIELD, UPDATE_METABIB_FIELD,
254 DELETE_METABIB_FIELD, or ADMIN_METABIB_FIELD for all actions
255
256 Backend
257 +++++++
258 There now exist several new database tables and functions primarily in support
259 of search highlighting. Additionally, the QueryParser driver for Evergreen has
260 been augmented to be able to return a data structure describing how the search
261 was performed, in a way that allows a separate support API to gather a
262 highlighted version of the Display Field data for a given record.
263
264 Default Weights
265 +++++++++++++++
266 By default, the following fields will be weighted more heavily in keyword
267 searches. Administrators can change these defaults by changing the values in the
268  "All searchable fields" virtual index in the "MARC Search/Facet Fields"
269 interface.
270
271   * Title proper
272   * Main title (a new index limited to the words in the 245a)
273   * Personal author
274   * All subjects
275
276 In addition, note indexes and the physical description index will receive
277 less weight in default keyword searches.
278
279 Re-ingest or Indexing Dependencies
280 ++++++++++++++++++++++++++++++++++
281 With the addition and modification of many Index Definitions, a full reingest is
282 recommended.  However, search will continue to work as it did previously
283 for those records that have not yet been reingested. Therefore a slow, rolling
284 reingest is recommended.
285
286 Performance Implications or Concerns
287 ++++++++++++++++++++++++++++++++++++
288 Because the Metabib Display Fields infrastructure will eventually replace
289 functionality that is significantly more CPU-intensive in the various forms of
290 XML parsing, XSLT transformation, XPath calculation, and
291 Metabib Virtual Record construction, it is expected that the overall CPU load
292 will be reduced by this development, and ideally the overall time required to
293 perform and render a search will likewise drop. It is unlikely that the speed
294 increase will be visible to users on a per-search basis, but that search in
295 aggregate will become a smaller consumer of resources.
296
297
298 Cataloging
299 ~~~~~~~~~~
300
301 Track Record Merges
302 ^^^^^^^^^^^^^^^^^^^
303 When 2 or more bib records are merged, all records involved are stamped
304 with a new `merge_date` value.  For any bib record, this field indicates
305 the last time it was involved in a merge.  At the same time, all
306 subordinate records (i.e. those deleted as a product of the merge) are
307 stamped with a `merged_to` value indicating which bib record the source
308 record was merged with.
309
310 In the browser client bib record display, a warning alert now appears
311 along the top of the page (below the Deleted alert) indicating when a
312 record was used in a merge, when it was merged, and which record it was
313 merge with, rendered as a link to the target record.
314
315
316 Circulation
317 ~~~~~~~~~~~
318
319 Alternate Patron Hold Pickup
320 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
321 This feature adds a bit of convenience to a common task: checking out
322 an item on hold to another patron (typically a family member or helper).
323
324 When you checkout the item, you will get a pop-up window with warnings associated
325 with this item.  The "ITEM_ON_HOLDS_SHELF" message is now expanded to
326
327  * Let you know the name of the person who had placed the hold.
328  * Give you the option (in the form of a checkbox) of cancelling the
329    hold placed by the above-named patron.  (Checked = Cancel the hold;
330    Unchecked = Leave the hold in place)
331
332 The initial value of the checkbox is derived from the
333 `circ.clear_hold_on_checkout` organizational setting.
334
335 If the operator has CANCEL_HOLD privilege, then if the checkbox is checked and
336 the checkout is allowed to proceed, the hold will be cancelled with a note that
337 the item was checked out to another patron.
338
339 This feature is available in the browser-based staff client.
340
341 New Patron Billing Statement
342 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
343 The Evergreen web staff client now includes a patron billing statement,
344 which summarizes a patron's bills, credits and payments in a familiar
345 layout.  This can be found on the "Statement" tab of the Patron Bill
346 Details page. (From the Patron Bills page, double-click a row to view
347 its details, or choose "Full Details" from the Actions menu.)
348
349 Enhanced Billing Timestamp Support
350 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
351 Previously, billings had to make do with a single timestamp attempting
352 to fill two different roles.  In the case of an overdue fine, the
353 timestamp represented the *end* of the fine period for that billing,
354 while for all other fines, the timestamp was merely the time the bill
355 was created.  This setup generally worked, but not without confusion,
356 and limited our ability to understand and process the data.
357
358 Billings will now have up to three timestamps: a create date, and when
359 applicable, a fine period start and a fine period end.  This clarifies
360 and simplifies things like backdating, retrospective fine generation,
361 account balancing for negative balance avoidance, and billing timeline
362 views.
363
364 Copy Alerts and Suppression Matrix
365 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
366 The Copy Alerts feature allows library staff to add customized alert
367 messages to copies. The copy alerts will appear when a specific event
368 takes place, such as when the copy is checked in, checked out, or
369 renewed. Alerts can be temporary or persistent: temporary alerts will be
370 disabled after the initial alert and acknowledgement from staff, while
371 persistent alerts will display each time the alert event takes place.
372 Copy Alerts can be configured to display at the circulating or owning
373 library only or, alternatively, when the library at which the alert
374 event takes place is not the circulating or owning library.  Copy Alerts
375 can also be configured to provide options for the next copy status that
376 should be applied to an item.  Library administrators will have the
377 ability to create and customize Copy Alert Types and to suppress copy
378 alerts at specific org units.
379
380 Copy alerts can be added via the volume/creator and the check in,
381 check out, and renew pages.  Copy alerts can also be managed at the
382 item status page.
383
384 Copy alert types can be managed via the Copy Alert Types page in
385 Local Administration, and suppression of them can be administered
386 via the Copy Alert Suppression page under Local Administration.
387
388 Place Multiple Holds At Once
389 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
390 Users with the appropriate permissions now have the ability to place multiple
391 title/metarecords holds at once. This feature is especially beneficial for book
392 clubs and reading groups, which need to place holds on multiple copies of a
393 title.
394
395 In order to use the feature:
396
397   * Set the _Maximum number of duplicate holds allowed_ Library Setting
398     (`circ.holds.max_duplicate_holds`) to a number higher than 1
399   * Log in as a user with the CREATE_DUPLICATE_HOLDS
400
401 When placing a title or metarecord hold, a _Number of copies_ field will
402 display for these users. This field is not available when placing part, volume
403 or copy holds.
404
405 This feature does not change the way in which the system fills holds. The
406 multiple holds will fill in the same way that they would if the user had placed
407 multiple holds separately.
408
409 New Notice Columns in Items Out Grid
410 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
411 The grid in the patron "items out" page in the Evergreen web staff client has two new
412 columns indicating the number of notifications generated for a given loan and the date of
413 the most recent notification. These columns will allow circulation staff to better respond to
414 patron questions about whether they were sent notification about an overdue item.
415
416 The columns are based on the number of completed Action Trigger events on the
417 loan that have a 'checkout.due' hook. In other words, they would include overdue
418 and courtesy notices.
419
420 A new library setting, "Exclude Courtesy Notices from Patrons Itemsout Notices Count",
421 if set will cause the notice count and date fields to exclude courtesy notices.
422
423 Patron Email Addresses Now Clickable In Web Staff Client
424 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
425 Adds a mailto link to the patron's email in their profile so it can
426 be clicked to send and email to the patron. No new settings or
427 permissions are included in this feature.
428
429 Pickup Library for Staff-placed Holds
430 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
431 Adds a new library setting, _circ.staff_placed_holds_fallback_to_ws_ou_,
432 that helps determine the hold pickup library in cases where patrons don't
433 have a preferred hold pickup library in their account and a staff member
434 is placing the hold on their behalf.
435
436   * When this setting is true and the patron doesn't have a preferred
437   library listed, the hold pickup library will default to the
438   workstation's organizational unit.
439   * When this setting is false and the patron doesn't have a preferred
440   library listed, the hold pickup library will default to the
441   patron's home library.
442
443 Public Catalog
444 ~~~~~~~~~~~~~~
445
446 Search Term Highlighting
447 ^^^^^^^^^^^^^^^^^^^^^^^^
448 Evergreen now highlights search terms on the public catalog's main search
449 results page, the record detail page, and intermediate pages such as metarecord
450 grouped results page. Highlighting search terms will help the user determine why
451 a particular record (or set of records) was retrieved.
452
453 Highlighting of matched terms uses the same stemming used to accomplish the
454 search, as configured per field and class.
455
456 This feature will help the user more quickly determine the relevance of a
457 particular record by calling their attention to search terms in context. Lastly,
458 it will help familiarize the user with how records are searched, including which
459 fields are searched as well as exposing concepts like stemming.
460
461 You can turn off search term highlighting by uncommenting the line
462 `search.no_highlight = 1;` in `config.tt2`.
463
464 When highlighting is generally enabled, it may be turned on or off on a per-page
465 basis through the use of a UI component which will request the page again
466 without highlighting.
467
468 Highlighting of terms uses Template::Toolkit-driven CSS. A generic CSS class
469 identifying a highlighted term, along with CSS classes identifying the search
470 class and each search field are available for use for customization of the
471 highlighting. A stock CSS template is provided as a baseline upon which sites
472 may expand.
473
474
475 Copy Location Filter Displays for System Searches
476 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
477 The Shelving Location filter now displays on the advanced search page when
478 a search is scoped to a library system, not just to an individual branch. If
479 a library system is selected as the Search Library, the shelving location
480 limiter will display any shelving location that is owned by the selected system
481 or by the consortium. It will NOT display shelving locations owned by child
482 branches.
483
484 Multi-source Attributes
485 ^^^^^^^^^^^^^^^^^^^^^^^
486 We now allow record attribute definitions to extract data using more than
487 one strategy (XPath, tag+subfield, fixed field, etc.) as long as the values
488 from various sources would, after normalization, have the same shape.
489
490 Multilingual Search
491 +++++++++++++++++++
492 This change allows us to configure multilingual search, by extracting values
493 from both the 008 controlfield and the 041 datafield.  Because the values
494 in each can be normalized to the same controlled list (and, in practice, are
495 already from the same normalized value set), catalog searches can now use normal
496 boolean search semantics to find records with various combinations of
497 language attributes.
498
499 E.g., in the concerto test data:
500
501   * `keyword: piano item_lang(eng) item_lang(ita)`
502
503
504 Optional Display of Badges in Catalog
505 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
506 A new setting controls whether badges (popularity, etc.) are displayed
507 in the catalog. If you do not wish badges to be displayed, set the
508 `ctx.hide_badge_scores` setting to "true" in `config.tt2`.
509
510
511 Miscellaneous
512 ~~~~~~~~~~~~~
513
514 Fixes to patron name/username search indexes
515 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
516 When using pg_restore to restore an Evergreen database, some of the
517 indexes used to speed up patron searches on names and usernames
518 could be lost.
519
520 This release fixes the underlying issue and re-creates the indexes
521 in question.
522
523 Details
524 +++++++
525 When using pg_restore to restore an affected database, the
526 "unaccent" indexes on actor.usr would not be created due to an
527 unqualified function reference in `evergreen.unaccent_and_squash`.
528
529 The function will be replaced to resolve the search path issue,
530 and the following indexes on actor.usr will be dropped and then
531 re-created:
532
533   * actor_usr_first_given_name_unaccent_idx;
534   * actor_usr_second_given_name_unaccent_idx;
535   * actor_usr_family_name_unaccent_idx;
536   * actor_usr_usrname_unaccent_idx;
537
538 This will be done even if the indexes are already present, and may
539 take a few minutes on a database with many patrons.
540
541
542 3.1.0 Acknowledgments
543 ---------------------
544 The Evergreen project would like to acknowledge the following
545 organizations that commissioned developments in this release of
546 Evergreen:
547
548 * Albany Public Library (Oregon)
549 * Consortium of Ohio Libraries
550 * CW MARS
551 * Indiana State Library
552 * Georgia Public Library Service
553 * Hagerstown - Jefferson Township Library
554 * Linn-Benton Community College
555 * MassLNC
556 * Pennsylvania Integrated Library System
557 * Sage Library System
558 * Union County Public Library (Indiana)
559
560 We would also like to thank the following individuals who contributed
561 code, translations, documentations patches and tests to this release of
562 Evergreen:
563
564 * Eva Cerninakova
565 * Andi Chandler
566 * Galen Charlton
567 * Jeff Davis
568 * Bill Erickson
569 * Jeff Godin
570 * Rogan Hamby
571 * Angela Kilsdonk
572 * Sam Link
573 * Jeanette Lundgren
574 * Kathy Lussier
575 * Fares Othman
576 * Dan Pearl
577 * Mike Rylander
578 * Jane Sandberg
579 * Chris Sharp
580 * Ben Shum
581 * Remington Steed
582 * Jason Stephenson
583 * Kevin Tran
584 * Cesar Velez
585 * Dan Wells
586
587
588 We also thank the following organizations whose employees contributed
589 patches:
590
591 * Bibliomation
592 * British Columbia Libraries Cooperative
593 * Calvin College
594 * CW MARS
595 * Equinox Open Library Initiative
596 * Georgia Public Library Service
597 * Greater Clarks Hill Regional Library System
598 * Jordanian Library and Information Association
599 * King County Library System
600 * Knihovna Jabok
601 * Linn-Benton Community College
602 * MassLNC
603 * Sigio
604 * Traverse Area District Library
605
606 We regret any omissions.  If a contributor has been inadvertently
607 missed, please open a bug at http://bugs.launchpad.net/evergreen/
608 with a correction.