LP#1842940: Don't allow self-edit or perm-restricted edit

[Evergreen.git] / docs / RELEASE_NOTES_3_4.adoc

Evergreen 3.4 Release Notes
===========================
:toc:
:numbered:

Evergreen 3.4-beta2
-------------------
The Evergreen 3.4-beta2 release includes security fixes for cross-site scripting
(XSS) vulnerabilities in the Evergreen public catalog. Testers of the Evergreen
3.4-beta1 release are encouraged to install this release, which does not
include any database updates since the beta 1.

Security Issue: XSS Vulnerability in Public Catalog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This release fixes several cross-site scripting (XSS) vulnerabilities
in the public catalog. When upgrading, Evergreen administrators should
review whether any of the following templates have been customized
or overridden. If so, either the template should be replaced with the
stock version or the XSS fix (which entails adding the `| html` filter
in several places) applied to the customized version.

 * `Open-ILS/src/templates/opac/browse.tt2`
 * `Open-ILS/src/templates/opac/parts/ebook_api/base_js.tt2`
 * `Open-ILS/src/templates/opac/parts/header.tt2`
 * `Open-ILS/src/templates/opac/parts/place_hold.tt2`
 * `Open-ILS/src/templates/opac/parts/place_hold_result.tt2`
 * `Open-ILS/src/templates/opac/parts/result/adv_filter.tt2`

They should also review the following templates.  If these templates have
been customized or overridden, either the template should be replaced with
the stock version or the XSS fix (which entails adding `rel="nofollow` to
external links) applied to the customized version.

* `Open-ILS/src/templates/opac/parts/record/summary.tt2`
* `Open-ILS/src/templates/opac/parts/result/table.tt2`

Upgrade notes
-------------

Minimum Required OpenSRF Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Evergreen 3.4 requires OpenSRF 3.2.x or later.

Updating OPAC colors.tt2 file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sites that have customized `colors.tt2` should add a line for
the new `link` color.  For example:

[source,perl]
----
link = "#3ef624", # lime green
----

The template can be found at opac/parts/css/colors.tt2.

marc_stream_importer.pl configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Because `marc_stream_importer.pl` now expects its configuration file to
be in the configuration directory, not the binary directory, existing
users will likely need to manually move the configuration file into
place.



New Features
------------



Administration
~~~~~~~~~~~~~~

Ability to specify specific date in action_trigger_aggregator.pl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An option, `--date`, has been added to the `action_trigger_aggregator.pl`
support script that allows the user to specify a specific date to aggregate
event output for.  This new argument cannot be used with either `--start-date`
or `--end-date`.  This option was added to simplify pulling event output for a 
single day.

Aged Billings and Payments
^^^^^^^^^^^^^^^^^^^^^^^^^^

Two new database tables are added for tracking aged billings and payments:
`money.aged_billing` and `money.aged_payment`.

Two new database views are added, `money.all_billings` and `money.all_payments`
for aggregating data across the active and aged tables.

When a circulation is aged, billings and payments linked to the circulation
are migrated from the active billing and payment tables to the new aged 
tables.

The new tables are accessible to the reporter.

New Action Trigger - Fine Limit Exceeded
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New optional email notification that is sent when a block is applied
to a patron's account due to excess fines.

(The patron block functionality itself already exists and is based on
the settings in Local Administration -> Standing Penalties (PATRON_EXCEEDS_FINES)
and Local Administration -> Group Penalty Thresholds.)

Install marc_stream_importer.pl By Default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The script for the MARC stream importer, `marc_stream_importer.pl`,
is now installed in the Evergreen `bin` directory (typically
`/openils/bin`) by default. It now also expects that its configuration
file will be in the usual config directory (typically `/openils/conf`)
and the example configuration file is installed there by default.


AuthProxy Support for Arbitrary LDAP Usernames
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

AuthProxy now supports LDAP-based login with a username that is
different from your Evergreen username.

This feature may be useful for libraries that use an LDAP server for
single sign-on (SSO).  Let's say you are a post-secondary library using
student or employee numbers as Evergreen usernames, but you want people
to be able to login to Evergreen with their SSO credentials, which may
be different from their student/employee number.  To support this,
AuthProxy can now be configured to accept your SSO username on login,
use it to look up your student/employee number on the LDAP server, and
log you in as the appropriate Evergreen user.

