Docs: Revising 3.3 release notes and related docs

[working/Evergreen.git] / docs / RELEASE_NOTES_2_4.adoc

Evergreen 2.4.0 Release Notes
=============================
:toc:
:numbered:

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

Custom Toolbar Permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~
With the addition of more granular permissions for configuring a custom
toolbars, the ADMIN_TOOLBAR permission alone will not allow users to 
configure a custom toolbar. This permission must now be used in conjunction
with one or more of the following permissions:

* ADMIN_TOOLBAR_FOR_ORG
* ADMIN_TOOLBAR_FOR_USER
* ADMIN_TOOLBAR_FOR_WORKSTATION

New features
------------

Acquisitions
~~~~~~~~~~~~

Acquisitions Inline Item Detail View
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Acquisitions selection lists and purchase order interfaces contain a new link
beside each lineitem which, when clicked, creates an inline grid of copies
linked to the lineitem.  The grid contains the same information that displays
in the full copy edit grid (from clicking on the Copies(n) link).  However,
the inline grid is read-only, so it displays much faster and does not require
the user to change visual contexts.  

Included along the top of the lineitem table is a new 'Expand All' link which, 
when clicked, expands or collapses the inline grid for all visible lineitems.

Acquisitions Lineitem Order Identifiers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Staff now have the ability to specify the identifier value to use for
lineitems when communicating order information to vendors.  This is 
particularly important when a lineitem has, for example, multiple ISBNs.
Determining which ISBN is to act as the "order identifier" allows staff
to provide the most accurate order information to vendors.  

Supported identifier types include ISBN, ISSN, and UPC.  Order identifier 
values are relayed to vendors via EDI and print PO.

Permissions
+++++++++++++
Two new permissions are added for this feature:

 * ACQ_SET_LINEITEM_IDENTIFIER
  ** Allows staff to apply order identifiers to lineitems
 * ACQ_ADD_LINEITEM_IDENTIFIER
  ** Implies that new identifiers shall be added to linked bib records, 
     when a linkage exists.

Acquisitions Purchase Order and other Interface Improvements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Feature Summary
+++++++++++++++

The following features, which primarily affect the user interface layer,
improve Acquisitions work flows.

  * Avoid double-activation of POs
  * Disable invoice and cancel options for pending POs
  * Disable zero-copy checkbox for activated POs
  * Disable new charges for activated POs
  * Replace "Shelving Location" with Copy Location

  * Rearranging "actions" drop-down
    ** More consistency in actions applying to selected lineitems specifically
    ** Things moved from the per-lineitem dropdown to the main one when
       sensible.
    ** Add to PO dialog added
    ** You can no longer add lineitems to a PO if they're already on one.
    ** Actions in dropdown now enabled/disabled differently depending on
       the interface where it appears (PO vs Selection List vs Acq Search etc.)

  * Batch update for line items
     ** Apply updates to all copies of all selected line items at once
     ** Relies on a middle layer method that streams back information that
        would suit a more asynchronous display in the future (rather than
        simply reloading the page upon success, which it does now)
     ** For failure cases, specific information about which line item cannot
        be updated, and why, is available to the client, although taking
        best advantage of this information for user-friendly display is left
        to the future.
  * Add optional fund, circ modifier and collection code fields to distribution
  formulas.
  * The invoices interface auto-populates "# Invoiced" column with number of
  invoiceable copies, and copies the "billed cost" column to the "amount paid"
  column if the latter doesn't have anything in it yet.

Acquisitions MARC Upload Form Persistence
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Adds a two-layer persistence mechanism for the acquisitions MARC file upload
interface.  A set of org unit settings now exist for managing default values
for the interface.  Additionally, for each field where no org unit setting
value is configured, the last-used value will be persisted locally and re-
used with subsequent loads of the interface.

Default Number of Acquisitions Copies to Order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Acquisitions providers have a new "Default # Copies" field.  When the value
is set, this number of copies will be automatically added to each lineitem
added to a purchase order for the provider.  This takes place during PO
creation from a selection list or existing bib record and when a lineitem is 
added to an existing purchase order.  If a lineitem already has copies 
attached, no default copies are added.

OPAC
~~~~

Removal of JSPAC
^^^^^^^^^^^^^^^^
TPAC is now the default catalog in Evergreen. The default apache configuration
now points to TPAC, staff client OPAC options now point to TPAC, and the JSPAC
to TPAC toggle has been removed from the portal page.

Display alternate graphic (880) fields
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, Evergreen displays alternate graphic fields, if any, for
contributors (1xx / 7xx), titles (245), edition statements (250), imprints
(260), notes (5xx), subjects (6xx), and series (4xx / 8xx) in search results and record details
per the Library of Congress MARC21 specifications:

