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