Docs: correction to 3.7 release notes
[Evergreen.git] / docs / RELEASE_NOTES_3_7.adoc
1 Evergreen 3.7-beta Release Notes
2 ================================
3 :toc:
4 :numbered:
5
6 Upgrade notes
7 -------------
8
9 Database Upgrade Procedure
10 ~~~~~~~~~~~~~~~~~~~~~~~~~~
11 The database schema upgrade for Evergreen 3.7 has more steps than normal. The general
12 procedure, assuming Evergreen 3.6.2 as the starting point, is:
13
14 . Run the main 3.6.2 => to 3.7 schema update script from the Evergreen source directory,
15 supplying database connection parameters as needed:
16 +
17 [source,sh]
18 ----
19 psql -f Open-ILS/src/sql/Pg/version-upgrade/3.6.2-3.7-beta-upgrade-db.sql 2>&1 | tee 3.6.2-3.7-beta-upgrade-db.log
20 ----
21 [start=2]
22 . Create and ingest search suggestions:
23 .. Run the following from `psql` to export the strings to files:
24 +
25 [source,sql]
26 ----
27 \a
28 \t
29
30 \o title
31 select value from metabib.title_field_entry;
32 \o author
33 select value from metabib.author_field_entry;
34 \o subject
35 select value from metabib.subject_field_entry;
36 \o series
37 select value from metabib.series_field_entry;
38 \o identifier 
39 select value from metabib.identifier_field_entry;
40 \o keyword
41 select value from metabib.keyword_field_entry;
42
43 \o
44 \a
45 \t
46 ----
47 [start=2]
48 .. From the command line, convert the exported words into SQL scripts to load into the database.
49 This step assumes that you are at the top of the Evergreen source tree.
50 +
51 [source,sh]
52 ----
53 $ ./Open-ILS/src/support-scripts/symspell-sideload.pl title > title.sql
54 $ ./Open-ILS/src/support-scripts/symspell-sideload.pl author > author.sql
55 $ ./Open-ILS/src/support-scripts/symspell-sideload.pl subject > subject.sql
56 $ ./Open-ILS/src/support-scripts/symspell-sideload.pl series > series.sql
57 $ ,/Open-ILS/src/support-scripts/symspell-sideload.pl identifier > identifier.sql
58 $ ./Open-ILS/src/support-scripts/symspell-sideload.pl keyword > keyword.sql
59 ----
60 [start=3]
61 .. Back in `psql`, import the suggestions. This step can take several hours in a large databases,
62 but the `\i $FILE.sql`` steps can be run in parallel.
63 +
64 [source,sql]
65 ----
66 ALTER TABLE search.symspell_dictionary SET UNLOGGED;
67 TRUNCATE search.symspell_dictionary;
68
69 \i identifier.sql
70 \i author.sql
71 \i title.sql
72 \i subject.sql
73 \i series.sql
74 \i keyword.sql
75
76 CLUSTER search.symspell_dictionary USING symspell_dictionary_pkey;
77 REINDEX TABLE search.symspell_dictionary;
78 ALTER TABLE search.symspell_dictionary SET LOGGED;
79 VACUUM ANALYZE search.symspell_dictionary;
80
81 DROP TABLE search.symspell_dictionary_partial_title;
82 DROP TABLE search.symspell_dictionary_partial_author;
83 DROP TABLE search.symspell_dictionary_partial_subject;
84 DROP TABLE search.symspell_dictionary_partial_series;
85 DROP TABLE search.symspell_dictionary_partial_identifier;
86 DROP TABLE search.symspell_dictionary_partial_keyword;
87 ----
88 [start=3]
89 . (optional) Apply the new opt-in setting for overdue and preduce notices.
90 The following query will set the circ.default_overdue_notices_enabled
91 user setting to true (the default value) for all existing users,
92 ensuring they continue to receive overdue/predue emails.
93 +
94 [source,sql]
95 ----
96 INSERT INTO actor.usr_setting (usr, name, value)
97 SELECT
98 id,
99 circ.default_overdue_notices_enabled,
100 true
101 FROM actor.usr;
102 ----
103 +
104 The following query will add the circ.default_overdue_notices_enabled
105 user setting as an opt-in setting for all action triggers that send
106 emails based on a circ being due (unless another opt-in setting is
107 already in use).
108 +
109 [source,sql]
110 ----
111 UPDATE action_trigger.event_definition
112 SET opt_in_setting = circ.default_overdue_notices_enabled,
113 usr_field = usr
114 WHERE opt_in_setting IS NULL
115 AND hook = checkout.due
116 AND reactor = SendEmail;
117 ----
118 Evergreen admins who wish to use the new setting should run both of
119 the above queries. Admins who do not wish to use it, or who are
120 already using a custom opt-in setting of their own, do not need to
121 do anything.
122 [start=4]
123 . Perform a `VACUUM ANALYZE` of the following tables using `psql`:
124 +
125 [source,sql]
126 ----
127 VACUUM ANALYZE authority.full_rec;
128 VACUUM ANALYZE authority.simple_heading;
129 VACUUM ANALYZE metabib.identifier_field_entry;
130 VACUUM ANALYZE metabib.combined_identifier_field_entry;
131 VACUUM ANALYZE metabib.title_field_entry;
132 VACUUM ANALYZE metabib.combined_title_field_entry;
133 VACUUM ANALYZE metabib.author_field_entry;
134 VACUUM ANALYZE metabib.combined_author_field_entry;
135 VACUUM ANALYZE metabib.subject_field_entry;
136 VACUUM ANALYZE metabib.combined_subject_field_entry;
137 VACUUM ANALYZE metabib.keyword_field_entry;
138 VACUUM ANALYZE metabib.combined_keyword_field_entry;
139 VACUUM ANALYZE metabib.series_field_entry;
140 VACUUM ANALYZE metabib.combined_series_field_entry;
141 VACUUM ANALYZE metabib.real_full_rec;
142 ----
143
144 New Seed Data
145 ~~~~~~~~~~~~~
146
147 New Permissions
148 ^^^^^^^^^^^^^^^
149
150 * Administer geographic location services (`ADMIN_GEOLOCATION_SERVICES`)
151 * Administer library groups (`ADMIN_LIBRARY_GROUPS`)
152 * Manage batch (subscription) hold events (`MANAGE_HOLD_GROUPS`)
153 * Modify patron SSO settings (`SSO_ADMIN`)
154 * View geographic location services (`VIEW_GEOLOCATION_SERVICES`)
155
156 New Global Flags
157 ^^^^^^^^^^^^^^^^
158
159 * Block the ability of expired user with the STAFF_LOGIN permission to log into Evergreen (`auth.block_expired_staff_login`)
160 * Offer use of geographic location services in the public catalog (`opac.use_geolocation`)
161
162 New Internal Flags
163 ^^^^^^^^^^^^^^^^^^
164
165 * Maximum search result count at which spelling suggestions may be offered (`opac.did_you_mean.low_result_threshold`)
166
167 New Library Settings
168 ^^^^^^^^^^^^^^^^^^^^
169
170 * Allow both Shibboleth and native OPAC authentication (`opac.login.shib_sso.allow_native`)
171 * Allow renewal request if renewal recipient privileges have expired (`circ.renew.expired_patron_allow`)
172 * Enable Holdings Sort by Geographic Proximity ('opac.holdings_sort_by_geographic_proximity`)
173 * Enable Shibboleth SSO for the OPAC (`opac.login.shib_sso.enable`)
174 * Evergreen SSO matchpoint (`opac.login.shib_sso.evergreen_matchpoint`)
175 * Geographic Location Service to use for Addresses (`opac.geographic_location_service_for_address`)
176 * Keyboard distance score weighting in OPAC spelling suggestions (`search.symspell.keyboard_distance.weight`)
177 * Log out of the Shibboleth IdP (`opac.login.shib_sso.logout`)
178 * Minimum required uses of a spelling suggestions that may be offered (`search.symspell.min_suggestion_use_threshold`)
179 * Pg_trgm score weighting in OPAC spelling suggestions (`search.symspell.pg_trgm.weight`)
180 * Randomize group hold order (`holds.subscription.randomize`)
181 * Shibboleth SSO Entity ID (`opac.login.shib_sso.entityId`)
182 * Shibboleth SSO matchpoint (`opac.login.shib_sso.shib_matchpoint`)
183 * Show Geographic Proximity in Miles (`opac.geographic_proximity_in_miles`)
184 * Soundex score weighting in OPAC spelling suggestions (`search.symspell.soundex.weight`)
185
186 New Stock Action/Trigger Event Definitions
187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
188
189 * Hold Group Hold Placed for Patron Email Notification
190
191 New Features
192 ------------
193
194
195
196 Administration
197 ~~~~~~~~~~~~~~
198
199
200
201 Single Sign On (Shibboleth) Public Catalog integration
202 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203
204 The Evergreen OPAC can now be used as a Service Provider (SP) in a
205 Single Sign On infrastructure.  This allows system administrators to
206 connect the Evergreen OPAC to an identity provider (IdP).  Such a scenario
207 offers significant usability improvements to patrons:
208
209 * They can use the same, IdP-provided login screen and credentials that they
210 use for other applications (SPs).
211 * If they have already logged into another participating application, when
212 they arrive at the Evergreen OPAC, they can be logged in without needing to
213 enter any credentials at all.
214 * Evergreen can be configured to offer a Single Sign-out service, where
215 logging out of the Evergreen OPAC will also log the user out of all other SPs.
216
217 It can also offer security benefits, if it enables a Shibboleth-enabled
218 Evergreen installation to move away from insecure autogenerated user passwords
219 (e.g. year of birth or last four digits of a phone number).
220
221 Different Org Units can use different IdPs.  This development also supports a
222 mix of Shibboleth and non-Shibboleth libraries.
223
224 Note that only the OPAC can be integrated with Shibboleth at this time; no such
225 support exists for the staff client, self-check, etc.
226
227 Also note that this development does not include automatic provisioning of
228 accounts.  At this time, matching accounts must already exist in Evergreen
229 for a patron to successfully authenticate into the OPAC via Single Sign On.
230
231 Installation
232 ++++++++++++
233
234 Installing and configuring Shibboleth support is a complex project.  In
235 broad strokes, the process includes:
236
237 . Installing Shibboleth and the Shibboleth Apache module (`apt install libapache2-mod-shib2` on Debian and Ubuntu)
238 . Configuring Shibboleth, including:
239   * Setting up a certificate
240   * assigning an Entity ID
241   * getting metadata about the IdP from the IdP (perhaps "locally maintained
242   metadata", where an XML file from the IdP is copied into place on your
243   Evergreen server)
244   * Understanding what attributes the IdP will provide about your users,
245   and describing them in the `attribute-map.xml` file.
246 . Providing your Entity ID, information about possible bindings, and any
247 other requested information to the IdP administrator.  Much of this information
248 will be available at http://YOUR_EVERGREEN_DOMAIN/Shibboleth.sso/Metadata
249 . Configuring Apache, including:
250   * Enabling Shibboleth authentication in the `eg_vhost.conf` file
251   * (Optional) Using the new _sso_loc_ Apache variable to identify
252   which org unit should be used as the context location when fetching
253   Shibboleth-related library settings.
254 . As a user with the new `SSO_ADMIN` permission, configure Evergreen using
255 the Library Settings Editor, including:
256   * Enable Shibboleth SSO for the OPAC
257   * (Optional) Configure whether you will use SSO exclusively, or offer
258   patrons a choice between SSO and standard Evergreen authentication
259   * (Optional) Configure whether or not you will use Single Log Out
260   * (Optional) In scenarios where a single Evergreen installation is
261   connected to multiple IdPs, assign org units to the relevant IdPs,
262   referenced by the IdP's Entity Id.
263   * Of the attributes defined in `attribute-map.xml`, configure which one
264   should be used to match users in the Evergreen database.  This defaults
265   to uid.
266   * For the attribute you chose in the previous step, configure which
267   Evergreen field it should match against.  Options are usrname (default),
268   barcode, and email.
269
270 This https://www.youtube.com/watch?v=SvppXbpv-5k[video on the SAML protocol] can
271 be very helpful for introducing the basic concepts used in the installation and
272 configuration processes.
273
274
275
276
277 Architecture
278 ~~~~~~~~~~~~
279
280
281
282 Block Login of Expired Staff Accounts
283 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
284 Evergreen now has the ability to prevent staff users whose
285 accounts have expired from logging in. This is controlled
286 by the new global flag "auth.block_expired_staff_login", which
287 is not enabled by default. If that flag is turned on, accounts
288 that have the `STAFF_LOGIN` permission and whose expiration date
289 is in the past are prevented from logging into any Evergreen
290 interface, including the staff client, the public catalog, and SIP2.
291
292 It should be noted that ordinary patrons are allowed to log into
293 the public catalog if their circulation privileges have expired. This
294 feature prevents expired staff users from logging into the public catalog
295 (and all other Evergreen interfaces and APIs) outright in order to
296 prevent them from getting into the staff interface anyway by
297 creative use of Evergreen's authentication APIs.
298
299 Evergreen admins are advised to check the expiration status of staff
300 accounts before turning on the global flag, as otherwise it is
301 possible to lock staff users out unexpectedly. The following SQL
302 query will identify expired but otherwise un-deleted users that
303 would be blocked by turning on the flag:
304
305 [source,sql]
306 ----
307 SELECT DISTINCT usrname, expire_date
308 FROM actor.usr au, permission.usr_has_perm_at_all(id, 'STAFF_LOGIN')
309 WHERE active
310 AND NOT deleted
311 AND NOT barred
312 AND expire_date < NOW()
313 ----
314
315 Note that this query can take a long time to run in large databases
316 given the general way that it checks for users that have the
317 `STAFF_LOGIN` permission. Replacing the use of
318 `permission.usr_has_perm_at_all()` with a query on expired users
319 with profiles known to have the `STAFF_LOGIN` permission will
320 be much faster.
321
322
323
324
325 Migration From GIST to GIN Indexes for Full Text Search
326 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
327
328 Evergreen now uses GIN indexes for full text search in PostgreSQL.
329 GIN indexes offer better performance than GIST.  For more information
330 on the differences in the two index types, please refer to the
331 https://www.postgresql.org/docs/current/textsearch-indexes.html[PostgreSQL
332 documentation].
333
334 An upgrade script is provided as part of this migration.  If you
335 upgrade normally from a previous release of Evergreen, this upgrade
336 script should run as part of the upgrade process.  The migration
337 script recommends that you run a `VACUUM ANALYZE` in PostgreSQL on the
338 tables that had the indexes changed.  The migration process does not
339 do this for you, so you should do it as soon as is convenient after
340 the upgrade.
341
342 Updating Your Own Indexes
343 +++++++++++++++++++++++++
344
345 If you have added your own full text indexes of type GIST, and you
346 wish to migrate them to GIN, you may do so.  The following query, when
347 run in your Evergreen databsase after the migration from GIST to GIN,
348 will identify the remaining GIST indexes in your database:
349
350 [source,sql]
351 ----------------------------------------
352 SELECT schemaname, indexname
353 FROM pg_indexes
354 WHERE indexdef ~* 'gist';
355 ----------------------------------------
356
357 If the above query produces output, you can run the next query to
358 output a SQL script to migrate the remaining indexes from GIST to GIN:
359
360 [source,sql]
361 ----------------------------------------
362 SELECT 'DROP INDEX ' || schemaname || '.' || indexname || E';\n' ||
363        REGEXP_REPLACE(indexdef, 'gist', 'gin', 'i') || E';\n' ||
364        'VACUUM ANAlYZE ' || schemaname || '.' || tablename || ';'
365 FROM pg_indexes
366 WHERE indexdef ~* 'gist';
367 ----------------------------------------
368
369
370
371
372 Removal of Custom Dojo Build
373 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
374
375 Evergreen had a
376 https://wiki.evergreen-ils.org/doku.php?id=scratchpad:random_magic_spells#custom_dojo_build[method
377 of making a custom build of the Dojo JavaScript library].  Following
378 this procedure could improve the load times for the OPAC and other
379 interfaces that use Dojo.  However, very few sites took advantage of
380 this process or even knew of its existence.
381
382 As a part of the process, an `openils_dojo.js` file was built and
383 installed along with the other Dojo files.  Evergreen had many
384 references to load this optional file.  For the majority of sites that
385 did not use this custom Dojo process, this file did not exist.
386 Browsers would spend time and resources requesting this nonexistent
387 file.  This situation also contributed noise to the Apache logs with
388 the 404 errors from these requests.
389
390 In keeping with the goal of eliminating Dojo from Evergreen, all
391 references to `openils_dojo.js` have been removed from the OPAC and
392 other files.  The profile script required to make the custom Dojo
393 build has also been removed.
394
395
396
397
398
399 Cataloging
400 ~~~~~~~~~~
401
402
403
404 Czech language records in sample data
405 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
406
407 This release adds 7 Czech-language MARC records to the
408 sample data set (also known as Concerto data set).
409
410
411
412
413
414 Publisher Catalog Display Includes 264 Tag
415 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
416
417 Publisher values are now extracted for display from tags 260 OR 264.
418
419 Upgrade Notes
420 +++++++++++++
421
422 A partial reingest is required to extract the new publisher data for display.
423 This query may be long-running.
424
425 [source,sql]
426 --------------------------------------------------------------------------
427 WITH affected_bibs AS (
428     SELECT DISTINCT(bre.id) AS id
429     FROM biblio.record_entry bre
430     JOIN metabib.real_full_rec mrfr
431     ON (mrfr.record = bre.id AND mrfr.tag = '264')
432     WHERE NOT bre.deleted
433 )
434 SELECT metabib.reingest_metabib_field_entries(id, TRUE, FALSE, TRUE, TRUE)
435 FROM affected_bibs;
436 --------------------------------------------------------------------------
437
438
439
440
441
442 Circulation
443 ~~~~~~~~~~~
444
445
446
447 Hold Groups
448 ^^^^^^^^^^^
449
450 This feature allows staff to add multiple users to a named hold group
451 bucket and place title-level holds for a record for that entire set of users.
452 Users can be added to such a hold group bucket from either the patron
453 search result interface, via the Add to Bucket dropdown, or through a dedicated
454 Hold Group interface available from the Circulation menu.  Adding new
455 patrons to a hold group bucket will require staff have the PLACE_HOLD
456 permission.
457
458 Holds can be placed for the users in a hold group bucket either directly from
459 the normal staff-place hold interface in the embedded OPAC, or by supplying the
460 record ID within the hold group bucket interface.  In the latter case, the
461 list of users for which a hold was attempted but failed to be placed can be
462 downloaded by staff in order to address any placement issues.  Placing a
463 hold group bucket hold will requires staff have the MANAGE_HOLD_GROUPS
464 permission, which is new with this development.
465
466 In the event of a mistaken hold group hold, staff with the MANAGE_HOLD_GROUPS
467 permission will have the ability to cancel all unfulfilled holds created as
468 part of a hold group event.
469
470 A link to the title's hold interface is available from the list of hold group
471 events in the dedicated hold group interface.
472
473
474
475
476
477 Scan Item as Missing Pieces Angular Port
478 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
479 The 'Scan Item As Missing Pieces' interface is now an Angular interface.
480 The functionality is the same, but the interface displays more details
481 on the item in question (title/author/callnum) before proceeding with the 
482 missing pieces process.
483
484
485
486
487 Opt-In Setting for Overdue and Predue Emails
488 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
489 The "Receive Overdue and Courtesy Emails" user setting permits users to
490 control whether they receive email notifications about overdue items.
491
492 To use the setting, modify any action trigger event definitions which
493 send emails about overdue items, setting the "Opt In Setting" to
494 "circ.default_overdue_notices_enabled" and the "User Field" to "usr".
495 You can accomplish this by running the following query in your database:
496
497 ----
498 UPDATE action_trigger.event_definition
499 SET opt_in_setting = 'circ.default_overdue_notices_enabled',
500     usr_field = 'usr'
501 WHERE opt_in_setting IS NULL
502     AND hook = 'checkout.due'
503     AND reactor = 'SendEmail';
504 ----
505
506 Once this is done, the patron registration screen in the staff client
507 will show a "Receive Overdue and Courtesy Emails" checkbox, which will
508 be checked by default.  To ensure that existing patrons continue to
509 recieve email notifications, you will need to add the user setting to
510 their accounts, which you can do by running the following query in your
511 database:
512
513 ----
514 INSERT INTO actor.usr_setting (usr, name, value)
515 SELECT
516     id,
517     'circ.default_overdue_notices_enabled',
518     'true'
519 FROM actor.usr;
520 ----
521
522
523
524
525
526
527 Allow Circulation Renewal for Expired Patrons
528 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
529 The "Allow renewal request if renewal recipient privileges have
530 expired" organizational unit setting can be set to true to permit
531 expired patrons to renew circulations.  Allowing renewals for expired
532 patrons reduces the number of auto-renewal failures and assumes that a
533 patron with items out eligible for renewals has not been expired for
534 very long and that such patrons are likely to renew their privileges
535 in a timely manner.
536
537 The setting is referenced based on the current circulation library for
538 the renewal.  It takes into account the global flags for "Circ: Use
539 original circulation library on desk renewal instead of the
540 workstation library" and "Circ: Use original circulation library on
541 opac renewal instead of user home library."
542
543
544
545
546 OPAC
547 ~~~~
548
549
550
551 Consistent Ordering for Carousels
552 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
553 Carousel ordering is now stable and predictable:
554
555  * Newly Cataloged Item and Newest Items by Shelving Location carousels are ordered from most recently cataloged to least recently cataloged.
556  * Recently Returned Item carousels is ordered is from most recently returned to least recently returned.
557  * Top Circulated Items carousels is ordered is from most circulated to least circulated.
558  * Manual carousels (as of now, without the ability to adjust the position of items) are in the order they are added to the backing bucket.
559   ** Emptying and refilling the bucket allows reordering.
560
561
562
563
564
565 Default Public Catalog to the Bootstrap Skin
566 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
567 The public catalog now defaults to the Bootstrap skin rather than the
568 legacy TPAC skin.
569
570 Bootstrap is now the default in order to encourage more testing, but
571 users should be aware of the following 
572 https://bugs.launchpad.net/evergreen/+bugs?field.tag=bootstrap-blocker[issues];
573 certain specific functionality is available only in the TPAC skin.
574
575 The TPAC skin remains available for use, but current Evergreen users
576 should start actively considering migrating to the Bootstrap skin.
577
578 In order to continue to use the TPAC skin, comment out the following
579 line in `eg_vhost.conf`
580
581 [source,conf]
582 -------------------
583 PerlAddVar OILSWebTemplatePath "@localstatedir@/templates-bootstrap" # Comment this line out to use the legacy TPAC
584 -------------------
585
586
587
588
589 Did You Mean? Single word search suggestions
590 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
591 This feature is the first in the series to add native search suggestions
592 to the Evergreen search logic.  A significant portion of the code is
593 dedicated to infrastructure that will be used in later enhancements to
594 the functionality.
595
596 Overview
597 ++++++++
598 When searching the public or staff catalog in a single search class (title,
599 author, subject, series, identifier, or keyword) with a single search term
600 users can be presented with alternate search terms.  Depending on how the
601 instance has been configured, suggestions may be provided for only
602 misspelled words (as defined by existence in the bibliographic corpus),
603 terms that are spelled properly but occur very few times, or on every
604 single-term search.
605
606 Settings
607 ++++++++
608
609 The following new library settings control the behavior of the suggestions:
610
611 * Maximum search result count at which spelling suggestions may be offered
612 * Minimum required uses of a spelling suggestions that may be offered
613 * Maximum number of spelling suggestions that may be offered
614 * Pg_trgm score weighting in OPAC spelling suggestions
615 * Soundex score weighting in OPAC spelling suggestions
616 * QWERTY Keyboard similarity score weighting in OPAC spelling suggestions 
617
618 There are also two new internal flags:
619
620 * symspell.prefix_length
621 * symspell.max_edit_distance
622
623 Upgrading
624 +++++++++
625 This feature requires the addition of new Perl module dependencies.  Please
626 run the app server and database server dependency Makefiles before applying
627 the database and code updates.
628
629 At the end of the database upgrade script, the administrator is presented
630 with a set of instructions necessary to precompute the suggestion
631 dictionary based on the current bibliographic database.  The first half
632 of this procedure can be started even before the upgrade begins, as soon
633 as the Evergreen database is no longer accessible to users that might
634 cause changes to bibliographic records.  For very large instances, this
635 dictionary generation can take several hours and needs to be run on a
636 server with significant RAM and CPU resources. Please look at the upgrade
637 script before beginning an upgrade and plan this dictionary creation as
638 part of the overall upgrade procedure.
639
640 Given a server, such as a database server with 64G of RAM, you should
641 be able to run all six of the shell commands in parallel in screen
642 sessions or with a tool such as GNU parallel.
643
644 These commands invoke a script that will generate a class-specific sub-set
645 of the dictionary, and can be used to recreate the dictionary if
646 necessary in the future.
647
648
649
650
651
652 Sort Holdings by Geographical Proximity
653 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
654
655 This functionality integrates 3rd party geographic lookup services to allow patrons
656 to enter an address on the record details page in the OPAC and sort the holdings
657 for that record based on proximity of their circulating libraries to the entered
658 address. To support this, latitude and longitude coordinates may be associated with
659 each org unit. Care is given to not log or leak patron provided addresses or the
660 context in which they are used.
661
662 Requires the following Perl modules: `Geo::Coder::Free`, `Geo::Coder::Google`, and `Geo::Coder::OSM`
663
664 Configuration instructions:
665
666  . Register an account with a third party geographic location service and copy the API Key.
667  . Configure the Geographic Location Service (Server Administration > Geographic Location Service > New Geographic Location Service).
668  . Enable Global Flag by navigating to Server Administration → Global Flags and locating the `opac.use_geolocation` flag. (Any entry in the Value field will be ignored.)
669  . Enable Library Setting: Enable Holdings Sort by Geographic Proximity (set to True).
670  . Enable Library Setting: Geographic Location Service to use for Addresses (use the value from the Name field entered in the Geographic Location Services Configuration entry).
671  . Enable Library Setting: Show Geographic Proximity in Miles (if not set, it will default to kilometers).
672  . Set the geographic coordinates for each location by navigating to Server Administration > Organizational Units. Select the org unit, switch to the Physical Address subtab and either manually enter Latitude and Longitude values or use the Get Coordinate button. 
673
674 Two new permissions, VIEW_GEOLOCATION_SERVICES and ADMIN_GEOLOCATION_SERVICES, control viewing and editing values in the Geolocation Location Services interface. They are added to the System Administrator and Global Administrator permissions groups by default.
675
676
677 Library Groups
678 ^^^^^^^^^^^^^^
679 The Library Groups search feature revives a longstanding internal
680 concept in Evergreen called “Lassos,” which allows an administrator
681 to define a group of organizational units for searching outside of
682 the standard organizational unit hierarchy.
683
684 Use case examples include creating a group of law or science
685 libraries within a university consortium, or grouping all school
686 libraries together within a mixed school/public library consortium.
687
688 Searches can be restricted to a particular Library Group from the
689 library selector in the public catalog basic search page and from
690 the new "Where" selector on the advanced search page.
691
692 Restricting catalog searches by Library Group is available only
693 in the public catalog and "traditional" staff catalog; it is not
694 available in the Angular staff catalog.
695
696 This feature adds a new permission, `ADMIN_LIBRARY_GROUPS`, that
697 allows updating Library Groups and Library Group Maps. This permission
698 is not associated with any profiles by default, and replaces
699 the `CREATE_LASSO`, `UPDATE_LASSO`, and `DELETE_LASSO` permissions. 
700
701 To define new library groups, use the Server Administration Library
702 Groups and Library Group Maps pages. An autogen and a reload of
703 Apache should be performed after making changes to Library Groups.
704
705
706 Easier Styling of Public Catalog Logo and Cart Images
707 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
708
709 Evergreen now has IDs associated with logos and cart images in the TPAC and Bootstrap OPACs to aid in customization.  Images are as follows:
710
711 * small Evergreen logo in navigation bar is 'topnav_logo_image'
712 * the large Evergreen logo in the center of the splash page of the TPAC is 'homesearch_main_logo_image' 
713 * the cart icon is 'cart_icon_image' 
714 * the small logo in the footer is 'footer_logo_image'
715
716 The Bootstrap OPAC does not have a homesearch logo icon as it is added in the background by CSS and can be directly styled through the CSS.
717
718
719
720
721
722 Easier TPAC Customization via colors.tt2
723 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
724 Twelve new colors for TPAC have been added to the colors.tt2 file as well as 
725 having corresponding changes to the style.css.tt2 file. These use 
726 descriptive rather than abstract names. These changes help avoid 
727 situations were unreadable values are placed on top of each other 
728 and where different values are wanted for elements that only refernece 
729 a single color previously. Guidelines are below for setting values that 
730 correspond to the previous values used in the colors.tt2 file.  
731 For more diverse customizations the OPAC should be reviewed before 
732 a production load.
733
734 * 'footer' is used for the background color of the footer. It replaces the 
735 'primary'.
736 * 'footer_text' sets the text color in the footer and replaces 'text_invert' 
737 * 'header' sets the background of the header and replaces 'primary_fade'
738 * 'header_text' sets the color of text in the header and replaces 'text_invert'
739 * 'header_links_bar' sets the background of the links bar that separates the 
740 header on the front page of the opac and replaces 'background_invert'
741 * 'header_links_text' sets the text on the links bar and replaces 'text_invert'
742 * 'header_links_text_hover' set the hover text color on the links bar and 
743 replaces 'primary'
744 * 'opac_button' sets the background color of the My Opac button and replaces 
745 'control'
746 * 'opac_button_text' explicitly sets the text color on the My Opac button  
747 * 'opac_button_hover' sets the background color of the My Opac button when the 
748 mouse is hovering over it and replaces 'primary'
749 * 'opac_button_hover_text' sets the text color of the My Opac button when the 
750 mouse is hovering over it and replaces 'text invert'
751
752 Note that is patch is primarily meant for users who wish to continue
753 using TPAC rather than the Bootstrap skin for a while; new Evergreen
754 users are advised to use the now-default Bootstrap skin.
755
756
757
758
759 Configurable Read More Accordion for OPAC Search and Record View (TPAC)
760 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
761
762 Read More Button
763 ++++++++++++++++
764 Public catalog record fields (in the TPAC skin only) now truncate
765 themselves based on a configurable amount of characters.  The full
766 field may be displayed upon hitting a (Read More) link, which will
767 then toggle into a (Read Less) link to re-truncate the field.
768
769 Configuration
770 +++++++++++++
771 `Open-ILS/src/templates/opac/parts/config.tt2` contains two new
772 configuration variables:
773
774
775 * `truncate_contents` (default: 1)
776 * `contents_truncate_length` (default: 50).
777
778 Setting `truncate_contents` to 0 will disable the read more
779 functionality.  The variable `contents_truncate_length` corresponds
780 to the amount of characters to display before truncating the text.
781 If `contents_truncate_length` is removed, it will default to 100.
782
783 Additional configuration for note fields can be made in
784 `Open-ILS/src/templates/opac/parts/record/contents.tt2`, allowing a
785 `trunc_length` variable for each individual type of note, which will
786 override `contents_truncate_length` for that specific
787 type of note.
788
789
790 Adding Read More Functionality to further fields
791 ++++++++++++++++++++++++++++++++++++++++++++++++
792 To add Read More functionality to any additional fields, you may use
793 the macro `accordion()`, defined in `misc_util.tt2`. It can take three
794 variables: `str`, `trunc_length`, and `element`. `str` corresponds to
795 the string you want to apply it to, `trunc_length` (optional) will
796 override `contents_truncate_length` if supplied, and `element`
797 (optional) provides an alternative HTML element to look at for the
798 truncation process (useful in situations such as the Authors and Cast
799 fields, where each field is processed individually, but needs to be
800 treated as a single field).
801
802
803
804
805 Reports
806 ~~~~~~~
807
808
809
810 Reports Scheduler Improvements
811 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
812 Previously, the reports scheduler allowed duplicated reports
813 under certain circumstances.  A uniqueness constraint now
814 disallows this without adversely affecting the reports process.
815
816
817
818 Miscellaneous
819 -------------
820
821
822 * The 'Create Reservation' form in the Booking module now includes
823   an option to search for the patron by attributes other than just
824   their barcode. (https://bugs.launchpad.net/evergreen/+bug/1816655[Bug 1816655])
825 * The form to add a user to a Course now includes an option to search
826   for the patron by attributes other than just their barcode. (https://bugs.launchpad.net/evergreen/+bug/1907921[Bug 1907921])
827 * For consistency with the menu action Cataloging => Retrieve Record by
828   TCN Value, the staff catalog Numeric Search => TCN search now includes
829   deleted bib records. (https://bugs.launchpad.net/evergreen/+bug/1881650[Bug 1881650])
830 * Add a new command-line script, `overdrive-api-checker.pl`, for testing
831   the OverDrive API. (https://bugs.launchpad.net/evergreen/+bug/1696825[Bug 1696825])
832 * The Shelving Location Groups editor is ported to Angular. (https://bugs.launchpad.net/evergreen/+bug/1852321[Bug 1852321])
833 * The staff catalog now has the ability to add all search results (up to
834   1,000 titles) to the basket in one fell swoop. (https://bugs.launchpad.net/evergreen/+bug/1885179[Bug 1885179])
835 * Add 'All Videos' as a search format. (https://bugs.launchpad.net/evergreen/+bug/1917826[Bug 1917826])
836 * Server-side print templates can now have print contexts set. (https://bugs.launchpad.net/evergreen/+bug/1891550[Bug 1891550])
837 * Add ability to set the print context for a print template to "No-Print"
838   to specify, well, that a given receipt should never be printed. (https://bugs.launchpad.net/evergreen/+bug/1891550[Bug 1891550])
839 * Add Check Number as an available column to the Bill History grids. (https://bugs.launchpad.net/evergreen/+bug/1705693[Bug 1705693])
840 * Adds a new control to the item table in the TPAC public catalog only to
841   specify that only items that are available should be displayed. (https://bugs.launchpad.net/evergreen/+bug/1853006[Bug 1853006])
842 * Adds warning before deleting bib records with holds (https://bugs.launchpad.net/evergreen/+bug/1398107[Bug 1398107])
843 * Library scope on (Angular) Administration pages now defaults to workstation location rather than consortium (https://bugs.launchpad.net/evergreen/+bug/1873322[Bug 173322])
844 * Pending users now set last four digits of phone number as password when library setting is enabled (https://bugs.launchpad.net/evergreen/+bug/1887852[Bug 1887852])
845
846 Acknowledgments
847 ---------------
848 The Evergreen project would like to acknowledge the following
849 organizations that commissioned developments in this release of
850 Evergreen:
851
852 * BC Libraries Cooperative
853 * Community Library (Sunbury)
854 * Consortium of Ohio Libraries (COOL)
855 * Evergreen Community Development Initiative
856 * Evergreen Indiana
857 * Georgia PINES
858 * Linn-Benton Community College
859 * Pennsylvania Integrated Library System (PaILS)
860
861
862 We would also like to thank the following individuals who contributed
863 code, translations, documentation, patches, and tests to this release of
864 Evergreen:
865
866 * John Amundson
867 * Zavier Banks
868 * Felicia Beaudry
869 * Jason Boyer
870 * Dan Briem
871 * Andrea Buntz Neiman
872 * Christine Burns
873 * Galen Charlton
874 * Garry Collum
875 * Eva Cerniňáková
876 * Dawn Dale
877 * Elizabeth Davis
878 * Jeff Davis
879 * Martha Driscoll
880 * Bill Erickson
881 * Jason Etheridge
882 * Ruth Frasur
883 * Blake Graham-Henderson
884 * Katie Greenleaf Martin
885 * Rogan Hamby
886 * Elaine Hardy
887 * Kyle Huckins
888 * Angela Kilsdonk
889 * Tiffany Little
890 * Mary Llewellyn
891 * Terran McCanna
892 * Chauncey Montgomery
893 * Gina Monti
894 * Michele Morgan
895 * Carmen Oleskevich
896 * Jennifer Pringle
897 * Mike Risher
898 * Mike Rylander
899 * Jane Sandberg
900 * Chris Sharp
901 * Ben Shum
902 * Remington Steed
903 * Jason Stephenson
904 * Jennifer Weston
905 * Beth Willis
906
907 We also thank the following organizations whose employees contributed
908 patches:
909
910 * BC Libraries Cooperative
911 * Calvin College
912 * Catalyte
913 * CW MARS
914 * Equinox Open Library Initiative
915 * Georgia Public Library Service
916 * Kenton County Public Library
917 * King County Library System
918 * Linn-Benton Community College
919 * MOBIUS
920 * NOBLE
921 * Westchester Library System
922
923 We regret any omissions.  If a contributor has been inadvertently
924 missed, please open a bug at http://bugs.launchpad.net/evergreen/
925 with a correction.
926