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