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