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