For this to work, in the AuthProxy configuration for your LDAP server in
`opensrf.xml`, set `bind_attr` to the LDAP field containing your LDAP
username, and "id_attr" to the LDAP field containing your student or
employee number (or whatever other value is used as your Evergreen
username).  If `bind_attr` is not set, Evergreen will assume that your
LDAP username and Evergreen username are the same.

Now, let's say your LDAP server is only an authoritative auth provider
for Library A.  Nothing prevents the server from reporting that your
student number is 000000, even if that Evergreen username is already in
use by another patron at Library B.  We want to ensure that AuthProxy
does not use Library A's LDAP server to log you in as the Library B
patron.  For this reason, a new `restrict_by_home_ou` setting has been
added to AuthProxy config.  When enabled, this setting restricts LDAP
authentication to users belonging to a library served by that LDAP
server (i.e. the user's home library must match the LDAP server's
`org_units` setting in `opensrf.xml`).  Use of this setting is strongly
recommended.

Angular Organizational Units Admin Page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Administration -> Server Administration -> Organizational Units 
page has been migrated to Angular.

pingest.pl Now Has a --rebuild-rmsr Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An option, `--rebuild-rmsr`, has been added to the `pingest.pl` support
script.  This option will rebuild the
`reporter.materialized_simple_record` (rmsr) table after the ingests are
complete.

This option might prove useful if you want to rebuild the table as
part of a larger reingest.  If all you wish to do is to rebuild the
rmsr table, then it would be just as simple to connect to the database
server and run the following SQL:

[source,sql]
----
SELECT reporter.refresh_materialized_simple_record();
----

Links in Public Catalog Now Have Separate Color
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Hyperlinks in the public catalog now have a separate color definition
in the `colors.tt2` template to make it easier to style the public
catalog header/footer to use the same background color as the center
panel.


Server-Managed Print Templates for Angular
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds support for generating print content via server-side web service.  
Server print templates are implemented as Template Toolkit and content
is compiled and generated on the server, based on runtime data provided
by clients.

Feature includes a new Angular admin interface for testing and editing
server-managed print templates.  The UI is accessed under Administration ->
Server Administration -> Print Templates, though the menu entry may be
moved to Administration -> Local Administration, once Local Administration is migrated
to Angular.

Two sample templates are included to demonstrate the format and 
functionality.  The `Holds For Bib Record` template may be tested by
navigating to the record holds tab in the Angular staff catalog 
(/eg2/en-US/staff/catalog/record/<record-id>/holds) and chose the 
`Print Holds` grid action.

Apache Configuration
++++++++++++++++++++

Apply Apache configuration changes to `eg_vhost.conf` and `eg_startup`.

* Add to `eg_vhost.conf`
[source,conf]
---------------------------------------------------------------------------
<Location /print_template>
    SetHandler perl-script
    PerlHandler OpenILS::WWW::PrintTemplate
    Options +ExecCGI
    PerlSendHeader On
    Require all granted
</Location>
---------------------------------------------------------------------------

* Add to `eg_startup`
[source,conf]
---------------------------------------------------------------------------
# Pass second argument of '1' to enable process-level template caching.
use OpenILS::WWW::PrintTemplate ('/openils/conf/opensrf_core.xml', 0); 
---------------------------------------------------------------------------

New Perl Dependency
+++++++++++++++++++

A new Perl module `HTML::Defang` is required for cleansing generated HTML 
of executable code for security purposes.  The dependency is added to 
the Makefile.install process for new builds.  Existing Evergreen instances
will need the dependency manually installed.

Installing on (for example) Ubuntu:

[source,conf]
---------------------------------------------------------------------------
sudo apt-get install libhtml-defang-perl
---------------------------------------------------------------------------

Angular Standing Penalty Admin Page
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Administration -> Local Administration -> Standing Penalties
page has been migrated to Angular.