* http://www.loc.gov/marc/bibliographic/bd880.html
* http://www.loc.gov/marc/bibliographic/ecbdcntf.html
* http://www.loc.gov/marc/bibliographic/ecbdmulti.html (Model A)

Default display
+++++++++++++++
In general, alternate graphic fields display below the corresponding
primary field. One exception is the attribution summary on the record details
page, in which the alternate graphic field contents display between the
primary field content and the attribution statement. To support CSS
customizations, HTML elements for the graphic fields have the class attribute
value `graphic880`.

MARC21 Feeds from OpenSearch
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to the already supported formats, you can now get raw MARC21 from
OpenSearch feeds, à la:

    http://<host>/opac/extras/opensearch/1.1/-/marc21?searchTerms=piano


Options to Hide Some User Preferences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The config.tt2 file now provides options to disable phone notification options, password changes, and e-mail address changes in TPAC. These options are useful
for libraries that do not do phone notifications and for those that use
centralized authentication. 

Note the ability to disable user name changes is already available through the
Library Settings editor.

Public Copy Notes
^^^^^^^^^^^^^^^^^
Public copy notes are now visible in TPAC.

Search Changes
^^^^^^^^^^^^^^
A number of changes have been made to search to allow more control and improve
performance. These changes and their associated configurations are global to
the entire system and can not be configured on a per-library basis.

Amongst other things the new search code fixes:

* Invalid queries being generated from advanced searches
* Some timeouts from backend code taking too long to perform a search
* Some filters being one-use only
* Negations not working properly where multiple indexes are involved

Improvements include:

* Exact matches on input should be more likely to float to the top of results
* Non-English stemming can be used, alongside or instead of English stemming
* Entered search terms can be found across multiple indexes

Default configuration is geared towards English but is easily changed. In a
production environment changes will likely require re-indexing, however.

The upgrade script could be pre-tweaked to install desired configuration before
it builds and/or re-builds many of the indexes.

Permissions
+++++++++++
One new permission is added for this feature:

  * ADMIN_INDEX_NORMALIZER

Searching for deleted records
+++++++++++++++++++++++++++++
Evergreen now supports searching for deleted records via the '#deleted'
QP modifier.

In order to support this, sites must enable the
'ingest.metarecord_mapping.preserve_on_delete' internal flag.  It is off by
default since the ability to search for deleted records requires keeping
metarecord mappings around when bibs are deleted, which may not be desirable
for the typical site.

Two new QP filters: create_date and edit_date
+++++++++++++++++++++++++++++++++++++++++++++
These filter on the fields of the same name in biblio.record_entry.

e.g.

  * create_date(,2013-02-01)  =>  records created before 2013-02-01
  * create_date(2013-02-01)   =>  records created since 2013-02-01
  * create_date(2013-02-01,2013-02-28)  =>  records created in Feb 2013
  * create_date(yesterday)    =>  records since created yesterday

Show local call number in TPAC My Lists display
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If an opac-visible call number exists that is owned by an org unit
relevant to the patron, show the most relevant call number label
and owning branch name in the My Lists display for each record in
the list.  Call number is displayed in both saved and temporary lists.

A call number is considered relevant if its owner is one of:

physical location library
preferred library (plib, home, etc.)
search library

If no relevant call number is found, no call number is displayed.

TPAC Google Books preview
^^^^^^^^^^^^^^^^^^^^^^^^^
Setting `ctx.google_books_preview` to `1` in the TPAC `config.tt2`
configuration file will cause the TPAC to check to see, as part of the record
details view, if Google Books has an online preview available. If it does,
then a preview button will be displayed in the book cover image location.
If the user then clicks the preview button, the preview will load below the
title of the book in the record details page.

By default, this functionality is disabled to protect the privacy of users
who might not want to share their browsing behavior with Google.

TPAC Novelist Select Integration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The URL for Novelist Select integration with TPAC has changed, and so
has the manner in which it is configured in `eg_vhost.conf.` You will
find a section like the following in `eg_vhost.conf:`

-------------------------------------------------------------------------------
    # Novelist
    # SetEnv OILS_NOVELIST_URL http://imageserver.ebscohost.com/novelistselect/ns2init.js
    # SetEnv OILS_NOVELIST_PROFILE <profile>
    # SetEnv OILS_NOVELIST_PASSWORD <password>
-------------------------------------------------------------------------------

You will want to remove the hash marks on the three lines that have
`SetEnv` in them.  You will also want to replace `<profile>` and
`<password>` with your Novelist Select profile and password provided
to you by EBSCO.

TPAC Org Unit Hiding
^^^^^^^^^^^^^^^^^^^^
Adds support for the opac.org_unit_hiding.depth org unit setting to
TPAC, which makes out-of-scope org units disappear (except when
explicitly requested).

