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