Copy Alert Permissions Added to Seed Data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Copy alerts were improved in recent releases of Evergreen,
but the permissions were not assigned to any of the stock
permission profiles in the "seed data" supplied to first time
installations.

The VIEW_COPY_ALERT permission is now assigned to all profiles
under the "Staff" parent profile, and ADMIN_COPY_ALERT is now
assigned to Cataloging Administrator and should be available to
all Administrator profiles.

This change does NOT include an upgrade script, so site server
administrators are responsible for updating the permissions
profiles for their individual systems.

Architecture and Internals
~~~~~~~~~~~~~~~~~~~~~~~~~~

Angular Grid Improvements
^^^^^^^^^^^^^^^^^^^^^^^^^
Grids in new Angular staff interfaces now have options to

* allow users to filter results per-column
* make the grid header in tall/long grids sticky (i.e., the
  grid header continues to be displayed while the user
  scrolls through the grid)
* allow users to edit a record in a grid and save the results
  without losing one's place in grid paging.

Configurable APIs for Patron Authentication and Retrieval
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Many external services need to authenticate patrons and retrieve information
about their accounts from Evergreen.  Most of these services support some form
of HTTP-based authentication, but every service has its own requirements and
none of them support native Evergreen authentication.  Meanwhile, libraries
often need to restrict access to these external services based on patron type,
current status, standing penalties, and so on.

To meet these needs, Evergreen now has support for separate, configurable HTTP
API endpoints for remote patron authentication and retrieval.  Each RemoteAuth
endpoint handles a different external service or authentication method.  You
set up the endpoints you want in your Apache config; each one uses a generic
mod_perl handler to manage incoming requests, and specifies a Perl module that
can actually talk to the external service, as well as an authentication profile
that determines which patrons can be authenticated at this endpoint.  Support
for https://tools.ietf.org/html/rfc7617["Basic" HTTP Authentication] is
provided as a reference implementation.

open-ils.circ.renew.auto API Deprecated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `open-ils.circ.renew.auto` API added in release 3.2 is deprecated
and will be removed in Evergreen release 3.5.  Please switch to using
the `open-ils.circ.renew` API with the `auto_renew` option set to 1 in any
custom code.

Cataloging
~~~~~~~~~~

New Cancel Edit Button In Record Merge Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The web staff client's Record Merge dialog now has a "Cancel Edit"
button that is displayed when editing the lead record in place. Using
this button will abandon any pending record edits without requiring
that the entire dialog be dismissed.

Staff Catalog Basket Export Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds a new "Export Records" option to the staff catalog basket menu.
When selected, the user is directed to the Vandelay record export
interface, which will be set to "basket export" mode.  Staff can then
apply export preferences (usmarc, marxml, etc.) and export the basket
records.  In "basket export" mode, Vandley provides a link to return to
the catalog (preserving search parameters).

Copy Edit Interface Display Modifications
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hide Disabled Fields
++++++++++++++++++++

Disabling a field in the "Defaults" tab in the copy editor now hides the 
field instead of simply disabling it.

Working Items Moves Down
++++++++++++++++++++++++

The "Working Items" grid now sits below the item attribute edit area, so the
attributes are allowed to fill the horizontal space.

New Options for Importing Copies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Two new options for importing holdings have been added to MARC Batch
Import/Export:

. **Auto-overlay On-order Cataloguing Copies**: This is similar to
  "Auto-overlay In-process Acquisitions Copies," but for copies that were not
  created from an acquisitions workflow.  Holdings information in the incoming
  record will be used to overlay any existing On Order copies for the matching
  record which belong to the owning library defined in the Holdings Import
  Profile.  The Holdings Import Profile is also used to match incoming copies to
  existing copies, if possible; otherwise, On Order copies are overlaid in the
  order they were created.  The call number will also be overlaid if the
  incoming record provides one.
. **Use Org Unit Matching in Copy to Determine Best Match**: When there are
  multiple potential matching records, this feature allows the user to
  automatically select the record which has the most copies at libraries near
  the importing library in the org tree.  That is, starting at the importing
  library, it climbs the org tree, gradually expanding the scope at which it
  checks for holdings on matching records; once holdings are found, the record
  with the most holdings at that scope is selected for overlay.  If there are
  no matching records with holdings, then the default best match overlay is
  attempted.