Org unit hiding is based on the physical_loc (Physical Location) param /
cookie, which is the closest analog to 'ol' (original location), from
which it was based in the JSPAC.

UI Changes
++++++++++

 * All search org unit selectors
 * Holds pickup lib selector
 * Copy summary in search results page
 * Copy list in search results page
 * Copy summary in record detail page (which controls the copy grid).
 * Hold summary in record detail page

Cataloging
~~~~~~~~~~

MARC Import Tag Stripping
^^^^^^^^^^^^^^^^^^^^^^^^^
Administrators can configure MARC tags which are removed from MARC records 
imported via Z39.50 and the Vandelay MARC Import/Export UI (ACQ and non-ACQ).  
Tags are organized into groups.  Groups can be marked as optional or required.
For each tag, every instance of the tag (including all subfields) are removed 
from the record.

MARC fields which are contained within required ('always_apply') tag groups
are always removed from inbound records.  No action is needed.  Tag groups 
which are optional will appear in MARC import interfaces (see below) allowing 
staff to select which groups of tags to strip from incoming records at import 
time.

Interfaces Affected
+++++++++++++++++++

 * Admin UI
  ** Admin => Server Administration => MARC Import Remove Fields
 * Z39.50 Import
  ** Cataloging => Import Record from Z39.50
  ** Optional groups appear with the other import options
 * Vandelay
  ** Cataloging => MARC Import/Export (Vandelay)
  ** Acquisitions => Load Order Records
  ** Optional groups appear with the other import options

Permissions
+++++++++++
Three new permissions are added for this feature:

  * CREATE_IMPORT_TRASH_FIELD
  * UPDATE_IMPORT_TRASH_FIELD
  * DELETE_IMPORT_TRASH_FIELD

Vandelay Default Match Set
^^^^^^^^^^^^^^^^^^^^^^^^^^
A new org unit setting to specify a default Record Match Set when 
importing MARC records through the MARC Batch Import/Export interface. It does
not affect the default match set selected in acquisitions. If this
is set, it will not be possible to leave the Record Match Set field blank;
it may be necessary to define a default match set that replicates the current
default behavior. 

A new "Vandelay" org unit settings group is also created.

Direct access to Item Attribute Editor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can now access the item attribute editor via Admin -> Local Admin -> Item
Attribute Editor. No copy record is loaded into the editor, but it is available to without first finding an item and loading it into the editor:

  * Configure copy templates.
  * Hide fields in the copy editor.

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

Clickable Patron Indicators
^^^^^^^^^^^^^^^^^^^^^^^^^^^
When retrieving a patron record, staff can now click on the indicators listed 
beneath the patron's name and launch the related tabs.

For example, clicking on (See Notes) will open the associated patron's notes.

"Warn patrons when their account is about to expire"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To give staff the ability to warn patrons when their account is about to
expire, the staff client can display an alert message on the patron information
window.  A new library setting, `Warn patrons when their account is about to
expire` in the *Circulation* section of the *Library Settings Editor*,
determines how many days in advance of a patron's account expiry date the alert
should be displayed. By default, warnings about upcoming patron account expiry
dates are not displayed.

Show Hold Patron Name in TPAC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When looking up patron information for hold placement via the staff client in
TPac, the hold patron name is now shown next to the entered barcode. In the
event that the barcode is not found, a notice is displayed and the submit
button is disabled until a valid barcode is entered or the staff member is
switched to.

Show Holds On Bib Menu Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Add direct "Show holds on bibs" menu option from item checkin, item status, 
and patron hold interfaces. This gives staff a quicker way of viewing who 
else has holds on an item instead of having to click an option to view the 
bib record, then clicking into the menus to view holds.

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

Calculated Proximity Adjustments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Allows customization to the way that Evergreen measures the distance between
org units for the purposes of 1) determining what copy at what org unit is best
suited for targeting a title-level hold, and 2) determining what hold is best
suited for fulfillment by a copy-in-hand at capture (checkin) time.  The
customization is based on a table 'actor.org_unit_proximity_adjustment', with
certain matching criteria that the system compares to properties of the holds
and copies in question.

Permissions
+++++++++++
One new permission is added for this feature:

  * ADMIN_PROXIMITY_ADJUSTMENT
    ** Allows staff to administer the proximity adjustments


Custom best-hold selection sort order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ranking algorithm that chooses the best hold to target a copy in 
hand at a capture time used to be fairly simple.  It had two modes, FIFO
and not-FIFO, and that was it.

This change allows full configuration of that algorithm.  In other 
words, when the system captures a copy and sets out to evaluate what
hold, if any, that copy might best fulfill, site staff of sufficient
permission level are now empowered to choose exactly which comparisons
the systems makes in what order.  This gives said staff much greater
flexibility than they have today over holds policy.

