LP1607922: Receiving items on page 2 of search results
[working/Evergreen.git] / docs / RELEASE_NOTES_2_6.adoc
1 Evergreen 2.6 Release Notes
2 ===========================
3 :toc:
4 :numbered:
5
6 Upgrade notes
7 -------------
8
9 OPAC
10 ~~~~
11
12 TPAC library pages
13 ^^^^^^^^^^^^^^^^^^
14 Evergreen 2.5 introduced the `Library information URL` library setting to
15 associate a web page with a library. If set, this value was used as the target
16 of the library link in the copy table on the record details page. However, the
17 new default behavior is to link to the automatically generated TPAC library
18 page, which in turn links to the external web site.
19
20 If you wish to maintain the previous behavior, you can set the `Use external
21 library information URL` library setting to `True`.
22
23
24 Disable Autosuggest by Default
25 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
26 As described in https://bugs.launchpad.net/evergreen/+bug/1187993, the 
27 community is aware of ongoing accessibility issues caused through use of 
28 the autosuggest feature of the Evergreen catalog. The decision has been 
29 made to disable autosuggest by default for new installations. Existing sites
30 are cautioned to take note of this change and decide for themselves whether
31 to discontinue use.
32
33 It is possible to disable the autosuggest feature via a global flag. Look in
34 `Admin -> Server Administration -> Global Flags`, find the `OPAC: Show
35 auto-completing suggestions dialog...` setting, then edit and uncheck the
36 `Enabled` box.
37
38
39
40 Miscellaneous
41 ~~~~~~~~~~~~~
42
43 Removal of open-ils.ingest service
44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
45 The open-ils.ingest service is no longer required, and has been
46 removed.
47
48 You should update your opensrf.xml file to remove references to
49 open-ils.ingest, and you may also wish to remove the
50 OpenILS/Application/Ingest.pm file from your Perl @INC path.
51
52 In opensrf.xml, remove the entire <open-ils.ingest> element from the
53 <apps> element, and remove <appname>open-ils.ingest</appname> from
54 any <activeapps> elements where it is present.
55
56 If you have the perldoc command installed, you can use the following
57 command to locate the path on disk of the Ingest.pm file, which is
58 no longer required and can be removed:
59
60 [source, bash]
61 -----------------------------------------------------------------
62 perldoc -l OpenILS::Application::Ingest
63 -----------------------------------------------------------------
64
65
66 Reporter view 'classic_current_circ' dropped
67 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
68 As part of the DB upgrade, the reporter view
69 "reporter.classic_current_circ" was dropped.  If you previously
70 installed this view from example.reporter-extension.sql, it will
71 have to be re-installed by executing the "CREATE OR REPLACE
72 VIEW reporter.classic_current_circ AS..." SQL once again from
73 example.reporter-extension.sql.
74
75
76
77 New Features
78 ------------
79
80 Administration
81 ~~~~~~~~~~~~~~
82
83 Add granular settings for requiring staff initials for notes
84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85 There are now three separate library settings for controlling whether staff 
86 are required to input their initials when creating different types of notes.
87 See new library settings below.
88
89 Any pre-existing library setting for requiring staff initials are preserved 
90 during the upgrade process. After upgrading, you may choose to change the set
91 behavior for any of the three new settings.
92
93 New Library Settings
94 +++++++++++++++++++++
95  * Require staff initials for entry/edit of patron standing penalties and messages. (ui.staff.require_initials.patron_standing_penalty)
96  * Require staff initials for entry/edit of patron notes. (ui.staff.require_initials.patron_info_notes)
97  * Require staff initials for entry/edit of copy notes. (ui.staff.require_initials.copy_notes)
98
99
100 Cataloging
101 ~~~~~~~~~~
102
103 Enhancements to Evergreen's MARC Editor Concerning Fixed Fields
104 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
105 This work is a combination of two features. One provides suggested
106 values in a right-click context menus for fixed field values based on
107 the 'type' of the record being edited. The other provides a wizard to
108 help specifically with the Physical Characteristics of the record, i.e.
109 the 007 field.
110
111 Right-Click Context Menus
112 +++++++++++++++++++++++++
113 Users will be able to right-click on the value control for fixed fields
114 in the MARC Editor, and Evergreen will provide a menu from which the
115 user can select a possible value. This will work for fixed fields where
116 Evergreen already contains information from the Library of Congress's
117 MARC 21 standard.
118
119 Example:
120
121 image::media/ffer-right-click.png["Right-clicking the BLvl field"]
122
123 Evergreen already comes loaded with information from the Library of
124 Congress's MARC 21 standard on possible values for some fixed fields.
125
126 The following table shows which fixed fields for which 'Record Types'
127 have values already loaded into Evergreen.
128
129 ---------------------------------------------------------
130
131  Fixed Field |          Record Types
132 -------------+-----------------------------------
133  Audn        | {BKS,COM,REC,SCO,SER,VIS}
134  BLvl        | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
135  Form        | {BKS,MAP,MIX,REC,SCO,SER,VIS}
136  Lang        | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
137  LitF        | {BKS}
138  Type        | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
139
140
141 ---------------------------------------------------------
142
143 A 'Record Type' is itself a combination of the 'Type of Record' (fixed
144 field name: Type) and 'Bibliographic Level' (fixed field name: BLvl)
145 elements of the MARC leader (positions 06 and 07 respectively). You can
146 see a record's Record Type in the MARC Editor as shown in
147 this screenshot:
148
149 'Record Type':
150
151 image::media/ffer-record-type.png["This Record Type is REC"]
152
153 A user may add values to these fixed fields as well as to other fixed
154 fields through the MARC Coded Value Maps interface found under the Admin
155 -> Server Administration menu in the staff client. These are grouped by
156 Record Attribute Types (a superset of fixed fields) which have labels
157 such as 'Alph', 'Biog', 'Videorecording format', and 'Language'.
158
159 From LOC Fixed Fields documentation, 'Alph' is 'Original alphabet or
160 script of title', 'Biog' is 'Biography', 'Videorecording format' is from
161 the 007 field, 'Language' is positions 35-37 of the 008, and so on.
162 Other Record Attribute Types such as 'Author' are, of course, not fixed
163 fields at all.
164
165 When users add new values here, the right-click context menus of the
166 fixed fields in the MARC Editor will include those values.
167
168 All values added for any fixed field in the Coded Value Map will display
169 for any 'Record Type' that uses that fixed field.
170
171 Users of the MARC Editor always retain the option of leaving a fixed
172 field blank, entering the special values # or |, or entering a value not
173 provided by the right-click context menu.
174
175 Physical Characteristics Wizard
176 +++++++++++++++++++++++++++++++
177 By right-clicking on an existing or new 007 field in the MARC Editor, users
178 will be able to enter a wizard that leads them step-by-step through the
179 positions in that 007 field, telling them the significance of the current
180 position and providing a drop-down list of possible values.
181
182 Launching the Physical Characteristics Wizard:
183
184 image::media/ffer-open-wizard.png["Launching the Physical Characteristics Wizard"]
185
186 Choosing the Category of Material:
187
188 image::media/ffer-007-00.png["Choosing the Category of Material"]
189
190 Choosing a value for a later position:
191
192 image::media/ffer-007-smd.png["Choosing a value for a later position"]
193
194
195 marc_export script replacement
196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
197 The `/openils/bin/marc_export` script is completely rewritten.  This
198 new version accepts all of the same command line options as the old
199 version as well as some new options.
200
201 The rewritten `marc_export` talks directly to your Evergreen database
202 and is a great deal faster than the previous version.  Because the new
203 script talks directly to the database, it needs to know how to
204 connect.  To facilitate this, a new option, `--store`, was added that
205 allows the user to specify one of three Evergreen storage backends to
206 use when exporting records.  The valid choices are `reporter`,
207 `cstore`, or `storage`.  The default of `reporter` should work in most
208 cases, but if you do have a separate reporter database and you know
209 you want to talk directly to your main production database, then you
210 will probably want to choose either `cstore` or `storage`.
211
212 In addition to the `--store` option, a `--since` option is also added
213 so that you can specify output of an update file of records changed,
214 added, and/or deleted since the given date.  The `--since` option uses
215 a fairly flexible date parser and can accept a wide range of date
216 formats including ISO 8601, man common date formats such as M/D/Y
217 (common in the US) or D/Mon/Y (with the first 3 characters or more of
218 the month spelled out), as well as several less common date formats.
219 Special date strings such as `yesterday`, `today`, `yesterday week`,
220 and `today week` are also supported.  For more information see the
221 VALID DATE FORMATS section of the `Date::Manip::Date` man page.
222 Available online here:
223
224 http://search.cpan.org/~sbeck/Date-Manip-6.42/lib/Date/Manip/Date.pod#VALID_DATE_FORMATS
225
226 There is one final difference between the new script and the old
227 `marc_export`.  The new script does not output progress as it
228 executes.  Many of the statistics that the script reported are not
229 readily available to the new script.  It was deemed better to just not
230 output any progress rather than to output something different from the
231 old program.  If your scripts parse the output from `marc_export`,
232 they will need to modified not to expect any.
233
234
235 Circulation
236 ~~~~~~~~~~~
237
238 Lost Item Billing: New Min/Max Price Settings
239 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
240 When an item is marked lost, the user is typically billed for the item.
241 In Evergreen, they can either be charged the amount recorded in the item
242 object, or if that value is blank (or zero), charged a default price
243 (controlled by settings).
244
245 In addition to these existing settings, now we can accommodate a range of
246 prices by saying the patron should be billed at least 'X' and not more
247 than 'Y'. This also allows you to effectively set a fixed price for all
248 lost items by setting min and max to the same amount.
249
250 New Org Unit Settings
251 +++++++++++++++++++++
252  * Minimum Item Price: circ.min_item_price
253  * Maximum Item Price: circ.max_item_price
254
255 New Permissions
256 +++++++++++++++
257  * UPDATE_ORG_UNIT_SETTING.circ.min_item_price
258  * UPDATE_ORG_UNIT_SETTING.circ.max_item_price
259
260
261 User Editor: "Update Expire Date" button
262 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
263 A new button labeled "Update Expire Date" is added in the user
264 editor next to expire date field. This button can be used to
265 re-calculate the user's expire date based on the current profile's
266 permission interval and today's date.
267
268 This is similar to how the expire date is populated when creating a
269 new user, or when changing the profile group.
270
271 This button simplifies the process of "renewing" a user, by
272 eliminating the requirement that staff manually enter a new expire
273 date.
274
275 A button is used here so that the updating of the expire date
276 remains an  intentional process, not one that happens upon any edit.
277
278
279 OPAC
280 ~~~~
281
282 Composite Record Attributes
283 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
284 With this feature we create an abstraction on top of the Record Attribute
285 infrastructure to allow the aggregation of multiple, cross-Attribute values
286 under a single search filter value, accessible through new, dynamic filters.
287
288 Each QueryParser filter will be created by the addition of a Composite Record
289 Attribute Definition. For instance, one may wish to create a Composite Record
290 Attribute Definition for an abstract "Item Type" interface component that
291 uses information from the item_type, vr_format, bib_level and item_form
292 Record Attribute Definitions, with each Composite Record Attribute Value
293 having a different combination of Record Attribute Values from some or all of
294 these Record Attribute Definitions. In this way, as single interface
295 component might be presented as a dropdown with options such as "All Books",
296 "All video recordings", "DVDs", "VHS Tapes", "E-Books", "Audio Books" and
297 "Large Print Books". Of particular note are the "DVDs" and "VHS Tapes"
298 entries, which include information from Record Attribute Definitions
299 completely separate from the others. Additionally, the Composite Record
300 Attribute Values defined by this Composite Record Attribute Definition
301 can be used to drive behavioral logic, such as alternate icon display or
302 link generation, in upgrade-friendly template adjustments.
303
304 Included in this development is a replacement for the single-attribute
305 Format filter supplied for basic search.  Instead, a Composite Attribute
306 is used to combine the values from Item Type, Item Form and Videorecording
307 Format in various ways that provide a more patron-friendly set of choices.
308
309 This new Format filter can be adjusted, or even replaced with a completely
310 local one, through configuration and without template adjustment.
311
312
313
314 Located URI visibility options
315 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
316 Before this, Evergreen restricted the visibility of bibliographic records
317 that make use of Located URIs in a way that attempts to model licensing
318 restrictions.
319
320 There now exists a global flag to allow sites the option of changing the
321 behaviour of Located URIs so that they act in a way analogous to copies
322 for visibility testing.  When the opac.located_uri.act_as_copy global flag
323 is enabled, Located URIs will cause their containing bib records to become
324 visible in searches where the URI is in scope to either ancestors of the
325 search library, as before, or descendants of the search library, as copies
326 do.  As before, if a preferred library is supplied by the user, it is
327 added to the list of visible org units to check.
328
329 Additionally, while the underlying UnAPI and supporting code was capable
330 of providing a reasonable and logical sort order for the Located URIs when
331 embedded as XML holdings elements, the client-facing UnAPI method was not
332 making use of that.  It now does, and uses the same sorting algorithm as
333 is used for copies.
334
335
336 Multi-valued Record Attributes and Controlled Record Attributes
337 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
338 Having identified common use cases and reasonable restrictions that can be
339 placed on the feature set, we have extended the Record Attribute
340 infrastructure to support both the extraction and storage of all instances
341 of a defined Attribute found within a bibliographic record, as well as
342 provide new and more powerful indexing of existing data, in several ways.
343
344 Record Attributes can now be defined by configuration as either single-valued
345 or multi-valued. For any Attribute configured as single-valued, only the
346 first value extracted from a record will be stored. This configuration
347 parameter and restriction is in place to support potential query
348 optimizations based on foreknowledge of whether a given Attribute is multi-
349 valued or not.
350
351 Record Attributes will be defined by configuration as either controlled or
352 uncontrolled. A controlled Record Attribute is one that has entries in the
353 Coded Value Map infrastructure specifying the valid values the record may
354 carry for this attribute. If defined as a controlled Attribute, any unknown
355 values extracted from a record will be ignored. Uncontrolled Attributes,
356 however, may contain any value. This configuration parameter and restriction
357 also supports potential query optimization.
358
359 We store uncontrolled attribute values in a new table with a monotonically
360 decreasing ID sequence, separating it from controlled values, reducing storage
361 requirements by retaining only unique values, and making lookup faster.
362
363 Restrictions
364 ++++++++++++
365  * A Record Attribute's values must match Coded Value Map entries if it is to be a Controlled Attribute. Coded Value Map control is indicated by a new "controlled" boolean on the config.record_attr_definition table.
366  * Record Attributes must "opt in" to multi-valued-ness. Record Attributes will opt in via a new "multi" boolean on config.record_attr_definition; this restriction enforces site config requirements by being explicit about the definition of "multi" fields.
367  * If controlled but not opt'd in to multi-mode, only the first value will be recorded but the new search mechanism will be used.
368  * Only single-valued Record Attributes will be available for use by the system as Sort Axes.
369  * Only controlled Record Attributes will be available for use by the TPAC as dynamically generated filter UI components, such as filter dropdowns or multi-selects.
370
371 New External Dependency
372 +++++++++++++++++++++++
373 This new feature requires the addition of the intarray extension to Postgres.
374 This is a stock extension available on most linux distributions via the same
375 package as the already-required plperl extension.
376
377
378 Restore OpenSearch Support
379 ^^^^^^^^^^^^^^^^^^^^^^^^^^
380 Restore previously held functionality from JSPAC to support OpenSearch in TPAC. 
381 This allows users to easily add the Evergreen search engine to their browser's 
382 built-in set of search engines.
383
384
385 Accepting payments with Stripe
386 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
387 Stripe is a payment processing service that lets
388 sites take credit card payments without payment card information ever
389 touching the sites' own servers.
390
391 NOTE: Using Stripe as a payment processor means that clients *must*
392 have Javascript enabled in order to submit fine payments through your
393 OPAC.
394
395 Library Settings
396 ++++++++++++++++
397 The following settings need to be set at the appropriate org level for
398 sites wanting to use Stripe.
399
400  * "Allow Credit Card Payments" (should be 'true')
401
402    credit.payments.allow
403
404  * "Enable Stripe payments" (should be 'true')
405
406    credit.processor.stripe.enabled
407
408  * "Stripe publishable key" (value provided by Stripe)
409
410    credit.processor.stripe.pubkey
411
412  * "Stripe secret key" (value provided by Stripe)
413
414    credit.processor.stripe.secretkey
415
416  * "Name default credit processor" (should be 'Stripe')
417
418    credit.processor.default
419
420
421 TPAC library pages
422 ^^^^^^^^^^^^^^^^^^
423 This feature adds one web page per library in the system to the TPAC at
424 `http://hostname/eg/opac/library/<SHORTNAME>` and
425 `http://hostname/eg/opac/library/<ID>`. The pages publish the following
426 information from Evergreen (if available):
427
428 * Name of the library
429 * Link to the library web site (from `Library Information URL` library setting)
430 * Opening hours
431 * Email address
432 * Phone number
433 * Mailing address
434 * Link to parent library (if applicable)
435
436 Library pages are linked from the copy table on the record details page.
437
438 Structured data
439 +++++++++++++++
440 The library web pages publish schema.org structured data, which can enable
441 search engines and other systems to better understand your libraries and their
442 resources.
443
444
445 TPAC Metarecord Search and Holds
446 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
447 This feature adds support for searching and placing holds against 
448 metarecords.
449
450 Metarecord Searching
451 ++++++++++++++++++++
452 In the top search bar and in the advanced search page, there is a new
453 search modifier labeled "Group Formats and Editions".  When selected,
454 searches are performed against metarecords and metarecords are shown
455 in the results list.
456
457 For each metarecord, format icons for all constituent records are shown.
458 When a use clicks on a metarecord, if the metarecord has multiple
459 constituent records, the user is taken to the constituent records
460 list.  Similarly, when a metarecord only has one constituent record,
461 the user is directed to the record detail page for the constituent
462 record.
463
464 Metarecord Holds
465 ++++++++++++++++
466 Clicking the place hold link from the metarecord results page shows
467 the available formats and languages for the metarecord, allowing
468 the user to limit the scope of the hold.  Non-metarecord holds now
469 get a new "Advanced Holds Options" link which allows user to promote
470 a title hold to a metarecord hold, thus providing access 
471 to the formats / editions selector, before the hold is placed.
472
473 In the My Account holds list, icons for all selected formats are 
474 displayed in the Format columns for the hold.  When editing a 
475 metarecord hold, users may modify the desired formats and languages.
476
477 Configuration
478 +++++++++++++
479 Admins may disable this feature by un-commenting the "metarecord.disabled"
480 attribute in config.tt2
481
482
483 Web Content Accessibility Guidelines (WCAG) Compliance
484 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
485 To make the catalog more accessible to users with a range of disabilities,
486 including blindness and low vision, the catalog has been revised to better
487 comply with the Web Content Accessibility Guidelines (WCAG) 2.0. These
488 revisions target level "AA" of compliance.
489
490 For more information on WCAG, see http://www.w3.org/WAI/intro/wcag
491
492
493 Bug Fixes
494 ---------
495
496 IMPORTANT SECURITY INFORMATION
497 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498 A serious security flaw that allows unauthorized remote access to
499 organizational unit settings is fixed in the following releases of
500 Evergreen: 2.5.9, 2.6.7, and 2.7.4.  All prior releases of Evergreen
501 are vulnerable to exploitation of this flaw to reveal sensitive system
502 information.  If you are running a vulnerable release of Evergreen you
503 are *strongly* encouraged to upgrade to a non-vulnerable release as
504 soon as possible.
505
506 Set resource limits for Clark Kent
507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
508 Several parameters are now available for the reporter daemon process
509 (`clark-kent.pl`) to control resource usage.  These can be used to
510 reduce the chances that a malformed report can cause indigestion
511 on a database or reports server.  The new parameters, which can be
512 set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
513
514 * `//reporter/setup/statement_timeout` / `--statement-timeout`
515
516 Number of minutes to allow a report's underlying SQL query
517 to run before it gets cancelled.  Default value is
518 60 minutes.  If a report's query gets cancelled, the
519 error_text value will be set to a valid that indicates that
520 the allowed time was exceeded.
521
522 * `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
523
524 Number of rows permitted in the query's output before
525 Clark Kent refuses to attempt to draw a graph. Default
526 value is 1,000 rows.
527
528 * `//reporter/setup/resultset_limit` / `--resultset-limit`
529
530 If set, truncates the report's output to the specified
531 number of hits.  Note that it will not be apparent
532 to a staff user if the report's output has been
533 truncated.  Default value is unlimited.
534
535 The report concurrency (i.e., the number of reports that Clark
536 Kent will run in parallel) can now also be controlled via
537 the `opensrf.xml` setting `//reporter/setup/parallel`.
538
539 Acknowledgments
540 ---------------
541 The Evergreen project would like to acknowledge the following
542 organizations who commissioned developments in this release of
543 Evergreen:
544
545  * Butler Public Library, IN, USA
546  * British Columbia Libraries Cooperative
547  * Carnegie Public Library of Steuben County, IN, USA
548  * Centerville-Center Township Public Library, IN, USA
549  * Flora Public Library, IN, USA
550  * Hagerstown - Jefferson Township Library, IN, USA
551  * Howe Library, Hanover, NH, USA
552  * Massachusetts Library Network Cooperative
553  * Newton County Public Library, IN, USA
554  * Noble County Public Library, IN, USA
555  * Natural Resources Canada
556  * North of Boston Library Exchange
557  * Perry County Public Library, IN, USA
558  * Plainfield-Guilford Township Public Library, IN, USA
559  * Rodgers Memorial Library, Hudson, NH, USA
560  * Statistics Canada
561  * Union County Public Library, IN, USA
562  * Westfield Washington Public Library, IN, USA
563
564 We would also like to thank the following individuals who contributed
565 code and documentations patches to this release of Evergreen:
566
567  * Jason Boyer
568  * Galen Charlton
569  * Mark Cooper
570  * Bill Erickson
571  * Jason Etheridge
572  * Lebbeous Fogle-Weekley
573  * Jeff Godin
574  * Pasi Kallinen
575  * Mike Rylander
576  * Dan Scott
577  * Chris Sharp
578  * Ben Shum
579  * Remington Steed
580  * Jason Stephenson
581  * Yamil Suarez
582  * Elliot Voris
583  * Dan Wells
584
585 We also thank the following organizations whose employees contributed
586 patches:
587
588  * Berklee College of Music
589  * Bibliomation
590  * Calvin College
591  * Equinox Software, Inc.
592  * Georgia Public Library Service
593  * Indiana State Library
594  * Laurentian University
595  * Merrimack Valley Library Consortium
596  * Pohjois-Karjalan Tietotekniikkakeskus Oy
597  * Saint Louis Christian College
598  * Traverse Area District Library
599
600 We regret any omissions.  If a contributor has been inadvertently
601 missed, please open a bug at http://bugs.launchpad.net/evergreen/
602 with a correction.
603