Permissions
+++++++++++

Two new permissions control the use of these new features:

* IMPORT_ON_ORDER_CAT_COPY
* IMPORT_USE_ORG_UNIT_COPIES

Enhanced Request Items Functionality
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Request Items action available in the Item Status and Item Buckets
interfaces has been given an Honor User Preferences checkbox which does
the following for the selected user when checked:

 * Change the Pickup Lib selection to match the user's Default Hold Pickup Location
 * Honor the user's Holds Notification settings (including Default Phone Number, etc.)

Success and Failure toasts have also been added based on what happens
after the Request Items interface has closed.

Also, a Title Hold option has been added to the Hold Type menu.  This will create
one title-level hold request for each unique title associated with the items that were selected
when Request Items was invoked.

Display Codes in Physical Characteristics Wizard Drop-downs (LP#1776003)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Drop-downs in the Physical Characteristics Wizard in the MARC editor
now display both code and label.

Circulation
~~~~~~~~~~~

Booking Module Refresh
^^^^^^^^^^^^^^^^^^^^^^

The Booking module has been redesigned, with many of its interfaces being
redesigned in Angular.

This adds a new screen called "Manage Reservations", where staff can check details about
all outstanding reservations, including those that have been recently placed, captured,
picked up, or returned.

On many screens within the new booking module, staff are able to edit reservations.  Previously,
they would have needed to cancel and recreate those reservations with the new data.

There is a new notes field attached to reservations, where staff can leave notes about the
reservation.  One use case is to alert staff that a particular resource is being stored in
an unfamiliar location.  This field is visible on all screens within the booking module.

The Create Reservations UI is completely re-designed, and now includes a calendar-like view
on which staff can view existing reservations and availability.

New Permission: CREATE_PRECAT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This permission is required to create (or re-create) a pre-cataloged item
through the "Barcode ??? was mis-scanned or is a non-cataloged item."
dialog.  All form elements in the pre-cat dialog other than the Cancel
button will be disabled if the current user lacks the CREATE_PRECAT
permission when an uncataloged (or already pre-cataloged item) is scanned.
This permission is not needed to renew pre-cataloged items.

The upgrade script for this feature will insert the permission into every
permission group that has the STAFF_LOGIN permission, so out-of-the-box no
behavior will change.

Enhanced Mark Item Functionality
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Evergreen's Mark Item Damaged and Mark Item Missing functionality has
been enhanced, and the ability to mark an item with the Discard/Weed
status has been added.  This enhancement affects both the Evergreen
back end code and the staff client.

Staff Client Changes
++++++++++++++++++++

The option to "Mark Item as Discard/Weed" has been added to areas
where the option(s) to "Mark Item as Missing" and/or "Mark Item as
Damaged" appear.  This is primarily in the action menus on the
following interfaces:

 * Item Status
 * Checkin
 * Renew
 * Holds Pull List
 * Patron Holds List
 * Record Holds List
 * Holds Shelf
 * Holdings Edit

This new option allows staff to mark a copy with the Discard/Weed
status quickly and easily without necessarily requiring the
intervention of cataloging staff.  In order to mark an item with the
Discard/Weed status, staff will require either the `MARK_ITEM_DISCARD`
or `UPDATE_COPY` status at the item's owning library.  (NOTE: This
permission choice is consistent with the permission requirements for
the current Mark Item Damaged or Missing functionality.)

If the item to be marked Discard/Weed is checked out to a patron, the
staff will be presented with a dialog informing them that the item is
checked out and asking if they would like to check it in and proceed.
If they choose to continue, the item will be checked in and then
marked with the Discard/Weed status.  If the staff person chooses to
cancel, then the item will not be checked in, and it will not be
marked Discard/Weed.  The Mark Item Missing functionality has also
been changed to exhibit this behavior with checked out items.  The
Mark Item Damaged functionality already handles checked out items.

