Docs: 3.7.1 release notes

[Evergreen.git] / docs / RELEASE_NOTES_3_7.adoc

= Evergreen 3.7 Release Notes =
:toc:
:numbered:


== Evergreen  3.7.1 ==

This release contains bug fixes improving on Evergreen 3.7.0.


=== Bug Fixes ===

==== Acquisitions ====

* Acq PO Search cancel reason column shows description (https://bugs.launchpad.net/bugs/1906825[Bug 1906825])
* Date columns in Acq Search now also show time (https://bugs.launchpad.net/bugs/1912097[Bug 1912097])

==== Administration ====

* Fixes an issue with editing carousels (https://bugs.launchpad.net/bugs/1879769[Bug 1879769])
* Carousel admin grid now has a link to edit the relevant bucket (https://bugs.launchpad.net/bugs/1901893[Bug 1901893])
* The Active Column in SMS Carrier administration now displays properly (https://bugs.launchpad.net/bugs/1873539[Bug 1873539])
* Fixes upgrade script for Enhanced Print/Email (https://bugs.launchpad.net/bugs/1905091[Bug 1905091])
* Cleans up numerous Perl warnings in logs (https://bugs.launchpad.net/bugs/1895660[Bug 1895660])


==== Catalog ====

* Fixes an issue displaying highlighting in traditional and bootstrap catalogue (https://bugs.launchpad.net/bugs/1923225[Bug 1923225])
* Fixes an issue displaying works with the word "hidden" in the title (https://bugs.launchpad.net/bugs/1930933[Bug 1930933])
* Bootstrap OPAC: Simple Selector for Lang now works in Advanced Search (https://bugs.launchpad.net/bugs/1920042[Bug 1920042])
* Bootstrap OPAC: My account summary now displays ebook references according to config file (https://bugs.launchpad.net/bugs/1910288[Bug 1910288])
* Bootstrap OPAC: Item tags no longer display as separate copies on an x-small screen (https://bugs.launchpad.net/bugs/1916936[Bug 1916936])
* Fixes nesting issues on the Bootstrap OPAC Record Detail Page (https://bugs.launchpad.net/bugs/1901710[Bug 1901710])
* Opac SMS and Carrier Fields display according to OU Setting when Editing a Hold (https://bugs.launchpad.net/bugs/1902302[Bug 1902302])
* Better controls for collapsing and expanding the staff catalog search form (https://bugs.launchpad.net/bugs/1913338[Bug 1913338])

==== Cataloging ====

* Angular Catalog: "Edit" link no longer ignores UPDATE_COPY perm (https://bugs.launchpad.net/bugs/1920815[Bug 1920815])
* Angular catalog: fixes an issue with metarecord search (https://bugs.launchpad.net/bugs/1930088[Bug 1930088])
* Angular staff catalog now displays e-resource links (https://bugs.launchpad.net/bugs/1881607[Bug 1881607])
* Record bucket Batch Edit now navigates to the Angular batch editor (https://bugs.launchpad.net/bugs/1926310[Bug 1926310])
* Angular Catalog: Shelving locations assigned to the top level OU now display in list (https://bugs.launchpad.net/bugs/1927527[Bug 1927527])
* Add to Carousel added back to the Other Actions menu in the Bib Record (https://bugs.launchpad.net/bugs/1922120[Bug 1922120])
* Makes terminology more consistent in Angular Catalog (https://bugs.launchpad.net/bugs/1925725[Bug 1925725])


==== Circulation ====

* Preferred Name is now the prominent display name (https://bugs.launchpad.net/bugs/1924185[Bug 1924185])
* Unchanged workstation settings are no longer re-applied on every checkin (https://bugs.launchpad.net/bugs/1918362[Bug 1918362])
* Adds accessible field labels in patron search and edit (https://bugs.launchpad.net/bugs/1615800[Bug 1615800])
* Fixes an issue with the embedded "Place a hold" catalog in the checkout interface (https://bugs.launchpad.net/bugs/1887876[Bug 1887876])
* Angular Catalog: Hold status in View Holds is now saved (https://bugs.launchpad.net/bugs/1917495[Bug 1917495])
* Angular Staff Catalog: Hold Pickup Library no longer sometimes empty (https://bugs.launchpad.net/bugs/1917944[Bug 1917944])
* Fixes an issue with the Angular catalog view holds sort by patron barcode (https://bugs.launchpad.net/bugs/1928684[Bug 1928684])
* Staff catalog hold detail page now supports hold notes/notifications (https://bugs.launchpad.net/bugs/1910145[Bug 1910145])

==== Client ====

* Angular grid column field picker has a better sort order (https://bugs.launchpad.net/bugs/1891699[Bug 1891699])
* Angular grids now support shift-click multi-row selection (https://bugs.launchpad.net/bugs/1911238[Bug 1911238])
* Fixes an issue with multi-word queries in the splash page catalog search (https://bugs.launchpad.net/bugs/1892435[Bug 1892435])

==== Database ====

* Evergreen now uses the builtin array_remove() function rather than its own custom version (https://bugs.launchpad.net/bugs/1778955[Bug 1778955])
* Adds seed data for the eg.orgselect.hopeless.wide_holds setting (https://bugs.launchpad.net/bugs/1895738[Bug 1895738])


==== Documentation ====

* Adds documentation on how to contribute Documentation (https://bugs.launchpad.net/bugs/1927534[Bug 1927534])
* Adds IDL acronym to the glossary (https://bugs.launchpad.net/bugs/1857917[Bug 1857917])
* Adds documentation on how to use the browser client efficiently (https://bugs.launchpad.net/bugs/1250528[Bug 1250528] and https://bugs.launchpad.net/bugs/1751146[Bug 1751146])
* Improves example for LDAP authentication (https://bugs.launchpad.net/bugs/1901940[Bug 1901940])
* Adds documentation about patron with negative balances (https://bugs.launchpad.net/bugs/1929467[Bug 1929467])

=== Acknowledgements ===

We would like to thank the following individuals who contributed code,
testing and documentation patches to the 3.7.1 point release of Evergreen:


* Jason Boyer
* Dan Briem
* Galen Charlton
* Garry Collum
* Jeff Davis
* Bill Erickson
* Jason Etheridge
* Lynn Floyd
* Blake Graham Henderson
* Rogan Hamby
* Elaine Hardy
* Kyle Huckins
* Rosie Le Faive
* Tiffany Little
* Mary Llewellyn
* Katie G. Martin
* Terran McCanna
* Gina Monti
* Michele Morgan
* Andrea Buntz Neiman
* Mike Risher
* Mike Rylander
* Jane Sandberg
* Chris Sharp
* Chrisy Schroth
* Jason Stephenson
* Stephen Wills

== Evergreen  3.7.0 ==

=== Upgrade notes ===

==== Database Upgrade Procedure ====

The database schema upgrade for Evergreen 3.7 has more steps than normal. The general
procedure, assuming Evergreen 3.6.2 as the starting point, is:

. Run the main 3.6.2 => to 3.7 schema update script from the Evergreen source directory,
supplying database connection parameters as needed:
+
[source,sh]
----
psql -f Open-ILS/src/sql/Pg/version-upgrade/3.6.2-3.7.0-upgrade-db.sql 2>&1 | tee 3.6.2-3.7.0-upgrade-db.log
----
[start=2]
. Create and ingest search suggestions:
.. Run the following from `psql` to export the strings to files:
+
[source,sql]
----
\a
\t

\o title
select value from metabib.title_field_entry;
\o author
select value from metabib.author_field_entry;
\o subject
select value from metabib.subject_field_entry;
\o series
select value from metabib.series_field_entry;
\o identifier 
select value from metabib.identifier_field_entry;
\o keyword
select value from metabib.keyword_field_entry;

\o
\a
\t
----
[start=2]
.. From the command line, convert the exported words into SQL scripts to load into the database.
This step assumes that you are at the top of the Evergreen source tree.
+
[source,sh]
----
$ ./Open-ILS/src/support-scripts/symspell-sideload.pl title > title.sql
$ ./Open-ILS/src/support-scripts/symspell-sideload.pl author > author.sql
$ ./Open-ILS/src/support-scripts/symspell-sideload.pl subject > subject.sql
$ ./Open-ILS/src/support-scripts/symspell-sideload.pl series > series.sql
$ ,/Open-ILS/src/support-scripts/symspell-sideload.pl identifier > identifier.sql
$ ./Open-ILS/src/support-scripts/symspell-sideload.pl keyword > keyword.sql
----
[start=3]
.. Back in `psql`, import the suggestions. This step can take several hours in a large databases,
but the `\i $FILE.sql`` steps can be run in parallel.
+
[source,sql]
----
ALTER TABLE search.symspell_dictionary SET UNLOGGED;
TRUNCATE search.symspell_dictionary;

\i identifier.sql
\i author.sql
\i title.sql
\i subject.sql
\i series.sql
\i keyword.sql

CLUSTER search.symspell_dictionary USING symspell_dictionary_pkey;
REINDEX TABLE search.symspell_dictionary;
ALTER TABLE search.symspell_dictionary SET LOGGED;
VACUUM ANALYZE search.symspell_dictionary;

DROP TABLE search.symspell_dictionary_partial_title;
DROP TABLE search.symspell_dictionary_partial_author;
DROP TABLE search.symspell_dictionary_partial_subject;
DROP TABLE search.symspell_dictionary_partial_series;
DROP TABLE search.symspell_dictionary_partial_identifier;
DROP TABLE search.symspell_dictionary_partial_keyword;
----
[start=3]
. (optional) Apply the new opt-in setting for overdue and preduce notices.
The following query will set the circ.default_overdue_notices_enabled
user setting to true (the default value) for all existing users,
ensuring they continue to receive overdue/predue emails.
+
[source,sql]
----
INSERT INTO actor.usr_setting (usr, name, value)
SELECT
id,
circ.default_overdue_notices_enabled,
true
FROM actor.usr;
----
+
The following query will add the circ.default_overdue_notices_enabled
user setting as an opt-in setting for all action triggers that send
emails based on a circ being due (unless another opt-in setting is
already in use).
+
[source,sql]
----
UPDATE action_trigger.event_definition
SET opt_in_setting = circ.default_overdue_notices_enabled,
usr_field = usr
WHERE opt_in_setting IS NULL
AND hook = checkout.due
AND reactor = SendEmail;
----
Evergreen admins who wish to use the new setting should run both of
the above queries. Admins who do not wish to use it, or who are
already using a custom opt-in setting of their own, do not need to
do anything.
[start=4]
. Perform a `VACUUM ANALYZE` of the following tables using `psql`:
+
[source,sql]
----
VACUUM ANALYZE authority.full_rec;
VACUUM ANALYZE authority.simple_heading;
VACUUM ANALYZE metabib.identifier_field_entry;
VACUUM ANALYZE metabib.combined_identifier_field_entry;
VACUUM ANALYZE metabib.title_field_entry;
VACUUM ANALYZE metabib.combined_title_field_entry;
VACUUM ANALYZE metabib.author_field_entry;
VACUUM ANALYZE metabib.combined_author_field_entry;
VACUUM ANALYZE metabib.subject_field_entry;
VACUUM ANALYZE metabib.combined_subject_field_entry;
VACUUM ANALYZE metabib.keyword_field_entry;
VACUUM ANALYZE metabib.combined_keyword_field_entry;
VACUUM ANALYZE metabib.series_field_entry;
VACUUM ANALYZE metabib.combined_series_field_entry;
VACUUM ANALYZE metabib.real_full_rec;
----

==== New Seed Data ====


===== New Permissions =====

* Administer geographic location services (`ADMIN_GEOLOCATION_SERVICES`)
* Administer library groups (`ADMIN_LIBRARY_GROUPS`)
* Manage batch (subscription) hold events (`MANAGE_HOLD_GROUPS`)
* Modify patron SSO settings (`SSO_ADMIN`)
* View geographic location services (`VIEW_GEOLOCATION_SERVICES`)

===== New Global Flags =====

* Block the ability of expired user with the STAFF_LOGIN permission to log into Evergreen (`auth.block_expired_staff_login`)
* Offer use of geographic location services in the public catalog (`opac.use_geolocation`)

===== New Internal Flags =====

* Maximum search result count at which spelling suggestions may be offered (`opac.did_you_mean.low_result_threshold`)

===== New Library Settings =====

* Allow both Shibboleth and native OPAC authentication (`opac.login.shib_sso.allow_native`)
* Allow renewal request if renewal recipient privileges have expired (`circ.renew.expired_patron_allow`)
* Enable Holdings Sort by Geographic Proximity ('opac.holdings_sort_by_geographic_proximity`)
* Enable Shibboleth SSO for the OPAC (`opac.login.shib_sso.enable`)
* Evergreen SSO matchpoint (`opac.login.shib_sso.evergreen_matchpoint`)
* Geographic Location Service to use for Addresses (`opac.geographic_location_service_for_address`)
* Keyboard distance score weighting in OPAC spelling suggestions (`search.symspell.keyboard_distance.weight`)
* Log out of the Shibboleth IdP (`opac.login.shib_sso.logout`)
* Minimum required uses of a spelling suggestions that may be offered (`search.symspell.min_suggestion_use_threshold`)
* Pg_trgm score weighting in OPAC spelling suggestions (`search.symspell.pg_trgm.weight`)
* Randomize group hold order (`holds.subscription.randomize`)
* Shibboleth SSO Entity ID (`opac.login.shib_sso.entityId`)
* Shibboleth SSO matchpoint (`opac.login.shib_sso.shib_matchpoint`)
* Show Geographic Proximity in Miles (`opac.geographic_proximity_in_miles`)
* Soundex score weighting in OPAC spelling suggestions (`search.symspell.soundex.weight`)

===== New Stock Action/Trigger Event Definitions =====

* Hold Group Hold Placed for Patron Email Notification

=== New Features ===


==== Administration ====



===== Single Sign On (Shibboleth) Public Catalog integration =====

The Evergreen OPAC can now be used as a Service Provider (SP) in a
Single Sign On infrastructure.  This allows system administrators to
connect the Evergreen OPAC to an identity provider (IdP).  Such a scenario
offers significant usability improvements to patrons:

* They can use the same, IdP-provided login screen and credentials that they
use for other applications (SPs).
* If they have already logged into another participating application, when
they arrive at the Evergreen OPAC, they can be logged in without needing to
enter any credentials at all.
* Evergreen can be configured to offer a Single Sign-out service, where
logging out of the Evergreen OPAC will also log the user out of all other SPs.

It can also offer security benefits, if it enables a Shibboleth-enabled
Evergreen installation to move away from insecure autogenerated user passwords
(e.g. year of birth or last four digits of a phone number).

Different Org Units can use different IdPs.  This development also supports a
mix of Shibboleth and non-Shibboleth libraries.

Note that only the OPAC can be integrated with Shibboleth at this time; no such
support exists for the staff client, self-check, etc.

Also note that this development does not include automatic provisioning of
accounts.  At this time, matching accounts must already exist in Evergreen
for a patron to successfully authenticate into the OPAC via Single Sign On.

====== Installation ======

Installing and configuring Shibboleth support is a complex project.  In
broad strokes, the process includes:

. Installing Shibboleth and the Shibboleth Apache module (`apt install libapache2-mod-shib2` on Debian and Ubuntu)
. Configuring Shibboleth, including:
  * Setting up a certificate
  * assigning an Entity ID
  * getting metadata about the IdP from the IdP (perhaps "locally maintained
  metadata", where an XML file from the IdP is copied into place on your
  Evergreen server)
  * Understanding what attributes the IdP will provide about your users,
  and describing them in the `attribute-map.xml` file.
. Providing your Entity ID, information about possible bindings, and any
other requested information to the IdP administrator.  Much of this information
will be available at http://YOUR_EVERGREEN_DOMAIN/Shibboleth.sso/Metadata
. Configuring Apache, including:
  * Enabling Shibboleth authentication in the `eg_vhost.conf` file
  * (Optional) Using the new _sso_loc_ Apache variable to identify
  which org unit should be used as the context location when fetching
  Shibboleth-related library settings.
. As a user with the new `SSO_ADMIN` permission, configure Evergreen using
the Library Settings Editor, including:
  * Enable Shibboleth SSO for the OPAC
  * (Optional) Configure whether you will use SSO exclusively, or offer
  patrons a choice between SSO and standard Evergreen authentication
  * (Optional) Configure whether or not you will use Single Log Out
  * (Optional) In scenarios where a single Evergreen installation is
  connected to multiple IdPs, assign org units to the relevant IdPs,
  referenced by the IdP's Entity Id.
  * Of the attributes defined in `attribute-map.xml`, configure which one
  should be used to match users in the Evergreen database.  This defaults
  to uid.
  * For the attribute you chose in the previous step, configure which
  Evergreen field it should match against.  Options are usrname (default),
  barcode, and email.

This https://www.youtube.com/watch?v=SvppXbpv-5k[video on the SAML protocol] can
be very helpful for introducing the basic concepts used in the installation and
configuration processes.


==== Architecture ====


===== Block Login of Expired Staff Accounts =====

Evergreen now has the ability to prevent staff users whose
accounts have expired from logging in. This is controlled
by the new global flag "auth.block_expired_staff_login", which
is not enabled by default. If that flag is turned on, accounts
that have the `STAFF_LOGIN` permission and whose expiration date
is in the past are prevented from logging into any Evergreen
interface, including the staff client, the public catalog, and SIP2.

It should be noted that ordinary patrons are allowed to log into
the public catalog if their circulation privileges have expired. This
feature prevents expired staff users from logging into the public catalog
(and all other Evergreen interfaces and APIs) outright in order to
prevent them from getting into the staff interface anyway by
creative use of Evergreen's authentication APIs.

Evergreen admins are advised to check the expiration status of staff
accounts before turning on the global flag, as otherwise it is
possible to lock staff users out unexpectedly. The following SQL
query will identify expired but otherwise un-deleted users that
would be blocked by turning on the flag:

[source,sql]
----
SELECT DISTINCT usrname, expire_date
FROM actor.usr au, permission.usr_has_perm_at_all(id, 'STAFF_LOGIN')
WHERE active
AND NOT deleted
AND NOT barred
AND expire_date < NOW()
----

Note that this query can take a long time to run in large databases
given the general way that it checks for users that have the
`STAFF_LOGIN` permission. Replacing the use of
`permission.usr_has_perm_at_all()` with a query on expired users
with profiles known to have the `STAFF_LOGIN` permission will
be much faster.




===== Migration From GIST to GIN Indexes for Full Text Search =====

Evergreen now uses GIN indexes for full text search in PostgreSQL.
GIN indexes offer better performance than GIST.  For more information
on the differences in the two index types, please refer to the
https://www.postgresql.org/docs/current/textsearch-indexes.html[PostgreSQL
documentation].

An upgrade script is provided as part of this migration.  If you
upgrade normally from a previous release of Evergreen, this upgrade
script should run as part of the upgrade process.  The migration
script recommends that you run a `VACUUM ANALYZE` in PostgreSQL on the
tables that had the indexes changed.  The migration process does not
do this for you, so you should do it as soon as is convenient after
the upgrade.

====== Updating Your Own Indexes ======

If you have added your own full text indexes of type GIST, and you
wish to migrate them to GIN, you may do so.  The following query, when
run in your Evergreen databsase after the migration from GIST to GIN,
will identify the remaining GIST indexes in your database:

[source,sql]
----------------------------------------
SELECT schemaname, indexname
FROM pg_indexes
WHERE indexdef ~* 'gist';
----------------------------------------

If the above query produces output, you can run the next query to
output a SQL script to migrate the remaining indexes from GIST to GIN:

[source,sql]
----------------------------------------
SELECT 'DROP INDEX ' || schemaname || '.' || indexname || E';\n' ||
       REGEXP_REPLACE(indexdef, 'gist', 'gin', 'i') || E';\n' ||
       'VACUUM ANAlYZE ' || schemaname || '.' || tablename || ';'
FROM pg_indexes
WHERE indexdef ~* 'gist';
----------------------------------------




===== Removal of Custom Dojo Build =====

Evergreen had a
https://wiki.evergreen-ils.org/doku.php?id=scratchpad:random_magic_spells#custom_dojo_build[method
of making a custom build of the Dojo JavaScript library].  Following
this procedure could improve the load times for the OPAC and other
interfaces that use Dojo.  However, very few sites took advantage of
this process or even knew of its existence.

As a part of the process, an `openils_dojo.js` file was built and
installed along with the other Dojo files.  Evergreen had many
references to load this optional file.  For the majority of sites that
did not use this custom Dojo process, this file did not exist.
Browsers would spend time and resources requesting this nonexistent
file.  This situation also contributed noise to the Apache logs with
the 404 errors from these requests.

In keeping with the goal of eliminating Dojo from Evergreen, all
references to `openils_dojo.js` have been removed from the OPAC and
other files.  The profile script required to make the custom Dojo
build has also been removed.





====== Cataloging ======



===== Czech language records in sample data =====

This release adds 7 Czech-language MARC records to the
sample data set (also known as Concerto data set).





===== Publisher Catalog Display Includes 264 Tag =====

Publisher values are now extracted for display from tags 260 OR 264.

====== Upgrade Notes ======

A partial reingest is required to extract the new publisher data for display.
This query may be long-running.

[source,sql]
--------------------------------------------------------------------------
WITH affected_bibs AS (
    SELECT DISTINCT(bre.id) AS id
    FROM biblio.record_entry bre
    JOIN metabib.real_full_rec mrfr
    ON (mrfr.record = bre.id AND mrfr.tag = '264')
    WHERE NOT bre.deleted
)
SELECT metabib.reingest_metabib_field_entries(id, TRUE, FALSE, TRUE, TRUE)
FROM affected_bibs;
--------------------------------------------------------------------------





==== Circulation ====



===== Hold Groups =====

This feature allows staff to add multiple users to a named hold group
bucket and place title-level holds for a record for that entire set of users.
Users can be added to such a hold group bucket from either the patron
search result interface, via the Add to Bucket dropdown, or through a dedicated
Hold Group interface available from the Circulation menu.  Adding new
patrons to a hold group bucket will require staff have the PLACE_HOLD
permission.

Holds can be placed for the users in a hold group bucket either directly from
the normal staff-place hold interface in the embedded OPAC, or by supplying the
record ID within the hold group bucket interface.  In the latter case, the
list of users for which a hold was attempted but failed to be placed can be
downloaded by staff in order to address any placement issues.  Placing a
hold group bucket hold will requires staff have the MANAGE_HOLD_GROUPS
permission, which is new with this development.

In the event of a mistaken hold group hold, staff with the MANAGE_HOLD_GROUPS
permission will have the ability to cancel all unfulfilled holds created as
part of a hold group event.

A link to the title's hold interface is available from the list of hold group
events in the dedicated hold group interface.




===== Scan Item as Missing Pieces Angular Port =====

The 'Scan Item As Missing Pieces' interface is now an Angular interface.
The functionality is the same, but the interface displays more details
on the item in question (title/author/callnum) before proceeding with the 
missing pieces process.




===== Opt-In Setting for Overdue and Predue Emails =====

The "Receive Overdue and Courtesy Emails" user setting permits users to
control whether they receive email notifications about overdue items.

To use the setting, modify any action trigger event definitions which
send emails about overdue items, setting the "Opt In Setting" to
"circ.default_overdue_notices_enabled" and the "User Field" to "usr".
You can accomplish this by running the following query in your database:

----
UPDATE action_trigger.event_definition
SET opt_in_setting = 'circ.default_overdue_notices_enabled',
    usr_field = 'usr'
WHERE opt_in_setting IS NULL
    AND hook = 'checkout.due'
    AND reactor = 'SendEmail';
----

Once this is done, the patron registration screen in the staff client
will show a "Receive Overdue and Courtesy Emails" checkbox, which will
be checked by default.  To ensure that existing patrons continue to
recieve email notifications, you will need to add the user setting to
their accounts, which you can do by running the following query in your
database:

----
INSERT INTO actor.usr_setting (usr, name, value)
SELECT
    id,
    'circ.default_overdue_notices_enabled',
    'true'
FROM actor.usr;
----






===== Allow Circulation Renewal for Expired Patrons =====

The "Allow renewal request if renewal recipient privileges have
expired" organizational unit setting can be set to true to permit
expired patrons to renew circulations.  Allowing renewals for expired
patrons reduces the number of auto-renewal failures and assumes that a
patron with items out eligible for renewals has not been expired for
very long and that such patrons are likely to renew their privileges
in a timely manner.

The setting is referenced based on the current circulation library for
the renewal.  It takes into account the global flags for "Circ: Use
original circulation library on desk renewal instead of the
workstation library" and "Circ: Use original circulation library on
opac renewal instead of user home library."




==== OPAC ====



===== Consistent Ordering for Carousels =====

Carousel ordering is now stable and predictable:

 * Newly Cataloged Item and Newest Items by Shelving Location carousels are ordered from most recently cataloged to least recently cataloged.
 * Recently Returned Item carousels is ordered is from most recently returned to least recently returned.
 * Top Circulated Items carousels is ordered is from most circulated to least circulated.
 * 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.
  ** Emptying and refilling the bucket allows reordering.




===== Default Public Catalog to the Bootstrap Skin =====

The public catalog now defaults to the Bootstrap skin rather than the
legacy TPAC skin.

Bootstrap is now the default in order to encourage more testing, but
users should be aware of the following 
https://bugs.launchpad.net/evergreen/+bugs?field.tag=bootstrap-blocker[issues];
certain specific functionality is available only in the TPAC skin.

The TPAC skin remains available for use, but current Evergreen users
should start actively considering migrating to the Bootstrap skin.

In order to continue to use the TPAC skin, comment out the following
line in `eg_vhost.conf`

[source,conf]
-------------------
PerlAddVar OILSWebTemplatePath "@localstatedir@/templates-bootstrap" # Comment this line out to use the legacy TPAC
-------------------



===== Did You Mean? Single word search suggestions =====

This feature is the first in the series to add native search suggestions
to the Evergreen search logic.  A significant portion of the code is
dedicated to infrastructure that will be used in later enhancements to
the functionality.

====== Overview ======

When searching the public or staff catalog in a single search class (title,
author, subject, series, identifier, or keyword) with a single search term
users can be presented with alternate search terms.  Depending on how the
instance has been configured, suggestions may be provided for only
misspelled words (as defined by existence in the bibliographic corpus),
terms that are spelled properly but occur very few times, or on every
single-term search.

====== Settings ======

The following new library settings control the behavior of the suggestions:

* Maximum search result count at which spelling suggestions may be offered
* Minimum required uses of a spelling suggestions that may be offered
* Maximum number of spelling suggestions that may be offered
* Pg_trgm score weighting in OPAC spelling suggestions
* Soundex score weighting in OPAC spelling suggestions
* QWERTY Keyboard similarity score weighting in OPAC spelling suggestions 

There are also two new internal flags:

* symspell.prefix_length
* symspell.max_edit_distance

====== Upgrading ======

This feature requires the addition of new Perl module dependencies.  Please
run the app server and database server dependency Makefiles before applying
the database and code updates.

At the end of the database upgrade script, the administrator is presented
with a set of instructions necessary to precompute the suggestion
dictionary based on the current bibliographic database.  The first half
of this procedure can be started even before the upgrade begins, as soon
as the Evergreen database is no longer accessible to users that might
cause changes to bibliographic records.  For very large instances, this
dictionary generation can take several hours and needs to be run on a
server with significant RAM and CPU resources. Please look at the upgrade
script before beginning an upgrade and plan this dictionary creation as
part of the overall upgrade procedure.

Given a server, such as a database server with 64G of RAM, you should
be able to run all six of the shell commands in parallel in screen
sessions or with a tool such as GNU parallel.

These commands invoke a script that will generate a class-specific sub-set
of the dictionary, and can be used to recreate the dictionary if
necessary in the future.




===== Sort Holdings by Geographical Proximity =====

This functionality integrates 3rd party geographic lookup services to allow patrons
to enter an address on the record details page in the OPAC and sort the holdings
for that record based on proximity of their circulating libraries to the entered
address. To support this, latitude and longitude coordinates may be associated with
each org unit. Care is given to not log or leak patron provided addresses or the
context in which they are used.

Requires the following Perl modules: `Geo::Coder::Free`, `Geo::Coder::Google`, and `Geo::Coder::OSM`

Configuration instructions:

 . Register an account with a third party geographic location service and copy the API Key.
 . Configure the Geographic Location Service (Server Administration > Geographic Location Service > New Geographic Location Service).
 . 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.)
 . Enable Library Setting: Enable Holdings Sort by Geographic Proximity (set to True).
 . 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).
 . Enable Library Setting: Show Geographic Proximity in Miles (if not set, it will default to kilometers).
 . 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. 

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.


===== Library Groups =====

The Library Groups search feature revives a longstanding internal
concept in Evergreen called "Lassos," which allows an administrator
to define a group of organizational units for searching outside of
the standard organizational unit hierarchy.

Use case examples include creating a group of law or science
libraries within a university consortium, or grouping all school
libraries together within a mixed school/public library consortium.

Searches can be restricted to a particular Library Group from the
library selector in the public catalog basic search page and from
the new "Where" selector on the advanced search page.

Restricting catalog searches by Library Group is available only
in the public catalog and "traditional" staff catalog; it is not
available in the Angular staff catalog.

This feature adds a new permission, `ADMIN_LIBRARY_GROUPS`, that
allows updating Library Groups and Library Group Maps. This permission
is not associated with any profiles by default, and replaces
the `CREATE_LASSO`, `UPDATE_LASSO`, and `DELETE_LASSO` permissions. 

To define new library groups, use the Server Administration Library
Groups and Library Group Maps pages. An autogen and a reload of
Apache should be performed after making changes to Library Groups.


===== Easier Styling of Public Catalog Logo and Cart Images =====

Evergreen now has IDs associated with logos and cart images in the TPAC and Bootstrap OPACs to aid in customization.  Images are as follows:

* small Evergreen logo in navigation bar is 'topnav_logo_image'
* the large Evergreen logo in the center of the splash page of the TPAC is 'homesearch_main_logo_image' 
* the cart icon is 'cart_icon_image' 
* the small logo in the footer is 'footer_logo_image'

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.




===== Easier TPAC Customization via colors.tt2 =====

Twelve new colors for TPAC have been added to the colors.tt2 file as well as 
having corresponding changes to the style.css.tt2 file. These use 
descriptive rather than abstract names. These changes help avoid 
situations were unreadable values are placed on top of each other 
and where different values are wanted for elements that only refernece 
a single color previously. Guidelines are below for setting values that 
correspond to the previous values used in the colors.tt2 file.  
For more diverse customizations the OPAC should be reviewed before 
a production load.

* 'footer' is used for the background color of the footer. It replaces the 
'primary'.
* 'footer_text' sets the text color in the footer and replaces 'text_invert' 
* 'header' sets the background of the header and replaces 'primary_fade'
* 'header_text' sets the color of text in the header and replaces 'text_invert'
* 'header_links_bar' sets the background of the links bar that separates the 
header on the front page of the opac and replaces 'background_invert'
* 'header_links_text' sets the text on the links bar and replaces 'text_invert'
* 'header_links_text_hover' set the hover text color on the links bar and 
replaces 'primary'
* 'opac_button' sets the background color of the My Opac button and replaces 
'control'
* 'opac_button_text' explicitly sets the text color on the My Opac button  
* 'opac_button_hover' sets the background color of the My Opac button when the 
mouse is hovering over it and replaces 'primary'
* 'opac_button_hover_text' sets the text color of the My Opac button when the 
mouse is hovering over it and replaces 'text invert'

Note that is patch is primarily meant for users who wish to continue
using TPAC rather than the Bootstrap skin for a while; new Evergreen
users are advised to use the now-default Bootstrap skin.



===== Configurable Read More Accordion for OPAC Search and Record View (TPAC) =====

====== Read More Button ======

Public catalog record fields (in the TPAC skin only) now truncate
themselves based on a configurable amount of characters.  The full
field may be displayed upon hitting a (Read More) link, which will
then toggle into a (Read Less) link to re-truncate the field.

====== Configuration ======

`Open-ILS/src/templates/opac/parts/config.tt2` contains two new
configuration variables:


* `truncate_contents` (default: 1)
* `contents_truncate_length` (default: 50).

Setting `truncate_contents` to 0 will disable the read more
functionality.  The variable `contents_truncate_length` corresponds
to the amount of characters to display before truncating the text.
If `contents_truncate_length` is removed, it will default to 100.

Additional configuration for note fields can be made in
`Open-ILS/src/templates/opac/parts/record/contents.tt2`, allowing a
`trunc_length` variable for each individual type of note, which will
override `contents_truncate_length` for that specific
type of note.


====== Adding Read More Functionality to further fields ======

To add Read More functionality to any additional fields, you may use
the macro `accordion()`, defined in `misc_util.tt2`. It can take three
variables: `str`, `trunc_length`, and `element`. `str` corresponds to
the string you want to apply it to, `trunc_length` (optional) will
override `contents_truncate_length` if supplied, and `element`
(optional) provides an alternative HTML element to look at for the
truncation process (useful in situations such as the Authors and Cast
fields, where each field is processed individually, but needs to be
treated as a single field).




==== Reports ====


===== Reports Scheduler Improvements =====

Previously, the reports scheduler allowed duplicated reports
under certain circumstances.  A uniqueness constraint now
disallows this without adversely affecting the reports process.



==== Miscellaneous ====

* The 'Create Reservation' form in the Booking module now includes
  an option to search for the patron by attributes other than just
  their barcode. (https://bugs.launchpad.net/evergreen/+bug/1816655[Bug 1816655])
* The form to add a user to a Course now includes an option to search
  for the patron by attributes other than just their barcode. (https://bugs.launchpad.net/evergreen/+bug/1907921[Bug 1907921])
* For consistency with the menu action Cataloging => Retrieve Record by
  TCN Value, the staff catalog Numeric Search => TCN search now includes
  deleted bib records. (https://bugs.launchpad.net/evergreen/+bug/1881650[Bug 1881650])
* Add a new command-line script, `overdrive-api-checker.pl`, for testing
  the OverDrive API. (https://bugs.launchpad.net/evergreen/+bug/1696825[Bug 1696825])
* The Shelving Location Groups editor is ported to Angular. (https://bugs.launchpad.net/evergreen/+bug/1852321[Bug 1852321])
* The staff catalog now has the ability to add all search results (up to
  1,000 titles) to the basket in one fell swoop. (https://bugs.launchpad.net/evergreen/+bug/1885179[Bug 1885179])
* Add 'All Videos' as a search format. (https://bugs.launchpad.net/evergreen/+bug/1917826[Bug 1917826])
* Server-side print templates can now have print contexts set. (https://bugs.launchpad.net/evergreen/+bug/1891550[Bug 1891550])
* Add ability to set the print context for a print template to "No-Print"
  to specify, well, that a given receipt should never be printed. (https://bugs.launchpad.net/evergreen/+bug/1891550[Bug 1891550])
* Add Check Number as an available column to the Bill History grids. (https://bugs.launchpad.net/evergreen/+bug/1705693[Bug 1705693])
* Adds a new control to the item table in the TPAC public catalog only to
  specify that only items that are available should be displayed. (https://bugs.launchpad.net/evergreen/+bug/1853006[Bug 1853006])
* Adds warning before deleting bib records with holds (https://bugs.launchpad.net/evergreen/+bug/1398107[Bug 1398107])
* Library scope on (Angular) Administration pages now defaults to workstation location rather than consortium (https://bugs.launchpad.net/evergreen/+bug/1873322[Bug 173322])
* 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])

=== Acknowledgments ===

The Evergreen project would like to acknowledge the following
organizations that commissioned developments in this release of
Evergreen:

* BC Libraries Cooperative
* Community Library (Sunbury)
* Consortium of Ohio Libraries (COOL)
* Evergreen Community Development Initiative
* Evergreen Indiana
* Georgia PINES
* Linn-Benton Community College
* Pennsylvania Integrated Library System (PaILS)


We would also like to thank the following individuals who contributed
code, translations, documentation, patches, and tests to this release of
Evergreen:

* John Amundson
* Zavier Banks
* Felicia Beaudry
* Jason Boyer
* Dan Briem
* Andrea Buntz Neiman
* Christine Burns
* Galen Charlton
* Garry Collum
* Eva Cerniňáková
* Dawn Dale
* Elizabeth Davis
* Jeff Davis
* Martha Driscoll
* Bill Erickson
* Jason Etheridge
* Ruth Frasur
* Blake Graham-Henderson
* Katie Greenleaf Martin
* Rogan Hamby
* Elaine Hardy
* Kyle Huckins
* Angela Kilsdonk
* Tiffany Little
* Mary Llewellyn
* Terran McCanna
* Chauncey Montgomery
* Gina Monti
* Michele Morgan
* Carmen Oleskevich
* Jennifer Pringle
* Mike Risher
* Mike Rylander
* Jane Sandberg
* Chris Sharp
* Ben Shum
* Remington Steed
* Jason Stephenson
* Jennifer Weston
* Beth Willis

We also thank the following organizations whose employees contributed
patches:

* BC Libraries Cooperative
* Calvin College
* Catalyte
* CW MARS
* Equinox Open Library Initiative
* Georgia Public Library Service
* Kenton County Public Library
* King County Library System
* Linn-Benton Community College
* MOBIUS
* NOBLE
* Westchester Library System

We regret any omissions.  If a contributor has been inadvertently
missed, please open a bug at http://bugs.launchpad.net/evergreen/
with a correction.