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