Should the item have a status of In Transit at the time it is to be
marked, then staff will be prompted to abort the transit before
proceeding with changing the item's status.  If they choose to abort
the transit and they have the permission to do so, the transit will be
aborted and the item's status changed.  If they choose to cancel, then
the transit will not be aborted and the item's status will remain
unchanged.  This change applies to all three of the current Mark Item
statuses: Missing, Damaged, and Discard/Weed.

Marking an item Discard/Weed is typically one step away from deleting
the item.  For this reason, if the item to be marked Discard/Weed is
not in a Checked Out or In Transit status, but it is in a status that
restricts item deletion, the staff will be presented with a dialog
notifying them of the item's status and asking if they wish to
proceed.  If staff choose to proceed and they have the
`COPY_DELETE_WARNING.override` permission, then the item will be
marked with the Discard/Weed status.  Naturally, the item's status
will be unchanged if they choose not to proceed.  This change does not
affect the marking of an item as Missing or Damaged.

Marking an item as Discard/Weed has one more additional check that the
other statuses do not.  If the item being marked as Discard/Weed is
the last copy that can fill a hold, then staff will also be notified
of this condition and asked if they wish to continue.  In this case,
there is no permission required.  Whether or not the item is marked as
Discard/Weed in this case depends solely on the staff's choice.

Back End Changes
++++++++++++++++

In order to accommodate the presentation of dialogs and overrides in
the staff client, the `OpenILS::Application::Circ` module's method for
marking item statuses has had a few changes made.  Firstly, the code
of the `mark_item` function has been rearranged to a more logical
flow.  Most of the condition and permission checks are made before
creating a transaction.  Secondly, it has been modified to return 3
new events when certain conditions are met:

 * `ITEM_TO_MARK_CHECKED_OUT`
 * `ITEM_TO_MARK_IN_TRANSIT`
 * `ITEM_TO_MARK_LAST_HOLD_COPY`

The `COPY_DELETE_WARNING` event will be returned when attempting to
mark an item with the Discard/Weed status and the status has the
`restrict_copy_delete` flag set to true.

The function now also recognizes a hash of extra arguments for all
statuses and not just for the mark Damaged functionality.  This
argument hash can be used to bypass or override any or all of the
above mentioned events.  Each event has a corresponding argument that
if set to a "true" value will cause the `mark_item` to bypass the
given event.  These argument flags are, respectively:

 * `handle_checkin`
 * `handle_transit`
 * `handle_last_hold_copy`
 * `handle_copy_delete_warning`

The code to mark an item damaged still accepts its previous hash
arguments in addition to these new ones.

The function still returns other errors and events as before.  It
still returns 1 on success.

It is also worth noting here that the staff client can be easily
extended with the ability to mark items into the other statuses
offered by the back end functions.  Most of the staff client
functionality is implemented in two functions with placeholders in the
main function (`egCirc.mark_item`) for the unimplemented statuses.

Library Links in Billing Details screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Billing Full Details view now includes links to information about the billing and owning
libraries. This can be useful in situations where circulation staff are troubleshooting a
bill and would like to quickly find contact information for the billing or owning library.

Client
~~~~~~

Cross-Tab Communication Demo
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Angular Sandbox now includes an example
for developers interested in sharing data
between staff client browser tabs.

(Experimental) Staff Catalog: Record Holds Tab
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Adds support for the Holds tab in the record detail view of the Angular
staff catalog.  Includes grid and hold-related actions.

 * Holds grid
 * Batch cancel holds
 * Batch retarget holds
 * Batch edit holds
  ** Unified form to modify notify options, dates, etc.
 * Hold detail page (menu and row double-click)
 * Batch mark items damaged
 * Batch mark items missing
 * Show last few circulations
 * Retrieve patron

(Experimental) Staff Catalog: Call Number Browse
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Adds support for call number browsing in the staff catalog.  The browse
results display vertically for consistency with the regular search and
browse result interfaces.

(Experimental) Staff Catalog: Recent Searches & Templates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Recent Searches
+++++++++++++++

Adds support for Recent Searches in the Angular staff catalog, consistent
with TPAC staff recent searches.  Setting a value for the library setting
`opac.staff_saved_search.size` is required for the recent searches to appear.

Search Templates
++++++++++++++++

