1. Upgrade notes

TODO

2. New Features

2.1. Administration

2.1.1. 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.

2.1.2. 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.

2.1.3. 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 Admin > Standing Penalties (PATRON_EXCEEDS_FINES) and Local Administration > Group Penalty Thresholds.)

2.1.4. 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 their by default.

Upgrade Note

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.

2.1.5. 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.

2.1.6. Angular Org Unit Admin Page

Migrate the Administration ⇒ Server Administration ⇒ Organizational Units page to Angular.

2.1.7. --rebuild-rmsr Option Added to pingest.pl

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:

SELECT reporter.refresh_materialized_simple_record();

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.

Upgrade Notes

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

2.1.9. 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 Admin ⇒ Server Administration ⇒ Print Templates, though the menu entry may be moved to Admin ⇒ Local Administration, once Local Admin 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

<Location /print_template>
    SetHandler perl-script
    PerlHandler OpenILS::WWW::PrintTemplate
    Options +ExecCGI
    PerlSendHeader On
    Require all granted
</Location>
  • Add to eg_startup

# 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:

sudo apt-get install libhtml-defang-perl

2.1.10. Angular Standing Penalty Admin Page

Migrate the Administration ⇒ Local Administration ⇒ Standing Penalties page to Angular.

2.2. Architecture

2.2.1. 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.

2.2.2. 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 "Basic" HTTP Authentication is provided as a reference implementation.

2.3. Cataloging

2.3.1. 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.

2.3.2. 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 params).

2.3.3. 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 attribute are allowed to fill the horizontal space.

2.3.4. New Options for Importing Copies

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

  1. 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 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.

  2. 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

2.3.5. 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 Notices 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 hold request for each unique title associated with the items that were selected when Request Items was invoked.

2.3.6. 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.

2.4. Circulation

2.4.1. 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 recently 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.

Upgrade considerations

The Booking Module Refresh requires some new dependencies for the Angular client. To install these, you will have to run the following commands:

cd $EVERGREEN_ROOT/Open-ILS/src/eg2/
npm install

2.4.2. 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.

2.4.3. 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 item.

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.

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.

2.5. Client

2.5.1. Cross-Tab Communication Demo

The Angular Sandbox now includes an example for developers interested in sharing data between staff client browser tabs.

2.5.2. Port Permission Group Admin to Angular

Migrate the Admin ⇒ Server Admin ⇒ Permission Groups admin page 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.

2.5.3. (Experimental) Angular 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

2.5.4. Experiment 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.

2.5.5. Angular 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.

2.5.6. Port Org Unit Type Admin to Angular

Migrate the Admin ⇒ Server Admin ⇒ Organization Types admin page to Angular.

2.5.7. 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

2.6. Public Catalog

2.6.1. 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.

2.6.2. 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.

2.6.3. 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."

2.7. SIP

2.7.1. 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.

2.7.2. 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.

3. Acknowledgments

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

TODO

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

TODO

We also thank the following organizations whose employees contributed patches:

TODO

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