For more information, see the included tech spec documents.

Permissions
+++++++++++
One new permission is added for this feature:

  * ADMIN_HOLD_CAPTURE_SORT
    ** Allows staff to administer the custom best-hold selection sort order.

Generic CSV Notification Generator/Receiver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

New Action/Trigger template and sample event definitions for creating a CSV
export file for various patron actions, primarily for the purpose of creating
patron notices via external notification mechanisms.

The reference implementation for this development is the TalkingTech iTiva
product, which consumes CSV files for generating phone/text notifications and
produces CSV results files for informing the ILS of notification statuses.  
The template and send/receive scripts, however, should be generic enough to 
create CSV for any type of 3rd-party notification product.

For more information, see the included tech spec documents.

Storing Z39.50 Server Credentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the Z39.50 configuration interface, staff now have the option to apply
z39.50 login credentials to each Z39.50 server at different levels of the 
org unit hierarchy (similar to org unit settings).  When credentials are set 
for a Z39 server, searches against the z39 server will used the stored 
credentials, unless other credentials are provided by the caller, in which 
case the caller credentials are used.

For security purposes, passwords may not be retrieved or reported on by staff.  
Staff can only apply new values for credentials or clear existing ones.

URL Verification
^^^^^^^^^^^^^^^^
In order to support verification of URLs, Evergreen now has several new
capabilities, and extensions to some existing features.

A wizard-style interface that walks a staff member through the process of collecting records and URLs to verify, verifying and reviewing the URLs.

URL validation sessions are built as a whole to support immediate and
future review of any URLs.  Each session carries a name, an owner, a set
of record search criteria, a set of tag and subfield combinations describing
the location of URLs to validate, a record container for tracking individual
records to verify, and a set of state and data tables for managing the
processing of individual URLs.

A set of middle-layer methods provide the business logic required to collect
records, extract, parse and test the validity of the URLs.

For more information, see the included tech spec documents.

Permissions
+++++++++++
One new permission is added for this feature:

 * URL_VERIFY

Serials
~~~~~~~

Serial Control: Embed Alternate Interfaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As another step toward a unified interface, the serial control subscription
editor now consists of an embedded version of the alternate control. This
reduces duplication of both code and documentation, and smooths the eventual
transition to a single interface.

In order to not lose any essential features, the following additions were made
to the new combination editor:

* note editors on subscriptions and distributions
* labeled dropdown for distribution summary options ("Add to record entry", "Use record entry only", etc.)
* legacy record entry linkage setup (Allows one to tie a distribution's information to a particular serial record entry (i.e. a MFHD record))

Serial Control: Set Special Statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Serial Control interface prevents direct editing of serial item statuses
for data integrity reasons. As an alternative to direct control, the interface
now offers new menu options for setting items to 'claimed', 'not held', and
'not published'. Note that these statuses are still currently useful for
reporting and display purposes only.

Staff Client
~~~~~~~~~~~~

Staff client search preferences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Staff can now set workstation-level search preferences through Admin ->
Workstation Administration -> Set Search Preferences. 

  * Default Search Library sets the library that is searched by default from
  the advanced search page and the portal page.
  * Preferred library is used to identify copies that should display first.
  * Advanced search default pane allows staff to set the numeric or expert
  searches as the default search tab.

The option to change the preferred search library from the search results page
is no longer available when logged into the staff client.

add "about:about" to developer menu in staff client
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

about:about gives access to various XULRunner diagnostic tools.
Useful ones include:

about:buildconfig::
    Get information about how the staff client is built.
about:config::
    Tweak XULRunner settings.
about:memory::
    Get detailed information about the memory usage of the staff
    client.


Miscellaneous
-------------

Loading Sample Data
~~~~~~~~~~~~~~~~~~~
One common need for people evaluating Evergreen, as well as for developers,
writers, and testers, is a set of sample data that can be easily loaded into
the Evergreen database and provide a consistent set of results for testing
and training purposes.

This release features sets of sample data consisting of:

* 100 bibliographic records retrievable via a "concerto" keyword search
* 100 French bibliographic records
* Associated call numbers, copies, parts, and conjoined items
* Patron accounts, including some recently expired patrons
* Circulation transactions, including some holds and some overdue items

To load the sample data into a freshly installed Evergreen database, you can
pass the following arguments to the `eg_db_config` script (either when you are
creating the initial database schema, or as a separate call after creating the
database schema):

* `--load-all-sample`: Loads all sample data, including bibliographic records,
   call numbers, copies, users, and transactions.
* `--load-concerto-sample`: Loads a subset of sample data that includes just
  100 bibliographic records, and associated call numbers and copies.