Adds support for named catalog search templates.  Templates allow staff to
create predefined searches (e.g. title =, subject =, format =, etc.) 
where all that's left do to perform the search is fill in the search 
values.

Templates may be built from any of the search tabs -- search, numeric search, 
marc, and browse -- except shelf browse, which uses no filters.

Templates are stored by default as workstation settings, using the setting
key `eg.catalog.search_templates`.

Port Permission Group Admin to Angular
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Administration -> Server Administration -> Permission Groups admin page has been migrated to 
Angular.

As an added feature, the interface now displays inherited permissions
alongside linked permissions for each group.  Inherited permissions
are read-only and act to indicate to the user when a group already has
a certain permission and therefore may not need a new one added.

Additionally, a new filter option is available in the linked permissions
interface for filtering the displayed linked permissions by code or 
description.

Port Org Unit Type Admin to Angular
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Administration -> Server Admininistration -> Organization Types admin page has been migrated to 
Angular.

Port Local Administration Page to Angular
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Administration -> Local Administration page has been migrated
to Angular along with the following specific Local Administration
interfaces:

 * Address Alerts
 * Barcode Completion
 * Group Penalty Thresholds
 * Hold Policies
 * Item Alert Suppression
 * Item Tags
 * Non-Cataloged Types Editor
 * Shelving Location Editor
 * Statistical Popularity Badges

Public Catalog
~~~~~~~~~~~~~~

Carousels
^^^^^^^^^
This feature fully integrates the creation and management of book carousels
into Evergreen, allowing for the display of book cover images on a library’s
public catalog home page.  Carousels may be animated or static.  They can be
manually maintained by staff or automatically maintained by Evergreen.  Titles
can appear in carousels based on newly cataloged items, recent returns,
popularity, etc.  Titles must have copies that are visible to the public
catalog, be circulating, and holdable to appear in a carousel.  Serial titles
cannot be displayed in carousels.  

Administration
++++++++++++++
This feature introduces the concepts of Carousel Types, Carousels, and Carousel
Library Mappings. The first can be administered in Server Administration
while the latter two can be administerd in Local Administration.

Carousel Types define the attributes of a carousel, such as whether it is
automatically managed and how it is filtered.  A carousel must be associated
with a carousel type to function properly.    

There are five stock Carousel Types:

  * Newly Cataloged Items - titles appear automatically based on the active date of the title’s copies
  * Recently Returned Items - titles appear automatically based on the mostly recently circulated copy’s check-in scan date and time  
  * Top Circulated Titles - titles appear automatically based on the most circulated copies in the Item Libraries identified in the carousel definition; titles are chosen based on the number of action.circulation rows created during an interval specified in the carousel definition and includes both circulations and renewals
  * Newest Items by Shelving Location - titles appear automatically based on the active date and shelving location of the title’s copies 
  * Manual - titles are added and managed manually by library staff

While additional Carousel Types can be added using the administration
interface, new automatic types currently require additional Perl code
to be recognized.

Carousel definitions allow the operator to specify the type, owner,
name and, for automatically-maintained types, the item libraries and
shelving locations to look for titles to populate the carousels as
well as how far back to look for titles.

Carousel Library Mappings specify the libraries that the carousel
should be displayed out. The visibility of a carousel at a given organizational
unit is not automatically inherited by the descendants of that unit.  The
carousel’s owning organizational unit is automatically added to the list of
display organizational units.

A server-side job, `refresh_carousels.srfsh`, is available to periodically
refresh the contents of automatic carousels.

Staff Interface
+++++++++++++++
Each carousel has a record bucket associated with it. Library staff can
add titles to a carousel's bucket, and for the manual Carousel Type, that
is the only way to populate the carousel. Records added to an automatic
carousel's bucket will be removed whenever the carousel is next
refreshed.

Public Catalog
++++++++++++++
A new Template Toolkit macro called “carousels” allows the Evergreen
administrator to inject the contents of one or more carousels into any point in
the OPAC.  The macro will accept the following parameters:

  * `carousel_id`
  * `dynamic` (Boolean, default value false)
  * `image_size` (small, medium, or large)
  * `width` (number of titles to display on a “pane” of the carousel)
  * `animated` (Boolean to specify whether the carousel should automatically cycle through its panes)
  * `animation_interval` (the interval (in seconds) to wait before advancing to the next pane)

If the `carousel_id` parameter is supplied, the carousel with that ID will be
displayed.  If `carousel_id` is not supplied, all carousels visible to the public
catalog’s `physical_loc` organizational unit is displayed.

Item Tags Now Display Tag Type Labels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When item tags display in the catalog, they will now include the label from the
item tag type.  For example, for a tag of type "Digital Bookplate", here is a
comparison of the old and new display:

 * Old output: "(Tag Value Here)"
 * New output: "Digital Bookplate: (Tag Value Here)"

The type label is wrapped in a new CSS class `copy_tag_type_label` that allows
it to be styled separately from the tag value or hidden entirely.

New Column in Items Out Display
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A new column, Owning Library, is now optionally available for the OPAC
Items Out display which shows the owning library of the item (not
necessarily the library at which the item was picked up).  Clicking on
the library name will provide contact information for that library.
This is useful for When a patron has run out of renewals and the
owning library, not the patron's home library, is the one with whom
the patron will negotiate additional renewals.  If the patron will
negotiate additional renewals with their home library or the checkout
library, then display of this field is superfluous.

The display of this column is controlled by the organization setting
`opac.show_owning_library_column.`

SIP
~~~

Fine Item Detail Enhancements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
SIP now suppports enhancements for the Fine Item Detail returned by
by Patron Information Response (code 64).  Different manufacturers
of self-check systems specify the format of the fine item detail
differently.  A new option allows you to select the format to return.

Configuration
+++++++++++++
After installation of Evergreen and SIP, in the Evergreen configuration
directory (typically /openils/conf) the SIP configuration file
oils_sip.xml awaits your modifications to use this feature.

In the <accounts><login> sections, you can add an attribute of the form
    `av_format="__<value>__"`

where __<value>__ is one of thsee values:

* `3m`
* `eg_legacy`
* `swyer_a`
* `swyer_b`

For example:

<login id="sipclient" password="password" institution="gapines" av_format="3m"/>

If you omit the option, 'eg_legacy' will be used as the default.

Currently, the behaviour of `eg_legacy` is close to, but not precisely
that of `3m`.  The `eg_legacy` produces the pre-enhancement behavior in
Evergreen.  Currently, the `swyer_a` behavior is identical to that of
`3m`, but there is no guarantee that this will always be the case.

If you change the brand of your self-check equipment, you may need to
change the value of the option to be consistent with the new brand.

Option to Limit Hold Items to Available
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A new option has been added to the SIP2 implementation configuration,
`msg64_hold_items_available`.  When set, this option will limit the
count and list of hold items in the SIP2 patron information response
message (64) to only those holds that are available for pickup.  When
not set, the full list of the patron's holds will continue to be sent.
This option is useful because some self checks expect to receive only
the list of available holds in the hold items and have few settings to
control the display of holds.

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

* BC Libraries Cooperative
* CW MARS
* Georgia Public Library Service
* Indiana State Library
* King County Library System
* MassLNC
* Pennsylvania Integrated Library System


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

* Felicia Beaudry
* A. Bellenir
* Jason Boyer
* Mark Bucholtz
* Christine Burns
* Eva Cerninakova
* Galen Charlton
* Garry Collum
* Jeff Davis
* Bill Erickson
* Jason Etheridge
* Rogan Hamby
* Abdul Munif Hanafi
* Kyle Huckins
* Sam Link
* Kathy Lussier
* Terran McCanna
* Andrea Buntz Neiman
* Dan Pearl
* Mike Risher
* Mike Rylander
* Geoff Sams
* Jane Sandberg
* Chris Sharp
* Ben Shum
* Remington Steed
* Jason Stephenson
* Josh Stompro
* Meg Stroup
* Cesar Velez
* Dan Wells
* Liam Whalen

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
* Grand Rapids Public Library
* Greater Clarks Hill Regional Library
* Indiana State Library
* Kenton County Public Library
* King County Library System
* Linn-Benton Community College
* Roanoke Public Library
* South Carolina State Library

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