Evergreen Documentation

Documentation Interest Group

Part I. Introduction

Chapter 1. About This Documentation

This guide was produced by the Evergreen Documentation Interest Group (DIG), consisting of numerous volunteers from many different organizations. The DIG has drawn together, edited, and supplemented pre-existing documentation contributed by libraries and consortia running Evergreen that were kind enough to release their documentation into the creative commons. Please see the Attributions section for a full list of authors and contributing organizations. Just like the software it describes, this guide is a work in progress, continually revised to meet the needs of its users, so if you find errors or omissions, please let us know, by contacting the DIG facilitators at docs@evergreen-ils.org.

This guide to Evergreen is intended to meet the needs of front-line library staff, catalogers, library administrators, system administrators, and software developers. It is organized into Parts, Chapters, and Sections addressing key aspects of the software, beginning with the topics of broadest interest to the largest groups of users and progressing to some of the more specialized and technical topics of interest to smaller numbers of users.

Copies of this guide can be accessed in PDF and HTML formats from http://docs.evergreen-ils.org/.

Chapter 2. About Evergreen

Evergreen is an open source library automation software designed to meet the needs of the very smallest to the very largest libraries and consortia. Through its staff interface, it facilitates the management, cataloging, and circulation of library materials, and through its online public access interface it helps patrons find those materials.

The Evergreen software is freely licensed under the GNU General Public License, meaning that it is free to download, use, view, modify, and share. It has an active development and user community, as well as several companies offering migration, support, hosting, and development services.

The community’s development requirements state that Evergreen must be:

Stable, even under extreme load.

Robust, and capable of handling a high volume of transactions and simultaneous users.

Flexible, to accommodate the varied needs of libraries.

Secure, to protect our patrons’ privacy and data.

User-friendly, to facilitate patron and staff use of the system.

Evergreen, which first launched in 2006 now powers over 544 libraries of every type – public, academic, special, school, and even tribal and home libraries – in over a dozen countries worldwide.

Part II. Evergreen 2.12 Release Notes

Chapter 3. Evergreen 2.12.12

This release is a security release that fixes cross-site scripting (XSS) vulnerabilities in the Evergreen public catalog.

3.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/parts/record/contents.tt2

Open-ILS/src/templates/opac/parts/record/copy_counts.tt2

Open-ILS/src/templates/opac/parts/record/issues-mfhd.tt2

Note that exploiting the XSS vulnerabilities fixed in this release would require either the ability to create maliciously-constructed MARC bibliographic or holdings records or the ability to set a maliciously constructed organizational unit name.

3.2. Acknowledgements

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

Galen Charlton

Dan Scott

Chris Sharp

Chapter 4. Evergreen 2.12.11

This release contains bug fixes improving on Evergreen 2.12.10:

The MARC Editor in the Web staff client now wraps long fields.

The MARC Editor no longer allows catalogers to enter new lines into MARC subfields.

Fixes an issue in the Web staff client reports module that caused syntax errors in reports that use virtual fields and joins.

Fixes an issue that created duplicate copy data when copies or volumes with parts were transferred.

Fixes an issue with the http → https redirect on Apache 2.4.

Fixes a color contrast accessibility issue in the Web staff client and adds underlining to links in grids for added accessibility.

Adds automated regression and unit tests for the Web staff client reports module.

4.1. Acknowledgements

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

Galen Charlton

Blake Graham-Henderson

Kathy Lussier

Remington Steed

Jason Stephenson

Cesar Velez

Chapter 5. Evergreen 2.12.10

This release contains bug fixes improving on Evergreen 2.12.9:

The patron bills screen now prevents staff members from double-clicking on the Apply Payment button (which otherwise would apply two payments).

Fixes a performance bug related to patrons logging in by barcode.

5.1. Acknowledgements

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

Galen Charlton

Bill Erickson

Jason Stephenson

Dan Wells

Chapter 6. Evergreen 2.12.9

This release contains bug fixes improving on Evergreen 2.12.8:

NodeJs is now installed from source, rather than using a pre-compiled binary.

NodeJs is now at version 6.11.3, which is the most recent LTS release.

6.1. Acknowledgements

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

Jeanette Lundgren

Ben Shum

Remington Steed

Chapter 7. Evergreen 2.12.8

This release contains several bug fixes improving on Evergreen 2.12.7:

Many patron fields have been redacted from the web staff client’s patron and record holds grids, leaving patron name, username, and ID.

Fixes two bugs where patron records could fail to be saved upon editing.

The patron summary in the web staff client now correctly displays primary and secondary ID values.

Patron barcode search completion in the web staff client now allows the user to select from all of the matching patron records.

The web staff print templates for current and historical bills can now include copy barcode and title.

Fixes a bug that resulted in some catalog searches unexpectedly timing out.

Fixes a bug where placing a hold request in the public catalog could result in "forgetting" the type and library of the user’s previous search.

Fixes a bug that made using the volume/copy editor to change a copy’s price problematic.

The administration interface for hard due dates now ensures that new (or edited) ceiling dates have their time component set to end of day, resolving an issue where ceiling dates would not be applied during the ceiling date itself.

Asset merging during bibliographic record merging now correctly recognizes call number prefixes and suffixes and deletes disused call number records.

The Concerto sample data set now includes data allowing for testing placing holds on monographic parts.

Fixes a bug where displaying user surveys could result in PCRUD drone starvation.

Fixes a bug where pg_restore of an Evergreen database could fail to create certain indexes on the actor.usr table.

7.1. Acknowledgements

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

Alex Cautley

Ben Shum

Bill Erickson

Cesar Velez

Chris Sharp

Galen Charlton

Jason Boyer

Jason Stephenson

Jeff Davis

Jeff Godin

Kathy Lussier

Kyle Huckins

Michele Morgan

Mike Rylander

Remington Steed

Rogan Hamby

Chapter 8. Evergreen 2.12.7

This release contains several bug fixes improving on Evergreen 2.12.6

Fixes a bug in the web staff client that prevented initials from being stored with copy notes.

Adds billing types that may have been missed by systems that were running Evergreen prior to the 1.4 release.

Fixes a web staff client bug with the CSV export option available from the Import Queue in the MARC Batch Import/Export interface.

Adds the missing copy alert field in the web client’s volume/copy editor.

Fixes a bug where the setting to require date of birth in patron registration was not being honored in the web staff client.

Fixes a bug in the web staff client patron registration form where the password wasn’t generating from the last four digits of the patron’s phone number.

Fixes an issue in the web staff client where the complete barcode did not display in some interfaces when partial barcodes were scanned.

8.1. Acknowledgements

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

Galen Charlton

Bill Erickson

Jeanette Lundgren

Kathy Lussier

Mike Rylander

Jane Sandberg

Chris Sharp

Ben Shum

Remington Steed

Cesar Velez

Chapter 9. Evergreen 2.12.6

This release contains several bug fixes improving on Evergreen 2.12.5.

Removes the option to add a title to My List from Group Formats and Editions searches where the option never worked correctly due to a bad id.

Removes deleted shelving locations from the web client’s volume/copy editor. Since there is no database constraint that prevents a copy from a deleted shelving location, if there are already copies attached to those shelving locations, the copy location selector will be blank. Evergreen admins can identify those items by running the following query:

select acp.id, acp.barcode, acpl.name
from asset.copy acp
join asset.copy_location acpl on (acpl.id = acp.location)
where not acp.deleted
and acpl.deleted
order by acp.id;

Adds the patron opt-in check in the web client whenever a patron is retrieved by barcode scan, patron search, or item circ history.

Fixes a bug where the price and acquisitions cost fields did not display their values.

Fixes a bug where a patron’s circulation history no longer moved to the lead account when merging patron accounts.

Now hides the ebook tabs in My Account for sites that have not yet enabled the Ebook API service.

Trims spaces from patron barcodes in the web client check out interface.

Makes a string in the holds validation alert translatable.

Fixes a bug that prevented the web client patron registration screen from loading when there is an opt-in action triggers, such as the email checkout receipt, t set to be a registration default.

Fixes a bug where barcode validation in the web client patron editor was using the incorrect regular expression.

Replaces an empty string in the mobile carrier dropdown menu with a Please select your mobile carrier label to improve usability and resolve a problem with translations.

Restores the ability to display a photo in the web client patron editor for accounts that have an actor.usr.photo_url.

Fixes a Firefox display issue in the web client that occurred when retrieving a bib record by TCN when the MARC Edit tab was set as the default view.

Fixes an bug where setting a patron’s default pickup location in the web client patron editor inadvertently changed the home library. It also disables any locations that are not viable pickup locations.

Fixes a bug where a misscan in a copy bucket failed silently.

9.1. Acknowledgements

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

Jason Boyer

Galen Charlton

Jeff Davis

Bill Erickson

Jason Etheridge

Blake Henderson

Skye Howard

Kathy Lussier

Terran McCanna

Jane Sandberg

Ben Shum

Cesar Velez

Chapter 10. Evergreen 2.12.5

This release contains several bug fixes improving on Evergreen 2.12.4.

Hides the Hold is Behind Circ Desk checkbox in the XUL client’s patron registration screen for those libraries that have not enabled Behind Desk Pickup support via the Library Settings Editor

Adds a missing error string that appears when marking an item damaged from an aged circulation.

Changes the hold request form so that it no longer defaults to the first SMS carrier for text notifications.

Adds a requirement for users to enter a phone/SMS number when they have enabled that notification method on the hold request form.

Changes the URL pointing to catalog images, CSS and javascript files to a full absolute URL instead of the relative URL previously used. This change fixes an issue with the Open Graph image property, which requires a full URL.

Fixes an issue where payment amounts sent to Stripe can be one cent less than the actual Evergreen payment.

Fixes an issue where the open-ils.storage OpenSRF module fails to start when using perl 5.24 or higher.

Fixes a problem in the web client where marking a transaction as claims returned or claims never checked out at the same time the patron’s record is edited would not increase the count once the patron’s record is saved.

Changes the cursor to a pointer for the record menus in the web client.

Fixes hardcoded patchs in srfsh support scripts.

Prevents a "Use of freed value in iteration" error that appeared in logs when adjusting a transaction to zero.

Prevents the temporary list page from crashing when a user adds the same title to the list more than once.

Removes duplicate rows from localized 950.data.seed-values.sql files.

Fixes the following two issues with conjoined items:

Foreign items previously did not display there was no extra copy attached to the bib record.

Conjoined items did not display unless there were two or more items in a set.

Fixes an issue in the web client where the Hold Verify prompt did not display for items in a Copy Location where the hold verify flag is enabled.

Fixes support for automatic item barcode completion in the web client check in, check out, renew, and item status interfaces.

Makes the courier code variable available for transit slips in the web client.

Fixes the ability to apply funds from the acquisitions selection list, View/Place Order, and MARC Federated Search interfaces.

10.1. Acknowledgements

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

Galen Charlton

Jeff Davis

Bill Erickson

Jason Etheridge

Kathy Lussier

Michele Morgan

Mike Rylander

Dan Scott

Chris Sharp

Ben Shum

Josh Stompro

Cesar Velez

Liam Whalen

Dan Wells

Chapter 11. Evergreen 2.12.4

11.1. Upgrade Notes

This release of Evergreen contains a fix to the Hold/Copy Ratio per Bib and Pickup Library (and Descendants) data source. Report templates using this data source will need to be re-created to improve accuracy of the data reported from this source.

This release also contains a fix to downloading large checkout histories from My Account. This feature no longer uses the action/trigger mechanism and the OPAC now generates the CSV directly. The old action/trigger code is still present in the database and should be removed at some point in the near future.

11.2. Bug Fixes

This release contains several bug fixes improving on Evergreen 2.12.3

A fix to a web client bug where adding copies through the Add Volumes and Copies menu item could fail silently.

A fix to a bug that allowed users to access some web client admin interfaces without a login.

A fix to the display of the loan duration and fine level fields in the web client Item Status Detail view.

A fix to the display of duplicate data on the bib record View Holds page when toggling between the holds and OPAC view.

A fix to a bug that prevented the web client patron registration page from loading.

Support for Org Unit Includes alert text, notice text, event text, header text, and footer text in the web client print templates.

A fix to make the web client MARC Editor’s flat text editor selection sticky.

A fix to make the Patron Search library selector sticky.

A fix to a bug in the web client that prevented the user from saving a new copy after using the MARC Edit Add Item option.

A fix to a patron registration bug that did not require the entry of a required user statistical category for stat cats that do not allow free-text entries.

The addition of the bad bacode image file in the web client.

An improvement to the MARC Batch Edit progress indicator to reduce the likelihood of system backlogs.

Downloading checkout history as a CSV from My Account has been fixed for users with a large circulation history. Previously, this would time out for patrons with more than 100 or so circulations.

A fix to syntax in the Spanish lang.dtd file that was creating an error when using the Closed Date Editor.

Improvements to CSS to silence some Mozilla extension warnings.

A fix to a failure to update targeted circulations when utilzing the recall functionality.

The addition of text wrapping in the copy details table on the bib record to prevent contents from falling off the page.

A fix to the adjust to zero option so that it can be applied correctly to multiple billings.

A fix to the "Hold/Copy Ratio per Bib and Pickup Library (and Descendants)" data source so that it will now include counts of eligible copies at locations that are not a pickup library for bib’s holds.

A fix to the XUL client Item Status → Alternate View → Holds / Transit tab so that it properly refreshes all data when switching between copies.

11.3. Acknowledgements

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

Jason Boyer

Galen Charlton

Jeff Davis

Bill Erickson

Jason Etherige

Pasi Kallinen

Angela Kilsdonk

Kathy Lussier

Michele Morgan

Mike Rylander

Jane Sandberg

Dan Scott

Ben Shum

Jason Stephenson

Josh Stompro

Cesar Velez

Dan Wells

Chapter 12. Evergreen 2.12.3

This release contains several bug fixes improving on Evergreen 2.12.2.

12.1. Web Client Bug Fixes

The web client, which is available for trial production use in libraries, received several fixes in this release:

The receipt on payment checkbox now prints a receipt at time of payment.

The Items Out count in the patron screen now includes long overdue items.

A fix was added to prevent values from a previously-edited patron from appearing in the edit form of a subsequent patron.

User notification preferences now save correctly in the patron registration and edit forms.

The UPDATE_MARC permission is no longer requested when performing a search from the staff catalog.

Non-cataloged circulations now display in the Items Out screen without requiring a refresh.

Required statistical categories are now required to be entered in the copy editor. (A similar bug for the patron editor was fixed in the 2.12.1 release).

Voiding bills now requires confirmation.

Staff can no longer use the copy editor to put items into or out of the following statuses: checked out, lost, in transit, on holds shelf, long overdue, and canceled transit.

The contrast is improved for alert text showing the amount a patron owes in bills.

Circ modifiers now sort alphabetically in the copy editor.

12.2. Other Bug Fixes

Code to prevent a hold already on the Holds Shelf from being transferred to another title.

A fix to a bug that prevented users from scheduling reports with a relative month if the report template used a date that applied the Year Month transform with the On or After (>=) operator.

A fix to a bug where the max fines threshold was reached prematurely due to the presence of account adjustments.

A check that prevents a SMS message from attempting to sending when the SMS carrier is null.

For systems that provide search format as a filter on the advanced search page, a fix so that the format selected in the search bar when launching a new search from the results page overrides any previously-set formats.

The addition of an optional new Apache/mod_perl configuration variable for defining the port Apache listens on for HTTP traffic. This resolves an issue where added content lookups attempting HTTP requests on the local Apache instance on port 80 failed because Apache was using non-standard ports.

A fix to the public catalog’s My List page responsive design so that it now displays properly on mobile devices and allows users to place holds from My List.

A fix to a bug where the second (and subsequent) pages of search results in the public catalog (when group formats and editions is in effect) does not correctly generate links to hits that are not part of of a multi-bib metarecords.

12.3. Acknowledgements

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

Jason Boyer

Galen Charlton

Jeff Davis

Bill Erickson

Jason Etheridge

Kathy Lussier

Terran McCanna

Dan Scott

Chris Sharp

Ben Shum

Remington Steed

Cesar Velez

Dan Wells

Chapter 13. Evergreen 2.12.2

This release is a security release that also contains several other bug fixes improving on Evergreen 2.12.1.

13.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/parts/locale_picker.tt2

Open-ILS/src/templates/opac/parts/login/form.tt2

Open-ILS/src/templates/opac/parts/searchbar.tt2

13.2. Upgrade Notes

Administrators of Evergreen who use RTL locales and who have customized style-rtl.css.tt2 should now incorporate their customizations into style.css.tt2.

The reporter.classic_current_circ view, which is part of some extra views defined in Open-ILS/src/sql/Pg/example.reporter-extension.sql, has been fixed to not exclude loans for patrons who do not have a billing address set. Users of this view should rerun Open-ILS/src/sql/Pg/example.reporter-extension.sql during upgrade.

13.3. Hold Targeter Repairs and Improvements

A series of changes were made to the new hold targeter available in 2.12.

Make the batch targeter more resilient to a single-hold failure.

Additional batch targeter info logging.

Set OSRF_LOG_CLIENT in hold_targeter_v2.pl for log tracing

Removes the confusingly named --target-all option

The same behavior can be achieved by using --retarget-interval "0s"

Removes --skip-viable (see --soft-retarget-interval below)

13.3.1. New --next-check-interval Option

Specify how long after the current run time the targeter will retarget the currently affected holds. Applying a specific interval is useful when the retarget-interval is shorter than the time between targeter runs.

For example, if the targeter is run nightly at midnight with a --retarget-interval 36h, you would set --next-check-interval to 48hr, since the holds won’t be processed again until 48 hours later. This ensures that the org unit closed date checks are looking at the correct date.

This setting overrides the default behavior of calculating the next retarget time from the retarget-interval.

13.3.2. New --soft-retarget-interval Option

This is a replacement for (and rebranding of) the --skip-viable option. The new option allows for time-based soft-targeting instead simple binary on/off soft-targeting.

How soft-targeting works: * Update hold copy maps for all affected holds * Holds with viable targets (on the pull list) are otherwise left alone. * Holds without viable targets are retargeted in the usual manner.

13.4. Other Bug Fixes

A fix to remove the Chilifresh patron reviews header for Evergreen sites that do not use Chilifresh.

A fix that marks acquisitions POs as received when all line items on the PO are received or canceled.

A typo fix to the long overdue override permission that prevented staff from being able to override long overdue check ins.

A fix to use a library’s configured currency in SIP patron responses instead of always using US dollars.

A fix to SIP timeouts caused by invalid sessions

A fix that allows boolean fields to be recognized in queries to the Z39.50 server.

A fix to use the correct method during adjust to zero on negative balances.

A correction to the datatype for the Vandelay Default Record Match Set setting.

The removal of the Keep field from MARC Batch Import Item Attributes. The field was not previously implemented.

A fix to set the complete time value for grouped Action/Trigger events when an event’s state reach complete, consistent with non-grouped events.

A fix to a bug in the rollover_phone_to_print.pl script that kept failed call files from being moved.

A new index for acq.edi_message that speeds up the check for duplicate EDI messages.

A fix that ensures JSON strings are converted to UTF8, ensuring that non-ASCII data display correctly.

A fix to avoid an erroneous unsaved data popup to appear during MARC record creation.

A typo fix in the web client’s bill payment receipt template.

A correction to ebook account links on the My Account Summary page.

Improved responsive design for the ebook My Account screens so that they display better on mobile devices.

A fix to a bug that prevented a patron opt-in dialog from loading.

The RTL stylesheet for the public catalog, templates/opac/css/style-rtl.css.tt2, has been merged into the LTR one (templates/opac/css/style.css.tt2). The combined stylesheet template will emit RTL or LTR styles based on the value of the rtl flag of the active locale. An rtl variable is also available in the template to allow the correct style to be chosen.

A fix to leaking of the internal port number to the client when Apache is configured to use nonstandard ports in combination with a proxy server.

The addition of the vandelay.auto_overlay_bib_record upgrade script, which was missed in a 2.1-2.2 era upgrade script. It isn’t necessary for sites that began using Evergreen since then to run the script, but it is harmless to run.

A web staff client fix that will hid the behind-desk option for for libraries that do not support "Behind Desk Pickup".

A web staff client fix that caused hold transit check ins to fail silently when the transit destination does not have a holds address.

A web staff client fix that now requires the entry of user statistical categories in the patron editor if those stat cats are configured to be required.

A fix to a problem with the "Exclude Electronic Resources" checkbox that prevented users from removing a selection from the box.

The removal of the search format limiters from the new advanced search limiter block on the search results page. The search format limiters should not display there because they can be selected from the search bar.

13.5. Acknowledgements

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

Galen Charlton

Jeff Davis

Bill Erickson

Jason Etheridge

Jeff Godin

Blake Henderson

Linda Jansova

Kathy Lussier

Jillianne Presley

Jane Sandberg

Dan Scott

Chris Sharp

Remington Steed

Jason Stephenson

Josh Stompro

Remington Steed

Chapter 14. Evergreen 2.12.1

This release contains several bug fixes improving on Evergreen 2.12.0

A fix to the 2.12 upgrade of the subject|temporal and subject|geographic indexes, where the above-mentioned browse indexes were not turned off in favor of new browse versions of the indexes. Sites that are upgrading from 2.12.0 can cancel the browse reingest that comes with the new upgrade script.

A change to the default pickup library when staff place a hold. The place hold screen will now default to the preferred pickup location for the patron. If the patron does not have a preferred pickup location, it will default to the patron’s home library.

A fix to a problem where users could not change the selected Org Unit on the MARC Tag Tables server admin page.

A fix to the seed data for translations for some Coded Value Map entries.

The ability to skip the XUL staff client build when in make_release.

Revised layout and styling for the advanced search limiter block that displays on the search results page.

A fix that silences a log warning that appears for every checkout where a hard due date is not used.

Tweaks for sounds that are used in the web staff client.

The addition of f4 and ctrl-f2 as hotkeys in the web staff client.

Additional help text for receipt templates in the web staff client.

The reinstatement of the Reprint Last Receipt functionality in the web staff client.

The ability in the web staff client copy editor to add new volumes to libraries that were not selected in holdings view.

A fix to a billing issue where transactions were not re-opened after they acquired a non-zero balance at check in.

A change to the web staff client work log to prevent it from storing unnecessary data.

A fix to a translation issue for the record attributes displayed in the advanced search limiter block on the search results page.

A fix to hold targeting for metarecord holds when the new hold targeter is run in parallel mode.

14.1. Acknowledgements

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

Eva Cerniňáková

Galen Charlton

Bill Erickson

Jason Etherige

Jeanette Lundgren

Kathy Lussier

Mike Rylander

Jane Sandberg

Dan Scott

Ben Shum

Robert Soulliere

Jason Stephenson

Josh Stompro

Dan Wells

Chapter 15. 2.12.0 Upgrade notes

Evergreen 2.12 now requires OpenSRF 2.5 or later; certain functionality will not work if you attempt to run Evergreen 2.12 on OpenSRF 2.4. Evergreen 2.12 recommends PostgreSQL 9.4. The minimum supported version of PostgreSQL is 9.3.

The stock schema upgrade script performs a browse and facet reingest, recalculates bib fingerprints, and remaps metarecords.

This version also adds two new services, open-ils.ebook_api and open-ils.hold-targeter.

Chapter 16. 2.12.0 New Features

16.1. Acquisitions

16.1.1. Default status for received line items

A new Library Setting has been added to allow libraries to set the default status for received line items. The previous behavior was to use the "In process" status for all acquisitions items that are received.

16.2. Administration

16.2.1. Additional SMS Carriers

SMS carrier definitions are now included for Google Fi and Republic Wireless. These will be automatically loaded when installing a new Evergreen system; admins who wish to add these definitions during an upgrade can use the following email gateway values:

Google Fi: $number@msg.fi.google.com

Republic Wireless: $number@text.republicwireless.com

16.2.2. Bibliographic Fingerprint Improvements

The bibliographic fingerprint will now incorporate subfields $n and $p from MARC title fields to better distinguish among records of the same series that may share the same title but have a different part. With this change, these MARC records will no longer be grouped together in a Group Formats & Editions search.

The bibliographic fingerprint was also changed to better distinguish among the fields contributing to the fingerprint. This change will help the system distinguish between a record for the movie Blue Steel and another record for the book Blue written by Danielle Steel.

16.2.3. Batch Hold Targeter Speed-up and New Features

Adds a new open-ils.hold-targeter service, supporting new targeting options and runtime optimizations to speed up targeting. The service is launched from a new targeting script, hold_targeter_v2.pl (default location: /openils/bin/hold_targeter_v2.pl).

This code has no effect on the existing hold targeter, which is still available as of this release and functions as before.

16.2.3.1. New Features/Options

Adds a global configuration flag circ.holds.retarget_interval for setting the hold retarget interval.

--target-all option forces the targeter to process all active holds, regardless of when they were last targeted.

--retarget-interval option make is possible to override the new circ.holds.retarget_interval setting via the command line when calling the hold targeter.

--skip-viable option causes the hold targeter to avoid modifying the currently targeted copy (i.e. the copy on the pull list) for holds that target a viable (capturable) copy. For skipped holds, no entry is added to the unfulfilled_hold_list. The set of potential copies (hold copy maps) are refreshed for all processed holds, regardless of target viability. This option is useful for 1.) finding targets for holds that require new targets and 2.) adding new/modified copies to the potential copy lists (for opportunistic capture) more frequently than you may want to do full retargeting of all holds.

--newest-first option processes holds in reverse order of request_time, so that newer holds are (re)targeted first. This is primarily useful when a large backlog of old, un-targetable holds exist. With --newest-first, the older holds will be processed last.

--parallel option overrides the parallel settings found in opensrf.xml for simpler modification and testing.

--lockfile option allows the caller to specify a lock file instead of using the default /tmp/hold_targeter-LOCK

--verbose option prints progress info to STDOUT, showing the number of holds processed per parallel targeter instance.

When configured, hold target loops cycle through all org units (with targetable copies) instead of repeatedly targeting copies at the pickup library when multiple targetable copies exist at the pickup library.

When configured, hold target loops prioritize (targetable) org units first by the number of previous target attempts, then by their weight/proximity. This effectively back-fills org units that had no targetable copies during earlier target loops so that they are targeted as many times as other org units (to the extent possible, anyway).

16.2.3.2. Examples

Traditional daily hold targeter with a value set for circ.holds.retarget_interval.

/openils/bin/hold_targeter_v2.pl

(Re)target non-viable holds twice a day, only processing holds that have never been targeter or those that have not been re-targeted in the last 12 hours.

/openils/bin/hold_targeter_v2.pl --skip-viable --retarget-interval "12h"

(Re)target non-viable holds twice a day, processing all holds regardless of when or if they were targeted before, running 3 targeters in parallel.

/openils/bin/hold_targeter_v2.pl --skip-viable --target-all --parallel 3

16.2.4. Add separate make target for translators

For those only interested in building Evergreen translations, a separate "translator" make target has been added to allow for easier installation of i18n prerequisites.

16.2.5. Allow admin to specify where Perl modules will be installed

Add --with-perlbase option to configure to specify an alternative location for installing the Perl modules. This can be useful for setups that want to run the Perl modules from a shared filesystem or environments that need to run multiple versions of Evergreen simultaneously.

Users of --with-perlbase are responsible for ensuring that PERL5LIB is set appropriately.

16.2.6. Addition of missing permissions

Required permissions that were previously missing from the stock data have now been added. If Evergreen sites have already manually added these permissions, the upgrade script will remove the old permission and create the new one, maintaining any maps to permission groups, with the stock permission ID.

16.2.7. get_org_unit_ancestor_at_depth Helper Added to Action Trigger Reactor Helpers

In action trigger templates it’s now possible to call helpers.get_org_unit_ancestor_at_depth($id_or_aou, $depth) in order to retrieve a fleshed aou for the target aou’s ancestor at the chosen depth. This could be used to retrieve the name of the library system rather than a specific branch name, for instance.

16.2.8. Removed unused selfcheck password setting

There was an unused duplicate selfcheck password setting that was removed to avoid confusion over which library setting was supposed to be set to enable passwords for selfcheck. After upgrading, verify that your library policy remains consistent for this setting.

16.2.9. Credit Processor Stripe Settings Permissions

Unprivileged users can retrieve organizational unit setting values for setting types lacking a "view" permission. When the feature adding Stripe credit card processing was added, the upgrade script neglected to add the VIEW_CREDIT_CARD_PROCESSING permission to the organizational unit setting type. This means that anyone can retrieve and view the settings for Stripe credit card processing.

Any system that upgraded from Evergreen version 2.5 to 2.6 is affected. If you use Stripe for credit card processing, it is strongly recommended that you apply this upgrade. Even if you do not use Stripe, applying this upgrade is still recommended. If you did not upgrade from version 2.5 to 2.6 of Evergreen, but started with a later version, applying this upgrade is harmless.

16.3. Cataloging

16.3.1. New Access Points for MARC Merge/Overlay Profiles

Catalogers can now select a MARC merge/overlay profile to apply when merging records in the (browser client) record bucket merge and Z39.50 record overlay interfaces. In both interfaces, if the user selects a merge profile, the results of the merge are displayed, giving the user the opportunity to choose a different merge profile or edit the records involved prior to committing to the merge.

A new library setting, "Default Merge Profile (Z39.50 and Record Buckets)", specifies the merge profile to preselect in the new merge profile selectors in the record bucket merge and Z39.50 overlay logs. The selectors will also remember the last selection that the user made.

16.4. Circulation

16.4.1. Display Copy Alerts With In-House-Use

Two library settings are used to control the display of copy alert messages or copy location check in alerts when recording in-house-use in Evergreen.

Setting Display copy alert for in-house-use to true for an organization will cause an alert to appear with the copy’s alert message, if it has one, when recording in-house-use for the copy.

Setting Display copy location check in alert for in-house-use to true for an organization will cause an alert to display a message indicating that the item needs to be routed to its location if the location has check in alert set to true.

The settings are independent of one another because you may want to display one and not the other when recording in-house-use.

16.5. Client

16.5.1. Active Date Column Picker Option

The active date will now be available as a column picker option in the Item Status screen.

16.5.2. Punctuation Insensitive Patron Search

When performing a patron search, punctuation characters will be ignored. So if the patron is named O’Brien, then you can enter Obrien, O’Brien, O Brien, etc. in the search box.

This behavior affects the Last Name (internally: family_name), First Name (first_given_name), and Middle Name (second_given_name) fields of the search.

16.5.3. Touch screen improvements for Evergreen self-check interface

Improvements were made to the Evergreen self-check interface to make it easier to use in a touch-screen environment.

The pay fines link is now a pay fines button, matching other buttons on the page.

The checkboxes have been enlarged, making them easier to activate when using a touch screen.

16.5.4. Trial Production Use of the Web Staff Client

The new web staff client is ready for trial production use in all functional areas with the exception of serials and offline transactions. In addition to many bug fixes in the areas of circulation, cataloging, administration and reporting, Release 2.12 sees the following additions to web client functionality.

Acquisitions interfaces and functionality have been integrated into the web staff client.

Booking interfaces and functionality have been integrated into the web staff client.

Hatch, the program that will allow for unmediated printing to multiple printers, sharing of workstation settings, and, eventually, offline transactions is now available. A windows installer for Hatch will be available on the Evergreen-ILS Downloads page.

The Evergreen developers will keep pilot libraries updated about known web client issues by posting known bugs to https://wiki.evergreen-ils.org/doku.php?id=dev:browser_staff:known_issues .

16.5.4.1. About Hatch

Hatch is not required to use the web client, but should be used for workstations that need to perform the following tasks.

Unmediated printing to multiple printers. Workstations can print to multiple printers without Hatch, but will need to click through a dialog to select a printer. Hatch allows workstations to automatically print, without dialog, to different printers.

Storage of workstation settings in a place outside the browser. Storing local preferences in hatch will prevent tampering with preferences via the browser developer tools and protect the settings from possible deletion if the browser deletes settings in local storage.

When offline functionality is available, hatch will be required to perform offline transactions.

Hatch is currently run as a Chrome extension and is not available in Firefox. To use hatch on Windows, Evergreen sites should:

install a java runtime environment version 8 (or higher) if not already installed,

download and execute the installer from the Evergreen downloads page,

open Chrome and navigate to chrome://extensions,

enable Developer Mode along the top right of the page,

click the Load Unpacked Extension button,

load the directory at Hatch → extension → app,

In Windows, the default location for the app directory will be C:\Program Files (x86)\Hatch\extension\app

enable hatch features in the web client by going to Administration → Workstation Administration → Print/Storage Service ("Hatch") and choosing which services to use with Hatch.

this page will also inform you that hatch is connected.

16.6. Infrastructure

16.6.1. Client Timezone Awareness

Previously, adjusting the time zone in which a database session operates could not be done in any way except globally, directly within the database. However, allowing modification of the timezone parameter now supports localization efforts for those consortia that span multiple time zones.

16.6.1.1. Implementation

CStore and other services that interact with the primary Evergreen database make use of the functionality provided by LP#1485371 in OpenSRF in order to set the time zone configuration parameter available in PostgreSQL.  This has the effect of interpreting all timestamps written to or read from the database in the client’s time zone.

Within CStore (and related, C-based services), all stateful sessions make use of this capability, setting the database time zone upon a successful CONNECT message from the client.  The time zone is reset to the database default when a session is terminated either due to client DISCONNECT or server keepalive timeout.

All stateless requests record the current database time zone, set the database time zone to that of the client’s, run the query, and then reset the database time zone on each request that carries a client time zone value.  It is expected that this will not cause any noticeable increase in latency or query execution time, as this setting is local to the specific PostgreSQL server backend process.

Within the Storage service, the timezone will be set automatically by a simple wrapper method used by the existing method registration mechanism for method publishing.  Disconnect and error callbacks are registered to revert the time zone setting within the database.  This provides completely transparent time zone manipulation for backend services that make use of open-ils.storage.

16.7. Public Catalog

16.7.1. New Subject Browse Index Definitions

New subject browse index definitions have been added that display the entire heading as a unit with hyphens between terms instead of displaying individual terms separately.

For example, the browse heading for:

=650 \0$aCats$zUnited States$vCorrespondence.

will display in a single entry as:

Cats — United States — Correspondence

Rather than separate entries for Cats and United States.

Name subjects will continue to display as separate entries because additional work would be required for the heading to be punctuated correctly.

16.7.2. Advanced Search Limiters Enhancement

Advanced search limiters will no longer propagate to the basic search box in the catalog. Instead, the limiters applied to the search will appear underneath the search box where they can be easily cleared by clicking an x. On a small, mobile device, the advanced search limiters can be seen by clicking an x filter applied link.

The selected limiters will be applied to any search from the search bar until: * The user actively removes the filters from the search or * The user starts a new basic or advanced search from scratch.

16.7.3. Arabic and Right-to-Left Language Support for the catalog

New stylesheets and other changes to the catalog to allow for better support of right-to-left (RTL) languages, such as Arabic.

Also adds Arabic (Jordan) as a new supported language.

16.7.4. Ebook API integration

Evergreen 2.12 supports partial integration with third-party APIs provided by OverDrive and OneClickdigital. When ebook API integration is enabled, bibliographic records from these vendors that appear in your public catalog will include vendor holdings and availability information. Also, when a user is logged in, the public catalog dashboard and My Account interface will include information about that user’s checkouts and holds for supported vendors.

For API integration to work, you need to request API access from the vendor and configure your Evergreen system according to the instructions below. You also need to configure the new open-ils.ebook_api service.

This feature assumes that you are importing MARC records supplied by the vendor into your Evergreen system, using Vandelay or some other MARC import method. This feature does not search the vendor’s online collections or automatically import vendor records into your system; it merely augments records that are already in Evergreen.

A future Evergreen release will add the ability for users to check out titles, place holds, etc., directly via the public catalog.

16.7.4.1. Ebook API service configuration

This feature uses the new open-ils.ebook_api OpenSRF service. This service must be configured in your opensrf.xml and opensrf_core.xml config files for ebook API integration to work. See opensrf.xml.example and opensrf_core.xml.example for guidance.

16.7.4.2. OverDrive API integration

Before enabling OverDrive API integration, you will need to request API access from OverDrive. OverDrive will provide the values to be used for the following new org unit settings:

OverDrive Basic Token: The basic token used for API client authentication. To generate your basic token, combine your client key and client secret provided by OverDrive into a single string ("key:secret"), and then base64-encode that string. On Linux, you can use the following command: echo -n "key:secret" | base64 -

OverDrive Account ID: The account ID (a.k.a. library ID) for your OverDrive API account.

OverDrive Website ID: The website ID for your OverDrive API account.

OverDrive Authorization Name: The authorization name (a.k.a. library name) designated by OverDrive for your library. If your OverDrive subscription includes multiple Evergreen libraries, you will need to add a separate value for this setting for each participating library.

OverDrive Password Required: If your library’s OverDrive subscription requires the patron’s PIN (password) to be provided during patron authentication, set this setting to "true." If you do not require the patron’s PIN for OverDrive authentication, set this setting to "false." (If set to "true," the password entered by a patron when logging into the public catalog will be cached in plain text in memcached.)

OverDrive Discovery API Base URI and OverDrive Circulation API Base URI: By default, Evergreen uses OverDrive’s production API, so you should not need to set a value for these settings. If you want to use OverDrive’s integration environment, you will need to add the appropriate base URIs for the discovery and circulation APIs. See OverDrive’s developer documentation for details.

OverDrive Granted Authorization Redirect URI: Evergreen does not currently support granted authorization with OverDrive, so this setting is not currently in use.

For more information, consult the OverDrive API documentation.

To enable OverDrive API integration, adjust the following public catalog settings in config.tt2:

ebook_api.enabled: set to "true".

ebook_api.overdrive.enabled: set to "true".

ebook_api.overdrive.base_uris: list of regular expressions matching OverDrive URLs found in the 856$9 field of older OverDrive MARC records. As of fall 2016, OverDrive’s URL format has changed, and the record identifier is now found in the 037$a field of their MARC records, with "OverDrive" in 037$b. Evergreen will check the 037 field for OverDrive record identifiers; if your system includes older-style OverDrive records with the record identifier embedded in the 856 URL, you need to specify URL patterns with this setting.

16.7.4.3. OneClickdigital API integration

Before enabling OneClickdigital API integration, you will need to request API access from OneClickdigital. OneClickdigital will provide the values to be used for the following new org unit settings:

OneClickdigital Library ID: The identifier assigned to your library by OneClickdigital.

OneClickdigital Basic Token: Your client authentication token, supplied by OneClickdigital when you request access to their API.

For more information, consult the OneClickdigital API documentation.

To enable OneClickdigital API integration, adjust the following public catalog settings in config.tt2:

ebook_api.enabled: set to "true".

ebook_api.oneclickdigital.enabled: set to "true".

ebook_api.oneclickdigital.base_uris: list of regular expressions matching OneClickdigital URLs found in the 859$9 field of your MARC records. Evergreen uses the patterns specified here to extract record identifiers for OneClickdigital titles.

16.7.4.4. Additional configuration

Evergreen communicates with third-party vendor APIs using the new OpenILS::Utils::HTTPClient module. This module is configured using settings in opensrf.xml. The default settings should work for most environments by default, but you may need to specify a custom location for the CA certificates installed on your server. You can also disable SSL certificate verification on HTTPClient requests altogether, but doing so is emphatically discouraged.

16.7.5. Links to Other Formats and Editions

The record summary pages in the catalog will now link to other formats and editions of a title. The links will allow users to quickly jump to another format of the title or an edition written in another language.

16.7.6. Metarecord Search Improvements

This release brings several improvement to the Group Formats and Editions search.

Limiters on the advanced search page can now be successfully applied to Group Formats and Editions searches,

Electronic resources are now retrievable through these searches,

Paged navigation has improved.

16.7.7. Allow Metarecord Search by default

Before the TPAC, a site could configure the public catalog to use metarecord searching by default, via a configuration file. Here we bring that back.

A new setting called search.metarecord_default is present in templates/opac/parts/config.tt2 to enable this feature. By setting this to a true value (normally 1) the TPAC will silently include the #metabib search modifier in the search form on any interfaces that do not have a UI component that allows the user to control the setting.

16.7.8. RDA Improvements

Author fields are now normalized to strip ending periods so that authors from RDA and non-RDA records are collapsed in browse and facet headings.

All author/contributor roles will now display in the record detail page. Previously, some of the roles were omitted or were duplicated.

16.7.9. Obalkyknih.cz Integration

Evergreen now integrates with Czech added content provider obalkyknih.cz. A new setting called obalkyknih_cz.enabled is available in templates/opac/parts/config.tt2 to enable this new feature.

Chapter 17. 2.12.0 Acknowledgments

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

Bibliomation

British Columbia Libraries Cooperative

C/W MARS

Georgia PINES

King County Library System

Linn Libraries Consortium

MassLNC

Pennsylvania Integrated Library System

Pioneer Library System

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

Adam Bowling

Anahi Valdez

Ben Shum

Bill Erickson

Billy Horn

Blake Henderson

Bob Wicksall

Chris Sharp

Christine Burns

Christine Morgan

Clare Sobotka

Dan Pearl

Dan Scott

Dan Wells

Darrell Rodgers

Debbie Luchenbill

Eva Cerninakova

Fares Othman

Galen Charlton

Jakub Kotrla

Jane Sandberg

Jason Boyer

Jason Etheridge

Jason Stephenson

Jeanette Lundgren

Jeff Davis

Jeff Godin

Jennifer Pringle

Jillianne Presley

Jim Keenan

Job Diógenes Ribeiro Borges

Jonathan Schatz

Josh Stompro

Kate Butler

Kathy Lussier

Kyle Huckins

Linda Jansová

Michele Morgan

Michelle Purcell

Mike Rylander

Nawras Othman

Remington Steed

Rogan Hamby

Terran McCanna

Thomas Berezansky

Victoria Lewis

We also thank the following organizations whose employees contributed patches:

British Columbia Libraries Cooperative

Calvin College

Catalyst DevWorks

C/W MARS

Emerald Data Networks, Inc.

Equinox Open Library Initiative

Georgia PINES

Indiana State Library

The Institute for the Study of Totalitarian Regimes, Prague

Jabok Library

Jordanian Library and Information Association

King County Library System

Lake Agassiz Regional Library

Laurentian University

Linn-Benton Community College

MassLNC

Merrimack Valley Library Consortium

MOBIUS Consortium

North of Boston Library Exchange

Pioneer Library System

Rodgers Memorial Library

Sigio

Traverse Area District Library

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

Part III. Software Installation

Chapter 18. Introduction

This part will guide you through the installation steps installation or upgrading your Evergreen system. It is intended for system administrators.

Chapter 19. System Requirements

19.1. Server Minimum Requirements

The following are the base requirements setting Evergreen up on a test server:

An available desktop, server or virtual image

4GB RAM, or more if your server also runs a graphical desktop

Linux Operating System (community supports Debian, Ubuntu, or Fedora)

Ports 80 and 443 should be opened in your firewall for TCP connections to allow OPAC and staff client connections to the Evergreen server.

19.2. Web Client Requirements

The current stable release of Firefox or Chrome is required to run the web client in a browser.

19.3. Staff Client Requirements

Staff terminals connect to the central database using the Evergreen staff client, available for download from The Evergreen download page. The staff client must be installed on each staff workstation and requires at minimum:

Windows, Mac OS X, or Linux operating system

a reliable high speed Internet connection

2GB RAM

The staff client uses the TCP protocol on ports 80 and 443 to communicate with the Evergreen server.

Barcode Scanners

Evergreen will work with virtually any barcode scanner – if it worked with your legacy system it should work on Evergreen.

Printers

Evergreen can use any printer configured for your terminal to print receipts, check-out slips, holds lists, etc. The single exception is spine label printing, which is still under development. Evergreen currently formats spine labels for output to a label roll printer. If you do not have a roll printer manual formatting may be required.

Chapter 20. Installing the Evergreen server

20.1. Preamble: referenced user accounts

In subsequent sections, we will refer to a number of different accounts, as follows:

Linux user accounts:

The user Linux account is the account that you use to log onto the Linux system as a regular user.

The root Linux account is an account that has system administrator privileges. On Debian you can switch to this account from your user account by issuing the su - command and entering the password for the root account when prompted. On Ubuntu you can switch to this account from your user account using the sudo su - command and entering the password for your user account when prompted.

The opensrf Linux account is an account that you create when installing OpenSRF. You can switch to this account from the root account by issuing the su - opensrf command.

The postgres Linux account is created automatically when you install the PostgreSQL database server. You can switch to this account from the root account by issuing the su - postgres command.

PostgreSQL user accounts:

The evergreen PostgreSQL account is a superuser account that you will create to connect to the PostgreSQL database server.

Evergreen administrator account:

The egadmin Evergreen account is an administrator account for Evergreen that you will use to test connectivity and configure your Evergreen instance.

20.2. Preamble: developer instructions

Skip this section if you are using an official release tarball downloaded from http://evergreen-ils.org/egdownloads

Developers working directly with the source code from the Git repository, rather than an official release tarball, must perform one step before they can proceed with the ./configure step.

As the user Linux account, issue the following command in the Evergreen source directory to generate the configure script and Makefiles:

autoreconf -i

20.3. Installing prerequisites

PostgreSQL: Version 9.4 is recommended. The minimum supported version is 9.3.

Linux: Evergreen 2.12 has been tested on Debian Jessie (8.0), Debian Wheezy (7.0), Ubuntu Xenial Xerus (16.04), and Ubuntu Trusty Tahr (14.04). If you are running an older version of these distributions, you may want to upgrade before upgrading Evergreen. For instructions on upgrading these distributions, visit the Debian or Ubuntu websites.

OpenSRF: The minimum supported version of OpenSRF is 2.5.0.

Evergreen has a number of prerequisite packages that must be installed before you can successfully configure, compile, and install Evergreen.

Begin by installing the most recent version of OpenSRF (2.5.0 or later). You can download OpenSRF releases from http://evergreen-ils.org/opensrf-downloads/

On some distributions, it is necessary to install PostgreSQL 9.4+ from external repositories.

Debian (Wheezy) and Ubuntu (Trusty) comes with older versions of PostgreSQL, so steps are taken to automatically utilize the PostgreSQL community’s apt sources. (For complete details, see: https://wiki.postgresql.org/wiki/Apt)

Debian (Jessie) and Ubuntu (Xenial) comes with PostgreSQL 9.4+, so no additional steps are required.

Issue the following commands as the root Linux account to install prerequisites using the Makefile.install prerequisite installer, substituting debian-jessie, debian-wheezy, ubuntu-xenial, or ubuntu-trusty for <osname> below:

make -f Open-ILS/src/extras/Makefile.install <osname>

Add the libdbi-libdbd libraries to the system dynamic library path by issuing the following commands as the root Linux account:

You should skip this step if installing on Ubuntu Trusty, Ubuntu Xenial or Debian Jessie. The Ubuntu and Debian Jessie targets use libdbd-pgsql from packages.

Debian Wheezy. 

echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
ldconfig

OPTIONAL: Developer additions

To perform certain developer tasks from a Git source code checkout, additional packages may be required. As the root Linux account:

To install packages needed for retrieving and managing web dependencies, use the <osname>-developer Makefile.install target. Currently, this is only needed for building and installing the (preview) browser staff client.

make -f Open-ILS/src/extras/Makefile.install <osname>-developer

To install packages required for building Evergreen translations, use the <osname>-translator Makefile.install target.

make -f Open-ILS/src/extras/Makefile.install <osname>-translator

To install packages required for building Evergreen release bundles, use the <osname>-packager Makefile.install target.

make -f Open-ILS/src/extras/Makefile.install <osname>-packager

20.4. Optional: Extra steps for web staff client

Skip this entire section if you are using an official release tarball downloaded from http://evergreen-ils.org/downloads

20.4.1. Install dependencies for web staff client

You may skip this section if you are installing on either Debian Jessie, Ubuntu Trusty, or Ubuntu Xenial and you have installed the previously described Optional: Developer Additions. You will still need to do the following steps in Install files for web staff client.

Install the long-term stability (LTS) release of Node.js. Add the Node.js /bin directory to your environment variable PATH.

Install Grunt CLI

% sudo npm install -g grunt-cli

Install Bower

% sudo npm install -g bower

20.4.2. Install files for web staff client

Building, Testing, Minification: The remaining steps all take place within the staff JS web root:

cd $EVERGREEN_ROOT/Open-ILS/web/js/ui/default/staff/

Install Project-local Dependencies. npm inspects the package.json file for dependencies and fetches them from the Node package network.

npm install   # fetch Grunt dependencies
bower install # fetch JS dependencies

Run the build script.

# build, run tests, concat+minify
grunt all

20.5. Configuration and compilation instructions

For the time being, we are still installing everything in the /openils/ directory. From the Evergreen source directory, issue the following commands as the user Linux account to configure and build Evergreen:

PATH=/openils/bin:$PATH ./configure --prefix=/openils --sysconfdir=/openils/conf
make

These instructions assume that you have also installed OpenSRF under /openils/. If not, please adjust PATH as needed so that the Evergreen configure script can find osrf_config.

20.6. Installation instructions

Once you have configured and compiled Evergreen, issue the following command as the root Linux account to install Evergreen, build the server portion of the staff client, and copy example configuration files to /openils/conf. Change the value of the STAFF_CLIENT_STAMP_ID variable to match the version of the staff client that you will use to connect to the Evergreen server.

make STAFF_CLIENT_STAMP_ID=rel_name install

The server portion of the staff client expects http://hostname/xul/server to resolve. Issue the following commands as the root Linux account to create a symbolic link pointing to the server subdirectory of the server portion of the staff client that we just built using the staff client ID rel_name:

cd /openils/var/web/xul
ln -sf rel_name/server server

20.7. Change ownership of the Evergreen files

All files in the /openils/ directory and subdirectories must be owned by the opensrf user. Issue the following command as the root Linux account to change the ownership on the files:

chown -R opensrf:opensrf /openils

20.8. Additional Instructions for Developers

Skip this section if you are using an official release tarball downloaded from http://evergreen-ils.org/egdownloads

Developers working directly with the source code from the Git repository, rather than an official release tarball, need to install the Dojo Toolkit set of JavaScript libraries. The appropriate version of Dojo is included in Evergreen release tarballs. Developers should install the Dojo 1.3.3 version of Dojo by issuing the following commands as the opensrf Linux account:

wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.

20.9. Configure the Apache Web server

Use the example configuration files in Open-ILS/examples/apache/ (for Apache versions below 2.4) or Open-ILS/examples/apache_24/ (for Apache versions 2.4 or greater) to configure your Web server for the Evergreen catalog, staff client, Web services, and administration interfaces. Issue the following commands as the root Linux account:

Debian Wheezy. 

cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
cp Open-ILS/examples/apache/eg_startup    /etc/apache2/
# Now set up SSL
mkdir /etc/apache2/ssl
cd /etc/apache2/ssl

Ubuntu Trusty, Ubuntu Xenial, and Debian Jessie. 

cp Open-ILS/examples/apache_24/eg_24.conf       /etc/apache2/sites-available/eg.conf
cp Open-ILS/examples/apache_24/eg_vhost_24.conf /etc/apache2/eg_vhost.conf
cp Open-ILS/examples/apache/eg_startup          /etc/apache2/
# Now set up SSL
mkdir /etc/apache2/ssl
cd /etc/apache2/ssl

The openssl command cuts a new SSL key for your Apache server. For a production server, you should purchase a signed SSL certificate, but you can just use a self-signed certificate and accept the warnings in the staff client and browser during testing and development. Create an SSL key for the Apache server by issuing the following command as the root Linux account:

openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key

As the root Linux account, edit the eg.conf file that you copied into place.

To enable access to the offline upload / execute interface from any workstation on any network, make the following change (and note that you must secure this for a production instance):

(Apache 2.2): Replace Allow from 10.0.0.0/8 with Allow from all

(Apache 2.4): Replace Require host 10.0.0.0/8 with Require all granted

Change the user for the Apache server.

(Debian and Ubuntu): As the root Linux account, edit /etc/apache2/envvars. Change export APACHE_RUN_USER=www-data to export APACHE_RUN_USER=opensrf.

As the root Linux account, configure Apache with KeepAlive settings appropriate for Evergreen. Higher values can improve the performance of a single client by allowing multiple requests to be sent over the same TCP connection, but increase the risk of using up all available Apache child processes and memory.

(Debian and Ubuntu): Edit /etc/apache2/apache2.conf.

Change KeepAliveTimeout to 1.

Change MaxKeepAliveRequests to 100.

As the root Linux account, configure the prefork module to start and keep enough Apache servers available to provide quick responses to clients without running out of memory. The following settings are a good starting point for a site that exposes the default Evergreen catalogue to the web:

Debian Wheezy (/etc/apache2/apache2.conf). 

<IfModule mpm_prefork_module>
   StartServers         15
   MinSpareServers       5
   MaxSpareServers      15
   MaxClients           75
   MaxRequestsPerChild 500
</IfModule>

Ubuntu Trusty, Ubuntu Xenial, Debian Jessie (/etc/apache2/mods-available/mpm_prefork.conf). 

<IfModule mpm_prefork_module>
   StartServers            15
   MinSpareServers          5
   MaxSpareServers         15
   MaxRequestWorkers       75
   MaxConnectionsPerChild 500
</IfModule>

(Ubuntu Trusty, Ubuntu Xenial, Debian Jessie) As the root user, enable the mpm_prefork module:

a2dismod mpm_event
a2enmod mpm_prefork

(Debian Wheezy): As the root Linux account, enable the Evergreen site:

a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
a2ensite eg.conf

(Ubuntu Trusty, Ubuntu Xenial, Debian Jessie):

a2dissite 000-default  # OPTIONAL: disable the default site (the "It Works" page)
a2ensite eg.conf

(Debian and Ubuntu): As the root Linux account, enable Apache to write to the lock directory; this is currently necessary because Apache is running as the opensrf user:

chown opensrf /var/lock/apache2

Learn more about additional Apache options in the following sections:

Apache Rewrite Tricks

Apache Access Handler Perl Module

20.10. Configure OpenSRF for the Evergreen application

There are a number of example OpenSRF configuration files in /openils/conf/ that you can use as a template for your Evergreen installation. Issue the following commands as the opensrf Linux account:

cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml

When you installed OpenSRF, you created four Jabber users on two separate domains and edited the opensrf_core.xml file accordingly. Please refer back to the OpenSRF README and, as the opensrf Linux account, edit the Evergreen version of the opensrf_core.xml file using the same Jabber users and domains as you used while installing and testing OpenSRF.

The -b flag tells the cp command to create a backup version of the destination file. The backup version of the destination file has a tilde (~) appended to the file name, so if you have forgotten the Jabber users and domains, you can retrieve the settings from the backup version of the files.

eg_db_config, described in Creating the Evergreen database, sets the database connection information in opensrf.xml for you.

20.11. Configure action triggers for the Evergreen application

Action Triggers provide hooks for the system to perform actions when a given event occurs; for example, to generate reminder or overdue notices, the checkout.due hook is processed and events are triggered for potential actions if there is no checkin time.

To enable the default set of hooks, issue the following command as the opensrf Linux account:

cp -b /openils/conf/action_trigger_filters.json.example /openils/conf/action_trigger_filters.json

For more information about configuring and using action triggers, see Notifications / Action Triggers.

20.12. Creating the Evergreen database

20.12.1. Setting up the PostgreSQL server

For production use, most libraries install the PostgreSQL database server on a dedicated machine. Therefore, by default, the Makefile.install prerequisite installer does not install the PostgreSQL 9 database server that is required by every Evergreen system. You can install the packages required by Debian or Ubuntu on the machine of your choice using the following commands as the root Linux account:

(Debian / Ubuntu) Installing PostgreSQL server packages. Each OS build target provides the postgres server installation packages required for each operating system. To install Postgres server packages, use the make target postgres-server-<OSTYPE>. Choose the most appropriate command below based on your operating system.

make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-jessie
make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-wheezy
make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-trusty
make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-xenial

For a standalone PostgreSQL server, install the following Perl modules for your distribution as the root Linux account:

(Debian Wheezy, Ubuntu Trusty, and Ubuntu Xenial). No extra modules required for these distributions.

You need to create a PostgreSQL superuser to create and access the database. Issue the following command as the postgres Linux account to create a new PostgreSQL superuser named evergreen. When prompted, enter the new user’s password:

createuser -s -P evergreen

Enabling connections to the PostgreSQL database. Your PostgreSQL database may be configured by default to prevent connections, for example, it might reject attempts to connect via TCP/IP or from other servers. To enable TCP/IP connections from localhost, check your pg_hba.conf file, found in the /etc/postgresql/ directory on Debian and Ubuntu. A simple way to enable TCP/IP connections from localhost to all databases with password authentication, which would be suitable for a test install of Evergreen on a single server, is to ensure the file contains the following entries before any "host … ident" entries:

host    all             all             ::1/128                 md5
host    all             all             127.0.0.1/32            md5

When you change the pg_hba.conf file, you will need to reload PostgreSQL to make the changes take effect. For more information on configuring connectivity to PostgreSQL, see http://www.postgresql.org/docs/devel/static/auth-pg-hba-conf.html

20.12.2. Creating the Evergreen database and schema

Once you have created the evergreen PostgreSQL account, you also need to create the database and schema, and configure your configuration files to point at the database server. Issue the following command as the root Linux account from inside the Evergreen source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname> with the appropriate values for your PostgreSQL database (where <user> and <password> are for the evergreen PostgreSQL account you just created), and replace <admin-user> and <admin-pass> with the values you want for the egadmin Evergreen administrator account:

perl Open-ILS/src/support-scripts/eg_db_config --update-config \
       --service all --create-database --create-schema --create-offline \
       --user <user> --password <password> --hostname <hostname> --port <port> \
       --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>

This creates the database and schema and configures all of the services in your /openils/conf/opensrf.xml configuration file to point to that database. It also creates the configuration files required by the Evergreen cgi-bin administration scripts, and sets the user name and password for the egadmin Evergreen administrator account to your requested values.

You can get a complete set of options for eg_db_config by passing the --help parameter.

20.12.3. Loading sample data

If you add the --load-all-sample parameter to the eg_db_config command, a set of authority and bibliographic records, call numbers, copies, staff and regular users, and transactions will be loaded into your target database. This sample dataset is commonly referred to as the concerto sample data, and can be useful for testing out Evergreen functionality and for creating problem reports that developers can easily recreate with their own copy of the concerto sample data.

20.12.4. Creating the database on a remote server

In a production instance of Evergreen, your PostgreSQL server should be installed on a dedicated server.

20.12.4.1. PostgreSQL 9.4 and later

To create the database instance on a remote database server running PostgreSQL 9.4 or later, simply use the --create-database flag on eg_db_config.

20.13. Starting Evergreen

As the root Linux account, start the memcached and ejabberd services (if they aren’t already running):

/etc/init.d/ejabberd start
/etc/init.d/memcached start

As the opensrf Linux account, start Evergreen. The -l flag in the following command is only necessary if you want to force Evergreen to treat the hostname as localhost; if you configured opensrf.xml using the real hostname of your machine as returned by perl -ENet::Domain 'print Net::Domain::hostfqdn() . "\n";', you should not use the -l flag.

osrf_control -l --start-all

If you receive the error message bash: osrf_control: command not found, then your environment variable PATH does not include the /openils/bin directory; this should have been set in the opensrf Linux account’s .bashrc configuration file. To manually set the PATH variable, edit the configuration file ~/.bashrc as the opensrf Linux account and add the following line:

export PATH=$PATH:/openils/bin

As the opensrf Linux account, generate the Web files needed by the staff client and catalogue and update the organization unit proximity (you need to do this the first time you start Evergreen, and after that each time you change the library org unit configuration. ):

autogen.sh

As the root Linux account, restart the Apache Web server:

/etc/init.d/apache2 restart

If the Apache Web server was running when you started the OpenSRF services, you might not be able to successfully log in to the OPAC or staff client until the Apache Web server is restarted.

20.14. Testing connections to Evergreen

Once you have installed and started Evergreen, test your connection to Evergreen via srfsh. As the opensrf Linux account, issue the following commands to start srfsh and try to log onto the Evergreen server using the egadmin Evergreen administrator user name and password that you set using the eg_db_config command:

/openils/bin/srfsh
srfsh% login <admin-user> <admin-pass>

You should see a result like:

Received Data: "250bf1518c7527a03249858687714376"
------------------------------------
Request Completed Successfully
Request Time in seconds: 0.045286
------------------------------------

Received Data: {
   "ilsevent":0,
   "textcode":"SUCCESS",
   "desc":" ",
   "pid":21616,
   "stacktrace":"oils_auth.c:304",
   "payload":{
      "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
      "authtime":420
   }

}

------------------------------------
Request Completed Successfully
Request Time in seconds: 1.336568
------------------------------------

If this does not work, it’s time to do some troubleshooting.

As the opensrf Linux account, run the settings-tester.pl script to see if it finds any system configuration problems. The script is found at Open-ILS/src/support-scripts/settings-tester.pl in the Evergreen source tree.

Follow the steps in the troubleshooting guide.

If you have faithfully followed the entire set of installation steps listed here, you are probably extremely close to a working system. Gather your configuration files and log files and contact the Evergreen development mailing list for assistance before making any drastic changes to your system configuration.

20.15. Getting help

Need help installing or using Evergreen? Join the mailing lists at http://evergreen-ils.org/communicate/mailing-lists/ or contact us on the Freenode IRC network on the #evergreen channel.

20.16. License

This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

Chapter 21. Upgrading the Evergreen Server

Before upgrading, it is important to carefully plan an upgrade strategy to minimize system downtime and service interruptions. All of the steps in this chapter are to be completed from the command line.

21.1. Software Prerequisites

PostgreSQL: Version 9.4 is recommended. The minimum supported version is 9.3.

Linux: Evergreen 2.12.12 has been tested on Debian Jessie (8.0), Debian Wheezy (7.0), Ubuntu Xenial Xerus (16.04), and Ubuntu Trusty Tahr (14.04). If you are running an older version of these distributions, you may want to upgrade before upgrading Evergreen. For instructions on upgrading these distributions, visit the Debian or Ubuntu websites.

OpenSRF: The minimum supported version of OpenSRF is 2.5.0.

In the following instructions, you are asked to perform certain steps as either the root or opensrf user.

Debian: To become the root user, issue the su command and enter the password of the root user.

Ubuntu: To become the root user, issue the sudo su command and enter the password of your current user.

To switch from the root user to a different user, issue the su - [user] command; for example, su - opensrf. Once you have become a non-root user, to become the root user again simply issue the exit command.

21.2. Upgrade the Evergreen code

The following steps guide you through a simplistic upgrade of a production server. You must adjust these steps to accommodate your customizations such as catalogue skins.

Stop Evergreen and back up your data:

As root, stop the Apache web server.

As the opensrf user, stop all Evergreen and OpenSRF services:

osrf_control --localhost --stop-all

Back up the /openils directory.

Upgrade OpenSRF. Download and install the latest version of OpenSRF from the OpenSRF download page.

As the opensrf user, download and extract Evergreen 2.12.12:

wget https://evergreen-ils.org/downloads/Evergreen-ILS-2.12.12.tar.gz
tar xzf Evergreen-ILS-2.12.12.tar.gz

For the latest edition of Evergreen, check the Evergreen download page and adjust upgrading instructions accordingly.

As the root user, install the prerequisites:

cd /home/opensrf/Evergreen-ILS-2.12.12

On the next command, replace [distribution] with one of these values for your distribution of Debian or Ubuntu:

debian-jessie for Debian Jessie (8.0) (See Bug 134222 if you want to use EDI)

debian-wheezy for Debian Wheezy (7.0)

ubuntu-xenial for Ubuntu Xenial Xerus (16.04) (EDI compatibility in progress)

ubuntu-trusty for Ubuntu Trusty Tahr (14.04) (See Bug 134222 if you want to use EDI)

make -f Open-ILS/src/extras/Makefile.install [distribution]

As the opensrf user, configure and compile Evergreen:

cd /home/opensrf/Evergreen-ILS-2.12.12
PATH=/openils/bin:$PATH ./configure --prefix=/openils --sysconfdir=/openils/conf
make

These instructions assume that you have also installed OpenSRF under /openils/. If not, please adjust PATH as needed so that the Evergreen configure script can find osrf_config.

As the root user, install Evergreen:

cd /home/opensrf/Evergreen-ILS-2.12.12
make STAFF_CLIENT_STAMP_ID=rel_2_12_12 install

As the root user, change all files to be owned by the opensrf user and group:

chown -R opensrf:opensrf /openils

As the opensrf user, update the server symlink in /openils/var/web/xul/:

cd /openils/var/web/xul/
rm server
ln -sf rel_2_12_12/server server

As the opensrf user, update opensrf_core.xml and opensrf.xml by copying the new example files (/openils/conf/opensrf_core.xml.example and /openils/conf/opensrf.xml). The -b option creates a backup copy of the old file.

cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml

Copying these configuration files will remove any customizations you have made to them. Remember to redo your customizations after copying them.

As the opensrf user, update the configuration files:

cd /home/opensrf/Evergreen-ILS-2.12.12
perl Open-ILS/src/support-scripts/eg_db_config --update-config --service all \
--create-offline --database evergreen --host localhost --user evergreen --password evergreen

As the root user, update the Apache files:

Use the example configuration files in Open-ILS/examples/apache/ (for Apache versions below 2.4) or Open-ILS/examples/apache_24/ (for Apache versions 2.4 or greater) to configure your Web server for the Evergreen catalog, staff client, Web services, and administration interfaces. Issue the following commands as the root Linux account:

Copying these Apache configuration files will remove any customizations you have made to them. Remember to redo your customizations after copying them. For example, if you purchased an SSL certificate, you will need to edit eg.conf to point to the appropriate SSL certificate files. The diff command can be used to show the differences between the distribution version and your customized version. diff <customized file> <dist file>

Update /etc/apache2/eg_startup by copying the example from Open-ILS/examples/apache/eg_startup.

cp /home/opensrf/Evergreen-ILS-2.12.12/Open-ILS/examples/apache/eg_startup /etc/apache2/eg_startup

Update /etc/apache2/eg_vhost.conf by copying the example from Open-ILS/examples/apache/eg_vhost.conf.

cp /home/opensrf/Evergreen-ILS-2.12.12/Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/eg_vhost.conf

Update /etc/apache2/sites-available/eg.conf by copying the example from Open-ILS/examples/apache/eg.conf.

cp /home/opensrf/Evergreen-ILS-2.12.12/Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/eg.conf

21.3. Upgrade the Evergreen database schema

The upgrade of the Evergreen database schema is the lengthiest part of the upgrade process for sites with a significant amount of production data.

Before running the upgrade script against your production Evergreen database, back up your database, restore it to a test server, and run the upgrade script against the test server. This enables you to determine how long the upgrade will take and whether any local customizations present problems for the stock upgrade script that require further tailoring of the upgrade script. The backup also enables you to cleanly restore your production data if anything goes wrong during the upgrade.

Evergreen provides incremental upgrade scripts that allow you to upgrade from one minor version to the next until you have the current version of the schema. For example, if you want to upgrade from 2.5.1 to 2.12.0, you would run the following upgrade scripts:

2.5.1-2.5.2-upgrade-db.sql

2.5.2-2.5.3-upgrade-db.sql

2.5.3-2.6.0-upgrade-db.sql (this is a major version upgrade)

2.6.2-2.6.3-upgrade-db.sql

2.6.3-2.7.0-upgrade-db.sql (this is a major version upgrade)

2.7.0-2.7.1-upgrade-db.sql

2.7.1-2.7.2-upgrade-db.sql

2.7.2-2.7.3-upgrade-db.sql

2.7.3-2.7.4-upgrade-db.sql

2.7.4-2.8.0-upgrade-db.sql (this is a major version upgrade)

2.8.0-2.8.1-upgrade-db.sql

2.8.1-2.8.2-upgrade-db.sql

2.8.2-2.8.3-upgrade-db.sql

2.8.3-2.8.4-upgrade-db.sql

2.8.4-2.9.0-upgrade-db.sql (this is a major version upgrade)

2.9.0-2.9.1-upgrade-db.sql

2.9.1-2.9.2-upgrade-db.sql

2.9.2-2.9.3-upgrade-db.sql

2.9.3-2.10.0-upgrade-db.sql

2.10.0-2.10.1-upgrade-db.sql

2.10.1-2.10.2-upgrade-db.sql

2.10.2-2.10.3-upgrade-db.sql

2.10.3-2.10.4-upgrade-db.sql

2.10.4-2.10.5-upgrade-db.sql

2.10.5-2.10.6-upgrade-db.sql

2.10.6-2.10.7-upgrade-db.sql

2.10.7-2.11.0-upgrade-db.sql (this is a major version upgrade)

2.11.0-2.11.1-upgrade-db.sql

2.11.1-2.11.2-upgrade-db.sql

2.11.2-2.11.3-upgrade-db.sql

2.11.3-2.12.0-upgrade-db.sql (this is a major version upgrade)

2.12.0-2.12.1-upgrade-db.sql

2.12.1-2.12.2-upgrade-db.sql

2.12.2-2.12.3-upgrade-db.sql

2.12.3-2.12.4-upgrade-db.sql

2.12.4-2.12.5-upgrade-db.sql

2.12.5-2.12.6-upgrade-db.sql

2.12.6-2.12.7-upgrade-db.sql

2.12.7-2.12.8-upgrade-db.sql

2.12.8-2.12.9-upgrade-db.sql

2.12.9-2.12.10-upgrade-db.sql

2.12.10-2.12.11-upgrade-db.sql

2.12.11-2.12.12-upgrade-db.sql

Note that you do not want to run additional 2.5 scripts to upgrade to the newest version of 2.5, since currently there is no automated way to upgrade from 2.5.4+ to 2.6. Only upgrade as far as necessary to reach the major version upgrade script (in this example, as far as 2.5.3).

To upgrade across multiple major versions (e.g. from 2.3.0 to 2.12.12), use the same logic to utilize the provided major version upgrade scripts. For example:

2.3-2.4.0-upgrade-db.sql

2.3-2.4-supplemental.sh

(run all incremental scripts from 2.4.0 to 2.4.3)

2.4.3-2.5.0-upgrade-db.sql

(run all incremental scripts from 2.5.0 to 2.5.3)

2.5.3-2.6.0-upgrade-db.sql

(run all incremental scripts from 2.6.0 to 2.6.3)

2.6.3-2.7.0-upgrade-db.sql

(run all incremental scripts from 2.7.0 to 2.7.4)

2.7.4-2.8.0-upgrade-db.sql

(run all incremental scripts from 2.8.0 to 2.8.4)

2.8.4-2.9.0-upgrade-db.sql

(run all incremental scripts from 2.9.0 to 2.9.3)

2.9.3-2.10.0-upgrade-db.sql

(run all incremental scripts from 2.10.0 to 2.10.7)

2.10.7-2.11.0-upgrade-db.sql

(run all incremental scripts from 2.11.0 to 2.11.3)

2.11.3-2.12.0-upgrade-db.sql

(run all incremental scripts from 2.12.0 to 2.12.12)

Pay attention to error output as you run the upgrade scripts. If you encounter errors that you cannot resolve yourself through additional troubleshooting, please report the errors to the Evergreen Technical Discussion List.

Run the following steps (including other upgrade scripts, as noted above) as a user with the ability to connect to the database server.

cd /home/opensrf/Evergreen-ILS-2.12.12/Open-ILS/src/sql/Pg
psql -U evergreen -h localhost -f version-upgrade/2.12.11-2.12.12-upgrade-db.sql evergreen

After the some database upgrade scripts finish, you may see a note on how to reingest your bib records. You may run this after you have completed the entire upgrade and tested your system. Reingesting records may take a long time depending on the number of bib records in your system.

21.4. Restart Evergreen and Test

As the root user, restart memcached to clear out all old user sessions.

service memcached restart

As the opensrf user, start all Evergreen and OpenSRF services:

osrf_control --localhost --start-all

As the opensrf user, run autogen to refresh the static organizational data files:

cd /openils/bin
./autogen.sh

Start srfsh and try logging in using your Evergreen username and password:

/openils/bin/srfsh
srfsh% login username password

You should see a result like:

Received Data: "250bf1518c7527a03249858687714376"
    ------------------------------------
    Request Completed Successfully
    Request Time in seconds: 0.045286
    ------------------------------------

    Received Data: {
       "ilsevent":0,
       "textcode":"SUCCESS",
       "desc":" ",
       "pid":21616,
       "stacktrace":"oils_auth.c:304",
       "payload":{
          "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
          "authtime":420
       }

    }

    ------------------------------------
    Request Completed Successfully
    Request Time in seconds: 1.336568
    ------------------------------------

If this does not work, it’s time to do some troubleshooting.

As the root user, start the Apache web server.

If you encounter errors, refer to the troubleshooting section of this documentation for tips on finding solutions and seeking further assistance from the Evergreen community.

21.5. Review Release Notes

Review the 2.12 release notes for other tasks that need to be done after upgrading. If you have upgraded over several major versions, you will need to review the release notes for each version also.

Chapter 22. Setting Up EDI Acquisitions

22.1. Introduction

Electronic Data Interchange (EDI) is used to exchange information between participating vendors and Evergreen. This chapter contains technical information for installation and configuration of the components necessary to run EDI Acquisitions for Evergreen.

22.2. Installation

22.2.1. Install EDI Translator

The EDI Translator is used to convert data into EDI format. It runs on localhost and listens on port 9191 by default. This is controlled via the edi_webrick.cnf file located in the edi_translator directory. It should not be necessary to edit this configuration if you install EDI Translator on the same server used for running Action/Triggers events.

If you are running Evergreen with a multi-server configuration, make sure to install EDI Translator on the same server used for Action/Trigger event generation.

Steps for Installing

As the opensrf user, copy the EDI Translator code found in Open-ILS/src/edi_translator to somewhere accessible (for example, /openils/var/edi):

cp -r Open-ILS/src/edi_translator /openils/var/edi

Navigate to where you have saved the code to begin next step:

cd /openils/var/edi

Next, as the root user (or a user with sudo rights), install the dependencies, via "install.sh". This will perform some apt-get routines to install the code needed for the EDI translator to function. (Note: subversion must be installed first)

./install.sh

Now, we’re ready to start "edi_webrick.bash" which is the script that calls the "Ruby" code to translate EDI. This script needs to be started in order for EDI to function so please take appropriate measures to ensure this starts following reboots/upgrades/etc. As the opensrf user:

./edi_webrick.bash

You can check to see if EDI translator is running.

Using the command "ps aux | grep edi" should show you something similar if the script is running properly:

root    30349  0.8  0.1  52620 10824 pts/0      S       13:04   0:00 ruby ./edi_webrick.rb

To shutdown EDI Translator you can use something like pkill (assuming no other ruby processes are running on that server):

kill -INT $(pgrep ruby)

22.2.2. Install EDI Scripts

The EDI scripts are "edi_pusher.pl" and "edi_fetcher.pl" and are used to "push" and "fetch" EDI messages for configured EDI accounts.

As the opensrf user, copy edi_pusher.pl and edi_fetcher.pl from Open-ILS/src/support-scripts into /openils/bin:

cp Open-ILS/src/support-scripts/edi_pusher.pl /openils/bin
cp Open-ILS/src/support-scripts/edi_fetcher.pl /openils/bin

Setup the edi_pusher.pl and edi_fetcher.pl scripts to run as cron jobs in order to regularly push and receive EDI messages.

Add to the opensrf user’s crontab the following entries:

10 * * * * cd /openils/bin && /usr/bin/perl ./edi_pusher.pl > /dev/null
0 1 * * * cd /openils/bin && /usr/bin/perl ./edi_fetcher.pl > /dev/null

The example for edi_pusher.pl sets the script to run at 10 minutes past the hour, every hour.

The example for edi_fetcher.pl sets the script to run at 1 AM every night.

You may choose to run the EDI scripts more or less frequently based on the necessary response times from your vendors.

22.3. Configuration

22.3.1. Configuring Providers

Look in Admin > Server Administration > Acquisitions > Providers

Column
Description/Notes

Provider Name

A unique name to identify the provider

Code

A unique code to identify the provider

Owner

The org unit who will "own" the provider.

Currency

The currency format the provider accepts

Active

Whether or not the Provider is "active" for use

Default Claim Policy

??

EDI Default

The default "EDI Account" to use (see EDI Accounts Configuration)

Email

The email address for the provider

Fax Phone

A fax number for the provider

Holdings Tag

The holdings tag to be utilized (usually 852, for Evergreen)

Phone

A phone number for the provider

Prepayment Required

Whether or not prepayment is required

SAN

The vendor provided, org unit specific SAN code

URL

The vendor website

22.3.2. Configuring EDI Accounts

Look in Admin > Server Administration > Acquisitions > EDI Accounts

Column
Description/Notes

Label

A unique name to identify the provider

Host

FTP/SFTP/SSH hostname - vendor assigned

Username

FTP/SFTP/SSH username - vendor assigned

Password

FTP/SFTP/SSH password - vendor assigned

Account

Vendor assigned account number associated with your organization

Owner

The organizational unit who owns the EDI account

Last Activity

The date of last activity for the account

Provider

This is a link to one of the "codes" in the "Providers" interface

Path

The path on the vendor’s server where Evergreen will send it’s outgoing .epo files

Incoming Directory

The path on the vendor’s server where "incoming" .epo files are stored

Vendor Account Number

Vendor assigned account number.

Vendor Assigned Code

Usually a sub-account designation. Can be used with or without the Vendor Account Number.

22.3.3. Configuring Organizational Unit SAN code

Look in Admin > Server Settings > Organizational Units

This interface allows a library to configure their SAN, alongside their address, phone, etc.

22.4. Troubleshooting

22.4.1. PO JEDI Template Issues

Some libraries may run into issues with the action/trigger (PO JEDI). The template has to be modified to handle different vendor codes that may be used. For instance, if you use "ingra" instead of INGRAM this may cause a problem because they are hardcoded in the template. The following is an example of one modification that seems to work.

Original template has: 

"buyer":[
    [%   IF   target.provider.edi_default.vendcode && (target.provider.code == 'BT' || target.provider.name.match('(?i)^BAKER & TAYLOR'))  -%]
        {"id-qualifier": 91, "id":"[% target.ordering_agency.mailing_address.san _ ' ' _ target.provider.edi_default.vendcode %]"}
    [%- ELSIF target.provider.edi_default.vendcode && target.provider.code == 'INGRAM' -%]
        {"id":"[% target.ordering_agency.mailing_address.san %]"},
        {"id-qualifier": 91, "id":"[% target.provider.edi_default.vendcode %]"}
    [%- ELSE -%]
        {"id":"[% target.ordering_agency.mailing_address.san %]"}
    [%- END -%]
],

Modified template has the following where it matches on provider SAN instead of code: 

"buyer":[
    [%   IF   target.provider.edi_default.vendcode && (target.provider.san == '1556150')  -%]
        {"id-qualifier": 91, "id":"[% target.ordering_agency.mailing_address.san _ ' ' _ target.provider.edi_default.vendcode %]"}
        {"id-qualifier": 91, "id":"[% target.ordering_agency.mailing_address.san _ ' ' _ target.provider.edi_default.vendcode %]"}
    [%- ELSIF target.provider.edi_default.vendcode && (target.provider.san == '1697978')  -%]
        {"id":"[% target.ordering_agency.mailing_address.san %]"},
        {"id-qualifier": 91, "id":"[% target.provider.edi_default.vendcode %]"}
    [%- ELSE -%]
        {"id":"[% target.ordering_agency.mailing_address.san %]"}
    [%- END -%]
],

Part IV. System Configuration and Customization

Chapter 23. Introduction

The Evergreen system allows a free range of customizations to every aspect of the system. Use this part of the documentation to become familiar with the tools for configuring the system as well as customizing the catalog and staff client.

Chapter 24. Describing your organization

Your Evergreen system is almost ready to go. You’ll need to add each of the libraries that will be using your Evergreen system. If you’re doing this for a consortium, you’ll have to add your consortium as a whole, and all the libraries and branches that are members of the consortium. In this chapter, we’ll talk about how to get the Evergreen system to see all your libraries, how to set each one up, and how to edit all the details of each one.

24.1. Organization Unit Types

The term Organization Unit Types refers to levels in the hierarchy of your library system(s). Examples could include: All-Encompassing Consortium, Library System, Branch, Bookmobile, Sub-Branch, etc.

You can add or remove organizational unit types, and rename them as needed to match the organizational hierarchy that matches the libraries using your installation of Evergreen. Organizational unit types should never have proper names since they are only generic types.

When working with configuration, settings, and permissions, it is very important to be careful of the Organization Unit Context Location - this is the organizational unit to which the configuration settings are being applied. If, for example, a setting is applied at the Consortium context location, all child units will inherit that setting. If a specific branch location is selected, only that branch and its child units will have the setting applied. The levels of the hierarchy to which settings can be applied are often referred to in terms of "depth" in various configuration interfaces. In a typical hierarchy, the consortium has a depth of 0, the system is 1, the branch is 2, and any bookmobiles or sub-branches is 3.

24.1.1. Create and edit Organization Unit Types

Open Administration > Server Administration > Organization Types.

In the left panel, expand the Organization Unit Types hierarchy.

Click on a organization type to edit the existing type or to add a new organization unit.

A form opens in the right panel, displaying the data for the selected organization unit.

Edit the fields as required and click Save.

To create a new dependent organization unit, click New Child. The new child organization unit will appear in the left panel list below the parent. Highlight the new unit and edit the data as needed, click Save

24.2. Organizational Units

Organizational Units are the specific instances of the organization unit types that make up your library’s hierarchy. These will have distinctive proper names such as Main Street Branch or Townsville Campus.

24.2.1. Remove or edit default Organizational Units

After installing the Evergreen software, the default CONS, SYS1, BR1, etc., organizational units remain. These must be removed or edited to reflect actual library entities.

24.2.2. Create and edit Organizational Units

Open Administration > Server Administration > Organizational Units.

In the left panel, expand the the Organizational Units hierarchy, select a unit.

A form opens in the right panel, displaying the data for the selected organizational unit.

To edit the existing, default organizational unit, enter system or library specific data in the form; complete all three tabs: Main Settings, Hours of Operation, Addresses.

Click Save.

To create a new dependent organizational unit, click New Child. The new child will appear in the hierarchy list below the parent unit. Click on the new unit and edit the data, click Save

24.2.3. Organizational Unit data

The Addresses tab allows you to enter library contact information. Library Phone number, email address, and addresses are used in patron email notifications, hold slips, and transit slips. The Library address tab is broken out into four address types: Physical Address, Holds Address, Mailing Address, ILL Address.

The Hours of Operation tab is where you enter regular, weekly hours. Holiday and other closures are set in the Closed Dates Editor. Hours of operation and closed dates impact due dates and fine accrual.

24.2.4. After Changing Organization Unit Data

After you change Org Unit data, you must run the autogen.sh script. This script updates the Evergreen organization tree and fieldmapper IDL. You will get unpredictable results if you don’t run this after making changes.

Run this script as the opensrf Linux account.

autogen.sh

24.2.5. Set closed dates using the Closed Dates Editor

These dates are in addition to your regular weekly closed days (see the section called “Library Hours of Operation”). Both regular closed days and those entered in the Closed Dates Editor affect due dates and fines:

Due dates. Due dates that would fall on closed days are automatically pushed forward to the next open day. Likewise, if an item is checked out at 8pm, for example, and would normally be due on a day when the library closes before 8pm, Evergreen pushes the due date forward to the next open day.

Overdue fines. Overdue fines may not be charged on days when the library is closed. This fine behavior depends on how the Charge fines on overdue circulations when closed setting is configured in the Library Settings Editor.

Closed dates do not affect the processing delays for Action/Triggers. For example, if your library has a trigger event that marks items as lost after 30 days, that 30 day period will include both open and closed dates.

24.2.5.1. Adding a closure

Select Administration > Local Administration.

Select Closed Dates Editor.

Select type of closure: typically Single Day or Multiple Day.

Click the Calendar gadget to select the All Day date or starting and ending dates.

Enter a Reason for closure (optional).

Click Apply to all of my libraries if your organizational unit has children units that will also be closed.

Click Save.

Now that your organizational structure is established, you can begin configuring permissions for the staff users of your Evergreen system.

24.2.5.2. Detailed closure

If your closed dates include a portion of a business day, you should create a detailed closing.

Select Administration → Local Administration.

Select Closed Dates Editor.

Select Add Detailed Closing.

Enter applicable dates, times, and a descriptive reason for the closing.

Click Save.

Check the Apply to all of my libraries box if your library is a multi-branch system and the closing applies to all of your branches.

Chapter 25. Describing your people

Many different members of your staff will use your Evergreen system to perform the wide variety of tasks required of the library.

When the Evergreen installation was completed, a number of permission groups should have been automatically created. These permission groups are:

Users

Patrons

Staff

Catalogers

Circulators

Acquisitions

Acquisitions Administrator

Cataloging Administrator

Circulation Administrator

Local Administrator

Serials

System Administrator

Global Administrator

Data Review

Volunteers

Each of these permission groups has a different set of permissions connected to them that allow them to do different things with the Evergreen system. Some of the permissions are the same between groups; some are different. These permissions are typically tied to one or more working location (sometimes referred to as a working organizational unit or work OU) which affects where a particular user can exercise the permissions they have been granted.

25.1. Setting the staff user’s working location

To grant a working location to a staff user in the staff client:

Search for the patron. Select Search > Search for Patrons from the top menu.

When you retrieve the correct patron record, select Other > User Permission Editor from the upper right corner. The permissions associated with this account appear in the right side of the client, with the Working Location list at the top of the screen.

The Working Location list displays the Organizational Units in your consortium. Select the check box for each Organization Unit where this user needs working permissions. Clear any other check boxes for Organization Units where the user no longer requires working permissions.

Scroll all the way to the bottom of the page and click Save. This user account is now ready to be used at your library.

As you scroll down the page you will come to the Permissions list. These are the permissions that are given through the Permission Group that you assigned to this user. Depending on your own permissions, you may also have the ability to grant individual permissions directly to this user.

25.2. Comparing approaches for managing permissions

The Evergreen community uses two different approaches to deal with managing permissions for users:

Staff Client

Evergreen libraries that are most comfortable using the staff client tend to manage permissions by creating different profiles for each type of user. When you create a new user, the profile you assign to the user determines their basic set of permissions. This approach requires many permission groups that contain overlapping sets of permissions: for example, you might need to create a Student Circulator group and a Student Cataloger group. Then if a new employee needs to perform both of these roles, you need to create a third Student Cataloger / Circulator group representing the set of all of the permissions of the first two groups.

The advantage to this approach is that you can maintain the permissions entirely within the staff client; a drawback to this approach is that it can be challenging to remember to add a new permission to all of the groups. Another drawback of this approach is that the user profile is also used to determine circulation and hold rules, so the complexity of your circulation and hold rules might increase significantly.

Database Access

Evergreen libraries that are comfortable manipulating the database directly tend to manage permissions by creating permission groups that reflect discrete roles within a library. At the database level, you can make a user belong to many different permission groups, and that can simplify your permission management efforts. For example, if you create a Student Circulator group and a Student Cataloger group, and a new employee needs to perform both of these roles, you can simply assign them to both of the groups; you do not need to create an entirely new permission group in this case. An advantage of this approach is that the user profile can represent only the user’s borrowing category and requires only the basic Patrons permissions, which can simplify your circulation and hold rules.

Permissions and profiles are not carved in stone. As the system administrator, you can change them as needed. You may set and alter the permissions for each permission group in line with what your library, or possibly your consortium, defines as the appropriate needs for each function in the library.

25.3. Managing permissions in the staff client

In this section, we’ll show you in the staff client:

where to find the available permissions

where to find the existing permission groups

how to see the permissions associated with each group

how to add or remove permissions from a group

We also provide an appendix with a listing of suggested minimum permissions for some essential groups. You can compare the existing permissions with these suggested permissions and, if any are missing, you will know how to add them.

25.3.1. Where to find existing permissions and what they mean

In the staff client, in the upper right corner of the screen, click on Administration > Server Administration > Permissions.

The list of available permissions will appear on screen and you can scroll down through them to see permissions that are already available in your default installation of Evergreen.

There are over 500 permissions in the permission list. They appear in two columns: Code and Description. Code is the name of the permission as it appear in the Evergreen database. Description is a brief note on what the permission allows. All of the most common permissions have easily understandable descriptions.

25.3.2. Where to find existing Permission Groups

In the staff client, in the upper right corner of the screen, navigate to Administration > Server Administration > Permission Groups.

Two panes will open on your screen. The left pane provides a tree view of existing Permission Groups. The right pane contains two tabs: Group Configuration and Group Permissions.

In the left pane, you will find a listing of the existing Permission Groups which were installed by default. Click on the + sign next to any folder to expand the tree and see the groups underneath it. You should see the Permission Groups that were listed at the beginning of this chapter. If you do not and you need them, you will have to create them.

25.3.3. Adding or removing permissions from a Permission Group

First, we will remove a permission from the Staff group.

From the list of Permission Groups, click on Staff.

In the right pane, click on the Group Permissions tab. You will now see a list of permissions that this group has.

From the list, choose CREATE_CONTAINER. This will now be highlighted.

Click the Delete Selected button. CREATE_CONTAINER will be deleted from the list. The system will not ask for a confirmation. If you delete something by accident, you will have to add it back.

Click the Save Changes button.

You can select a group of individual items by holding down the Ctrl key and clicking on them. You can select a list of items by clicking on the first item, holding down the Shift key, and clicking on the last item in the list that you want to select.

Now, we will add the permission we just removed back to the Staff group.

From the list of Permission Groups, click on Staff.

In the right pane, click on the Group Permissions tab.

Click on the New Mapping button. The permission mapping dialog box will appear.

From the Permission drop down list, choose CREATE_CONTAINER.

From the Depth drop down list, choose Consortium.

Click the checkbox for Grantable.

Click the Add Mapping button. The new permission will now appear in the Group Permissions window.

Click the Save Changes button.

If you have saved your changes and you don’t see them, you may have to click the Reload button in the upper left side of the staff client screen.

25.4. Managing role-based permission groups in the staff client

Main permission groups are granted in the staff client through Edit in the patron record using the Main (Profile) Permission Group field. Additional permission groups can be granted using secondary permission groups.

25.4.1. Secondary Group Permissions

The Secondary Groups button functionality enables supplemental permission groups to be added to staff accounts. The CREATE_USER_GROUP_LINK and REMOVE_USER_GROUP_LINK permissions are required to display and use this feature.

In general when creating a secondary permission group do not grant the permission to login to Evergreen.

25.4.1.1. Granting Secondary Permissions Groups

Open the account of the user you wish to grant secondary permission group to.

Click Edit.

Click Secondary Groups, located to the right of the Main (Profile) Permission Group.

From the dropdown menu select one of the secondary permission groups.

Click Add.

Click Apply Changes.

Click Save in the top right hand corner of the Edit Screen to save the user’s account.

25.4.1.2. Removing Secondary Group Permissions

Open the account of the user you wish to remove the secondary permission group from.

Click Edit.

Click Secondary Groups, located to the right of the Main (Profile) Permission Group.

Click Delete beside the permission group you would like to remove.

Click Apply Changes.

Click Save in the top right hand corner of the Edit Screen to save the user’s account.

25.5. Managing role-based permission groups in the database

While the ability to assign a user to multiple permission groups has existed in Evergreen for years, a staff client interface is not currently available to facilitate the work of the Evergreen administrator. However, if you or members of your team are comfortable working directly with the Evergreen database, you can use this approach to separate the borrowing profile of your users from the permissions that you grant to staff, while minimizing the amount of overlapping permissions that you need to manage for a set of permission groups that would otherwise multiply exponentially to represent all possible combinations of staff roles.

In the following example, we create three new groups:

a Student group used to determine borrowing privileges

a Student Cataloger group representing a limited set of cataloging permissions appropriate for students

a Student Circulator group representing a limited set of circulation permissions appropriate for students

Then we add three new users to our system: one who needs to perform some cataloging duties as a student; one who needs perform some circulation duties as a student; and one who needs to perform both cataloging and circulation duties. This section demonstrates how to add these permissions to the users at the database level.

To create the Student group, add a new row to the permission.grp_tree table as a child of the Patrons group:

INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm)
SELECT 'Students', pgt.id, TRUE, 'Student borrowers', 'group_application.user.patron.student'
FROM permission.grp_tree pgt
 WHERE name = 'Patrons';

To create the Student Cataloger group, add a new row to the permission.grp_tree table as a child of the Staff group:

INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm)
SELECT 'Student Catalogers', pgt.id, TRUE, 'Student catalogers', 'group_application.user.staff.student_cataloger'
FROM permission.grp_tree pgt
WHERE name = 'Staff';

To create the Student Circulator group, add a new row to the permission.grp_tree table as a child of the Staff group:

INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm)
SELECT 'Student Circulators', pgt.id, TRUE, 'Student circulators', 'group_application.user.staff.student_circulator'
FROM permission.grp_tree pgt
WHERE name = 'Staff';

We want to give the Student Catalogers group the ability to work with MARC records at the consortial level, so we assign the UPDATE_MARC, CREATE_MARC, and IMPORT_MARC permissions at depth 0:

WITH pgt AS (
  SELECT id
  FROM permission.grp_tree
  WHERE name = 'Student Catalogers'
)
INSERT INTO permission.grp_perm_map (grp, perm, depth)
SELECT pgt.id, ppl.id, 0
FROM permission.perm_list ppl, pgt
WHERE ppl.code IN ('UPDATE_MARC', 'CREATE_MARC', 'IMPORT_MARC');

Similarly, we want to give the Student Circulators group the ability to check out copies and record in-house uses at the system level, so we assign the COPY_CHECKOUT and CREATE_IN_HOUSE_USE permissions at depth 1 (overriding the same Staff permissions that were granted only at depth 2):

WITH pgt AS (
  SELECT id
  FROM permission.grp_tree
  WHERE name = 'Student Circulators'
) INSERT INTO permission.grp_perm_map (grp, perm, depth)
SELECT pgt.id, ppl.id, 1
FROM permission.perm_list ppl, pgt
WHERE ppl.code IN ('COPY_CHECKOUT', 'CREATE_IN_HOUSE_USE');

Finally, we want to add our students to the groups. The request may arrive in your inbox from the library along the lines of "Please add Mint Julep as a Student Cataloger, Bloody Caesar as a Student Circulator, and Grass Hopper as a Student Cataloguer / Circulator; I’ve already created their accounts and given them a work organizational unit." You can translate that into the following SQL to add the users to the pertinent permission groups, adjusting for the inevitable typos in the names of the users.

First, add our Student Cataloger:

WITH pgt AS (
  SELECT id FROM permission.grp_tree
  WHERE name = 'Student Catalogers'
)
INSERT INTO permission.usr_grp_map (usr, grp)
SELECT au.id, pgt.id
FROM actor.usr au, pgt
WHERE first_given_name = 'Mint' AND family_name = 'Julep';

Next, add the Student Circulator:

WITH pgt AS (
  SELECT id FROM permission.grp_tree
  WHERE name = 'Student Circulators'
)
INSERT INTO permission.usr_grp_map (usr, grp)
SELECT au.id, pgt.id
FROM actor.usr au, pgt
WHERE first_given_name = 'Bloody' AND family_name = 'Caesar';

Finally, add the all-powerful Student Cataloger / Student Circulator:

 WITH pgt AS (
  SELECT id FROM permission.grp_tree
  WHERE name IN ('Student Catalogers', 'Student Circulators')
)
INSERT INTO permission.usr_grp_map (usr, grp)
SELECT au.id, pgt.id
FROM actor.usr au, pgt
WHERE first_given_name = 'Grass' AND family_name = 'Hopper';

While adopting this role-based approach might seem labour-intensive when applied to a handful of students in this example, over time it can help keep the permission profiles of your system relatively simple in comparison to the alternative approach of rapidly reproducing permission groups, overlapping permissions, and permissions granted on a one-by-one basis to individual users.

Chapter 26. Migrating Patron Data

This section will explain the task of migrating your patron data from comma delimited files into Evergreen. It does not deal with the process of exporting from the non-Evergreen system since this process may vary depending on where you are extracting your patron records. Patron could come from an ILS or it could come from a student database in the case of academic records.

When importing records into Evergreen you will need to populate 3 tables in your Evergreen database:

actor.usr - The main table for user data

actor.card - Stores the barcode for users; Users can have more than 1 card but only 1 can be active at a given time;

actor.usr_address - Used for storing address information; A user can have more than one address.

Before following the procedures below to import patron data into Evergreen, it is a good idea to examine the fields in these tables in order to decide on a strategy for data to include in your import. It is important to understand the data types and constraints on each field.

Export the patron data from your existing ILS or from another source into a comma delimited file. The comma delimited file used for importing the records should use Unicode (UTF8) character encoding.

Create a staging table. A staging table will allow you to tweak the data before importing. Here is an example sql statement:

    CREATE TABLE students (
         student_id int, barcode text, last_name text, first_name text, email text,
                 address_type text, street1 text, street2 text,
        city text, province text, country text, postal_code text, phone text, profile
        int DEFAULT 2, ident_type int, home_ou int, claims_returned_count int DEFAULT
                0, usrname text, net_access_level int DEFAULT 2, password text
    );

The default variables allow you to set default for your library or to populate required fields in Evergreen if your data includes NULL values.

The data field profile in the above SQL script refers to the user group and should be an integer referencing the id field in permission.grp_tree. Setting this value will affect the permissions for the user. See the values in permission.grp_tree for possibilities.

ident_type is the identification type used for identifying users. This is a integer value referencing config.identification_type and should match the id values of that table. The default values are 1 for Drivers License, 2 for SSN or 3 for other.

home_ou is the home organizational unit for the user. This value needs to match the corresponding id in the actor.org_unit table.

Copy records into staging table from a comma delimited file.

    COPY students (student_id, last_name, first_name, email, address_type, street1, street2,
        city, province, country, postal_code, phone)
        FROM '/home/opensrf/patrons.csv'
                WITH CSV HEADER;

The script will vary depending on the format of your patron load file (patrons.csv).

Formatting of some fields to fit Evergreen filed formatting may be required. Here is an example of sql to adjust phone numbers in the staging table to fit the evergreen field:

    UPDATE students phone = replace(replace(replace(rpad(substring(phone from 1 for 9), 10, '-') ||
    substring(phone from 10), '(', ''), ')', ''), ' ', '-');

Data “massaging” will be required to fit formats used in Evergreen.

Insert records from the staging table into the actor.usr Evergreen table:

     INSERT INTO actor.usr (
        profile, usrname, email, passwd, ident_type, ident_value, first_given_name,
        family_name, day_phone, home_ou, claims_returned_count, net_access_level)
        SELECT profile, students.usrname, email, password, ident_type, student_id,
        first_name, last_name, phone, home_ou, claims_returned_count, net_access_level
        FROM students;

Insert records into actor.card from actor.usr .

    INSERT INTO actor.card (usr, barcode)
        SELECT actor.usr.id, students.barcode
        FROM students
                INNER JOIN actor.usr
                        ON students.usrname = actor.usr.usrname;

This assumes a one to one card patron relationship. If your patron data import has multiple cards assigned to one patron more complex import scripts may be required which look for inactive or active flags.

Update actor.usr.card field with actor.card.id to associate active card with the user:

    UPDATE actor.usr
        SET card = actor.card.id
        FROM actor.card
        WHERE actor.card.usr = actor.usr.id;

Insert records into actor.usr_address to add address information for users:

    INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code)
        SELECT actor.usr.id, students.street1, students.street2, students.city, students.province,
        students.country, students.postal_code
        FROM students
        INNER JOIN actor.usr ON students.usrname = actor.usr.usrname;

Update actor.usr.address with address id from address table.

    UPDATE actor.usr
        SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id
        FROM actor.usr_address
        WHERE actor.usr.id = actor.usr_address.usr;

This assumes 1 address per patron. More complex scenarios may require more sophisticated SQL.

26.1. Creating an sql Script for Importing Patrons

The procedure for importing patron can be automated with the help of an sql script. Follow these steps to create an import script:

Create an new file and name it import.sql

Edit the file to look similar to this:

    BEGIN;

    -- Create staging table.
    CREATE TABLE students (
        student_id int, barcode text, last_name text, first_name text, email text, address_type text,
                street1 text, street2 text, city text, province text, country text, postal_code text, phone
                text, profile int, ident_type int, home_ou int, claims_returned_count int DEFAULT 0, usrname text,
        net_access_level int DEFAULT 2, password text
    );

    --Copy records from your import text file
    COPY students (student_id, last_name, first_name, email, address_type, street1, street2, city, province,
        country, postal_code, phone, password)
        FROM '/home/opensrf/patrons.csv' WITH CSV HEADER;

    --Insert records from the staging table into the actor.usr table.
    INSERT INTO actor.usr (
        profile, usrname, email, passwd, ident_type, ident_value, first_given_name, family_name,
        day_phone, home_ou, claims_returned_count, net_access_level)
        SELECT profile, students.usrname, email, password, ident_type, student_id, first_name,
        last_name, phone, home_ou, claims_returned_count, net_access_level FROM students;

    --Insert records from the staging table into the actor.usr table.
    INSERT INTO actor.card (usr, barcode)
        SELECT actor.usr.id, students.barcode
        FROM students
                INNER JOIN actor.usr
                        ON students.usrname = actor.usr.usrname;

    --Update actor.usr.card field with actor.card.id to associate active card with the user:
    UPDATE actor.usr
        SET card = actor.card.id
        FROM actor.card
        WHERE actor.card.usr = actor.usr.id;

    --INSERT records INTO actor.usr_address from staging table.
    INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code)
        SELECT actor.usr.id, students.street1, students.street2, students.city, students.province,
        students.country, students.postal_code
        FROM students
        INNER JOIN actor.usr ON students.usrname = actor.usr.usrname;

   --Update actor.usr mailing address with id from actor.usr_address table.:
    UPDATE actor.usr
        SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id
        FROM actor.usr_address
        WHERE actor.usr.id = actor.usr_address.usr;

    COMMIT;

Placing the sql statements between BEGIN; and COMMIT; creates a transaction block so that if any sql statements fail, the entire process is canceled and the database is rolled back to its original state. Lines beginning with — are comments to let you you what each sql statement is doing and are not processed.

26.2. Batch Updating Patron Data

For academic libraries, doing batch updates to add new patrons to the Evergreen database is a critical task. The above procedures and import script can be easily adapted to create an update script for importing new patrons from external databases. If the data import file contains only new patrons, then, the above procedures will work well to insert those patrons. However, if the data load contains all patrons, a second staging table and a procedure to remove existing patrons from that second staging table may be required before importing the new patrons. Moreover, additional steps to update address information and perhaps delete inactive patrons may also be desired depending on the requirements of the institution.

After developing the scripts to import and update patrons have been created, another important task for library staff is to develop an import strategy and schedule which suits the needs of the library. This could be determined by registration dates of your institution in the case of academic libraries. It is important to balance the convenience of patron loads and the cost of processing these loads vs staff adding patrons manually.

Chapter 27. Migrating from a legacy system

When you migrate to Evergreen, you generally want to migrate the bibliographic records and copy information that existed in your previous library system. For anything more than a few thousand records, you should import the data directly into the database rather than use the tools in the staff client. While the data that you can extract from your legacy system varies widely, this section assumes that you or members of your team have the ability to write scripts and are comfortable working with SQL to manipulate data within PostgreSQL. If so, then the following section will guide you towards a method of generating common data formats so that you can then load the data into the database in bulk.

27.1. Making electronic resources visible in the catalog

Electronic resources generally do not have any call number or copy information associated with them, and Evergreen enables you to easily make bibliographic records visible in the public catalog within sections of the organizational unit hierarchy. For example, you can make a set of bibliographic records visible only to specific branches that have purchased licenses for the corresponding resources, or you can make records representing publicly available electronic resources visible to the entire consortium.

Therefore, to make a record visible in the public catalog, modify the records using your preferred MARC editing approach to ensure the 856 field contains the following information before loading records for electronic resources into Evergreen:

Table 27.1. 856 field for electronic resources: indicators and subfields

Attribute
Value
Note

Indicator 1

4

Indicator 2

0 or 1

Subfield u

URL for the electronic resource

Subfield y

Text content of the link

Subfield z

Public note

Normally displayed after the link

Subfield 9

Organizational unit short name

The record will be visible when a search is performed specifying this organizational unit or one of its children. You can repeat this subfield as many times as you need.

Once your electronic resource bibliographic records have the required indicators and subfields for each 856 field in the record, you can proceed to load the records using either the command-line bulk import method or the MARC Batch Importer in the staff client.

27.2. Migrating your bibliographic records

Convert your MARC21 binary records into the MARCXML format, with one record per line. You can use the following Python script to achieve this goal; just install the pymarc library first, and adjust the values of the input and output variables as needed.

#!/usr/bin/env python
# -*- coding: utf-8 -*-
import codecs
import pymarc

input = 'records_in.mrc'
output = 'records_out.xml'

reader = pymarc.MARCReader(open(input, 'rb'), to_unicode=True)
writer = codecs.open(output, 'w', 'utf-8')
for record in reader:
    record.leader = record.leader[:9] + 'a' + record.leader[10:]
    writer.write(pymarc.record_to_xml(record) + "\n")

Once you have a MARCXML file with one record per line, you can load the records into your Evergreen system via a staging table in your database.

Connect to the PostgreSQL database using the psql command. For example:

psql -U <user-name> -h <hostname> -d <database>

Create a staging table in the database. The staging table is a temporary location for the raw data that you will load into the production table or tables. Issue the following SQL statement from the psql command line, adjusting the name of the table from staging_records_import, if desired:

CREATE TABLE staging_records_import (id BIGSERIAL, dest BIGINT, marc TEXT);

Create a function that will insert the new records into the production table and update the dest column of the staging table. Adjust "staging_records_import" to match the name of the staging table that you plan to create when you issue the following SQL statement:

CREATE OR REPLACE FUNCTION staging_importer() RETURNS VOID AS $$
DECLARE stage RECORD;
BEGIN
FOR stage IN SELECT * FROM staging_records_import ORDER BY id LOOP
      INSERT INTO biblio.record_entry (marc, last_xact_id) VALUES (stage.marc, 'IMPORT');
      UPDATE staging_records_import SET dest = currval('biblio.record_entry_id_seq')
       WHERE id = stage.id;
   END LOOP;
  END;
  $$ LANGUAGE plpgsql;

Load the data from your MARCXML file into the staging table using the COPY statement, adjusting for the name of the staging table and the location of your MARCXML file:

COPY staging_records_import (marc) FROM '/tmp/records_out.xml';

Load the data from your staging table into the production table by invoking your staging function:

SELECT staging_importer();

When you leave out the id value for a BIGSERIAL column, the value in the column automatically increments for each new record that you add to the table.

Once you have loaded the records into your Evergreen system, you can search for some known records using the staff client to confirm that the import was successful.

27.3. Migrating your call numbers, copies, and parts

Holdings, comprised of call numbers, copies, and parts, are the set of objects that enable users to locate and potentially acquire materials from your library system.

Call numbers connect libraries to bibliographic records. Each call number has a label associated with a classification scheme such as a the Library of Congress or Dewey Decimal systems, and can optionally have either or both a label prefix and a label suffix. Label prefixes and suffixes do not affect the sort order of the label.

Copies connect call numbers to particular instances of that resource at a particular library. Each copy has a barcode and must exist in a particular copy location. Other optional attributes of copies include circulation modifier, which may affect whether that copy can circulate or for how long it can circulate, and OPAC visibility, which controls whether that particular copy should be visible in the public catalog.

Parts provide more granularity for copies, primarily to enable patrons to place holds on individual parts of a set of items. For example, an encyclopedia might be represented by a single bibliographic record, with a single call number representing the label for that encyclopedia at a given library, with 26 copies representing each letter of the alphabet, with each copy mapped to a different part such as A, B, C, … Z.

To migrate this data into your Evergreen system, you will create another staging table in the database to hold the raw data for your materials from which the actual call numbers, copies, and parts will be generated.

Begin by connecting to the PostgreSQL database using the psql command. For example:

psql -U <user-name> -h <hostname> -d <database>

Create the staging materials table by issuing the following SQL statement:

CREATE TABLE staging_materials (
  bibkey BIGINT,  -- biblio.record_entry_id
  callnum TEXT, -- call number label
  callnum_prefix TEXT, -- call number prefix
  callnum_suffix TEXT, -- call number suffix
  callnum_class TEXT, -- classification scheme
  create_date DATE,
  location TEXT, -- shelving location code
  item_type TEXT, -- circulation modifier code
  owning_lib TEXT, -- org unit code
  barcode TEXT, -- copy barcode
  part TEXT
);

For the purposes of this example migration of call numbers, copies, and parts, we assume that you are able to create a tab-delimited file containing values that map to the staging table properties, with one copy per line. For example, the following 5 lines demonstrate how the file could look for 5 different copies, with non-applicable attribute values represented by \N, and 3 of the copies connected to a single call number and bibliographic record via parts:

1   QA 76.76 A3 \N  \N  LC  2012-12-05  STACKS  BOOK    BR1 30007001122620  \N
2   GV 161 V8   Ref.    Juv.    LC  2010-11-11  KIDS    DVD BR2 30007005197073  \N
3   AE 5 E363 1984  \N  \N      LC  1984-01-10  REFERENCE   BOOK    BR1 30007006853385  A
3   AE 5 E363 1984  \N  \N      LC  1984-01-10  REFERENCE   BOOK    BR1 30007006853393  B
3   AE 5 E363 1984  \N  \N      LC  1984-01-10  REFERENCE   BOOK    BR1 30007006853344  C

Once your holdings are in a tab-delimited format—which, for the purposes of this example, we will name holdings.tsv--you can import the holdings file into your staging table. Copy the contents of the holdings file into the staging table using the COPY SQL statement:

COPY staging_items (bibkey, callnum, callnum_prefix,
  callnum_suffix, callnum_class, create_date, location,
  item_type, owning_lib, barcode, part) FROM 'holdings.tsv';

Generate the copy locations you need to represent your holdings:

INSERT INTO asset.copy_location (name, owning_lib)
  SELECT DISTINCT location, 1 FROM staging_materials
  WHERE NOT EXISTS (
    SELECT 1 FROM asset.copy_location
    WHERE name = location
  );

Generate the circulation modifiers you need to represent your holdings:

INSERT INTO config.circ_modifier (code, name, description, sip2_media_type)
  SELECT DISTINCT circmod, circmod, circmod, '001'
  FROM staging_materials
  WHERE NOT EXISTS (
    SELECT 1 FROM config.circ_modifier
    WHERE circmod = code
  );

Generate the call number prefixes and suffixes you need to represent your holdings:

INSERT INTO asset.call_number_prefix (owning_lib, label)
  SELECT DISTINCT aou.id, callnum_prefix
  FROM staging_materials sm
    INNER JOIN actor.org_unit aou
      ON aou.shortname = sm.owning_lib
  WHERE NOT EXISTS (
    SELECT 1 FROM asset.call_number_prefix acnp
    WHERE callnum_prefix = acnp.label
      AND aou.id = acnp.owning_lib
  ) AND callnum_prefix IS NOT NULL;

INSERT INTO asset.call_number_suffix (owning_lib, label)
  SELECT DISTINCT aou.id, callnum_suffix
  FROM staging_materials sm
    INNER JOIN actor.org_unit aou
      ON aou.shortname = sm.owning_lib
  WHERE NOT EXISTS (
    SELECT 1 FROM asset.call_number_suffix acns
    WHERE callnum_suffix = acns.label
      AND aou.id = acns.owning_lib
  ) AND callnum_suffix IS NOT NULL;

Generate the call numbers for your holdings:

INSERT INTO asset.call_number (
  creator, editor, record, owning_lib, label, prefix, suffix, label_class
)
  SELECT DISTINCT 1, 1, bibkey, aou.id, callnum, acnp.id, acns.id,
  CASE WHEN callnum_class = 'LC' THEN 1
             WHEN callnum_class = 'DEWEY' THEN 2
  END
  FROM staging_materials sm
    INNER JOIN actor.org_unit aou
      ON aou.shortname = owning_lib
    INNER JOIN asset.call_number_prefix acnp
      ON COALESCE(acnp.label, '') = COALESCE(callnum_prefix, '')
    INNER JOIN asset.call_number_suffix acns
      ON COALESCE(acns.label, '') = COALESCE(callnum_suffix, '')
;

Generate the copies for your holdings:

INSERT INTO asset.copy (
  circ_lib, creator, editor, call_number, location,
 loan_duration, fine_level, barcode
)
  SELECT DISTINCT aou.id, 1, 1, acn.id, acl.id, 2, 2, barcode
  FROM staging_materials sm
    INNER JOIN actor.org_unit aou
      ON aou.shortname = sm.owning_lib
    INNER JOIN asset.copy_location acl
      ON acl.name = sm.location
    INNER JOIN asset.call_number acn
      ON acn.label = sm.callnum
  WHERE acn.deleted IS FALSE
;

Generate the parts for your holdings. First, create the set of parts that are required for each record based on your staging materials table:

INSERT INTO biblio.monograph_part (record, label)
  SELECT DISTINCT bibkey, part
  FROM staging_materials sm
  WHERE part IS NOT NULL AND NOT EXISTS (
    SELECT 1 FROM biblio.monograph_part bmp
    WHERE sm.part = bmp.label
      AND sm.bibkey = bmp.record
  );

Now map the parts for each record to the specific copies that you added:

INSERT INTO asset.copy_part_map (target_copy, part)
  SELECT DISTINCT acp.id, bmp.id
  FROM staging_materials sm
    INNER JOIN asset.copy acp
      ON acp.barcode = sm.barcode
    INNER JOIN biblio.monograph_part bmp
      ON bmp.record = sm.bibkey
  WHERE part IS NOT NULL
    AND part = bmp.label
    AND acp.deleted IS FALSE
    AND NOT EXISTS (
    SELECT 1 FROM asset.copy_part_map
    WHERE target_copy = acp.id
      AND part = bmp.id
  );

At this point, you have loaded your bibliographic records, call numbers, call number prefixes and suffixes, copies, and parts, and your records should be visible to searches in the public catalog within the appropriate organization unit scope.

Chapter 28. Importing materials in the staff client

Evergreen exists to connect users to the materials represented by bibliographic records, call numbers, and copies — so getting these materials into your Evergreen system is vital to a successful system. There are two primary means of getting materials into Evergreen:

The Evergreen staff client offers the MARC Batch Importer, which is a flexible interface primarily used for small batches of records;

Alternately, import scripts can load data directly into the database, which is a highly flexible but much more complex method of loading materials suitable for large batches of records such as the initial migration from your legacy library system.

28.1. Staff client batch record imports

The staff client has a utility for importing batches of bibliographic and copy records available through Cataloging > MARC Batch Import/Export. In addition to importing new records, this interface can be used to match incoming records to existing records in the database, add or overlay MARC fields in the existing record, and add copies to those records.

The MARC Batch Import interface may also be colloquially referred to as "Vandelay" in the Evergreen community, referring to this interface’s internals in the system.You will also see this name used in several places in the editor. For instance, when you click on the Record Match Sets, the title on the screen will be Vandelay Match Sets.

28.1.1. When to use the MARC Batch Importer

When importing in batches of up to 500 to 1,000 records.

When you need the system to match those incoming records to existing records and overlay or add fields to the existing record.

When you need to add copies to existing records in the system.

If you are importing copies that do not have barcodes or call numbers, you must enable the Vandelay Generate Default Barcodes and Vandelay Default Barcode Prefix (vandelay.item.barcode.prefix) settings.

28.1.2. Record Match Sets

Click the Record Match Sets button to identify how Evergreen should match incoming records to existing records in the system.

These record match sets can be used when importing records through the MARC Batch Importer or when importing order records through the Acquisitions Load MARC Order Records interface.

Common match points used when creating a match set include:

MARC tag 020a (ISBN)

MARC tag 022a (ISSN)

MARC tag 024a (UPC)

MARC tag 028a (Publisher number)

28.1.3. Create Match Sets

On the Record Match Sets screen, click New Match Set to create a set of record match points. Give the set a Name. Assign the Owning Library from the dropdown list. The Match Set Type should remain as biblio. Click Save.

If you don’t see your new set in the list, in the upper left corner of the staff client window, click the Reload button.

If you had to reload, click the Record Match Sets button to get back to that screen. Find your new set in the list and click its name. (The name will appear to be a hyperlink.) This will bring you to the Vandelay Match Set Editor.

Create an expression that will define the match points for the incoming record. You can choose from two areas to create a match: Record Attribute (MARC fixed fields) or MARC Tag and Subfield. You can use the Boolean operators AND and OR to combine these elements to create a match set.

When adding a Record Attribute or MARC tag/subfield, you also can enter a Match Score. The Match Score indicates the relative importance of that match point as Evergreen evaluates an incoming record against an existing record. You can enter any integer into this field. The number that you enter is only important as it relates to other match points.

Recommended practice is that you create a match score of one (1) for the least important match point and assign increasing match points to the power of 2 to working points in increasing importance. . After creating a match point, drag the completed match point under the folder with the appropriately-named Boolean folder under the Expression tree.

Click Save Changes to Expression.

28.1.4. Quality Metrics

Quality metrics provide a mechanism for Evergreen to measure the quality of records and to make importing decisions based on quality.

Metrics are configured in the match set editor.

Quality metrics are not required when creating a match set.

You can use a value in a record attribute (MARC fixed fields) or a MARC tag as your quality metric.

The encoding level record attribute can be one indicator of record quality.

28.1.5. Import Item Attributes

If you are importing copies with your records, you will need to map the data in your holdings tag to fields in the copy record. Click the Holdings Import Profile button to map this information.

Click the New Definition button to create a new mapping for the holdings tag.

Add a Name for the definition.

Use the Tag field to identify the MARC tag that contains your holdings information.

Add the subfields that contain specific copy information to the appropriate copy field.

Select the Keep box if Evergreen should keep this holdings tag in the record after it is imported. Otherwise, Evergreen will remove this holdings tag.

At a minimum, you should add the subfields that identify the Circulating Library, the Owning Library, the Call Number and the Barcode.

For more details, see the full list of import fields

All fields (except for Name, Tag and Keep) can contain static values, a MARC subfield code (such as "a"), or an XPATH query.

28.1.6. Overlay/Merge Profiles

If Evergreen finds a match for an incoming record in the database, you need to identify which fields should be replaced, which should be preserved, and which should be added to the record. Click the Merge/Overlay Profiles button to create a profile that contains this information.

These overlay/merge profiles can be used when importing records through the MARC Batch Importer or when importing order records through the Acquisitions Load MARC Order Records interface.

Evergreen comes pre-installed with two default profiles:

Default merge - No fields from incoming record are added to match. This profile is useful for item loads or for order record uploads.

Default overlay - Incoming record will replace existing record.

You can customize the overlay/merge behavior with a new profile by clicking the New Merge Profile button. Available options for handling the fields include:

Preserve specification - fields in the existing record that should be preserved.

Replace specification - fields in existing record that should be replaced by those in the incoming record.

Add specification - fields from incoming record that should be added to existing record (in addition to any already there.)

Remove specification - fields that should be removed from incoming record.

You can add multiple tags to these specifications, separating each tag with a comma.

28.1.7. Importing the records

After making the above configurations, you are now ready to import your records.

Click the Import Records button

Provide a unique name for the queue where the records will be loaded

Identify the match set that should be used for matching

If you are importing copies, identify the Import Item Attributes definition in the Holdings Import Profile

Select a record source

Select the overlay/merge profile that defines which fields should be replaced, added or preserved

Identify which records should be imported, the options are:

Import Non-Matching Records will automatically import records that have no match in the system

Merge on Exact Match will automatically import records that match on the 901c (record ID)

Merge on Single Match will automatically import records when there is only one match in the system

Merge on Best Match will automatically import records for the best match in the system; the best match will be determined by the combined total of the records match point scores

You do not need to select any of these import options at this step. You may also opt to review the records first in the import queue and then import them.

Best Single Match Minimum Quality Ratio should only be changed if quality metrics were used in the match set

Set to 0.0 to import a record regardless of record quality

Set to 1.0 if the incoming record must be of equal or higher quality than the existing record to be imported

Set to 1.1 if the incoming record must be of higher quality than the existing record to be imported

Insufficient Quality Fall-Through Profile can also be used with quality metrics. If an incoming record does not meet the standards of the minimum quality ratio, you can identify a back-up merge profile to be used for those records. For example, you may want to use the default overlay profile for high-quality records but use the default merge profile for lower quality records.

Chapter 29. Ordering materials

Acquisitions allows you to order materials, track the expenditure of your collections funds, track invoices and set up policies for manual claiming. In this chapter, we’re going to be describing how to use the most essential functions of acquisitions in the Evergreen system.

29.1. When should libraries use acquisitions?

When you want to track spending of your collections budget.

When you want to use Evergreen to place orders electronically with your vendors.

When you want to import large batches of records to quickly get your on-order titles into the system.

If your library simply wants to add on-order copies to the catalog so that patrons can view and place holds on titles that have not yet arrived, acquisitions may be more than you need. Adding those on-order records via cataloging is a simpler option that works well for this use case.

Below are the basic administrative settings to be configured to get started with acquisitions. At a minimum, a library must configure Funding Sources, Funds, and Providers to use acquisitions.

29.2. Managing Funds

29.2.1. Funding Sources (Required)

Funding sources allow you to specify the sources that contribute monies to your fund(s). You can create as few or as many funding sources as you need. These can be used to track exact amounts for accounts in your general ledger.

Example funding sources might be:

A municipal allocation for your materials budget;

A trust fund used for collections;

A revolving account that is used to replace lost materials;

Grant funds to be used for collections.

Funding sources are not tied to fiscal or calendar years, so you can continue to add money to the same funding source over multiple years, e.g. County Funding. Alternatively, you can name funding sources by year, e.g. County Funding 2010 and County Funding 2011, and apply credits each year to the matching source.

To create a funding source, select Admin > Server Administration > Acquisitions > Funding Source. Click the New Funding Source button. Give the funding source a name, an owning library, and code. You should also identify the type of currency that is used for the fund.

You must add money to the funding source before you can use it. Click the hyperlinked name of the funding source and then click the Apply Credit button. Add the amount of funds you need to add. The Note field is optional.

29.2.2. Funds (Required)

Funds allow you to allocate credits toward specific purchases. They typically are used to track spending and purchases for specific collections. Some libraries may choose to define very broad funds for their collections (e.g. children’s materials, adult materials) while others may choose to define more specific funds (e.g. adult non-fiction DVDs for BR1).

If your library does not wish to track fund accounting, you can create one large generic fund and use that fund for all of your purchases.

To create a fund, select Admin > Server Administration > Acquisitions > Funds. Click the New Fund button. Give the fund a name and code.

The Year can either be the fiscal or calendar year for the fund.

If you are a multi-branch library that will be ordering titles for multiple branches, you should select the system as the owning Org Unit, even if this fund will only be used for collections at a specific branch. If you are a one-branch library or if your branches do their own ordering, you can select the branch as the owning Org Unit.

Select the Currency Type that will be used for this fund.

You must select the Active checkbox to use the fund.

Enter a Balance Stop Percent. The balance stop percent prevents you from making purchases when only a specified amount of the fund remains. For example, if you want to spend 95 percent of your funds, leaving a five percent balance in the fund, then you would enter 95 in the field. When the fund reaches its balance stop percent, it will appear in red when you apply funds to copies.

Enter a Balance Warning Percent. The balance warning percent gives you a warning that the fund is low. You can specify any percent. For example, if you want to spend 90 percent of your funds and be warned when the fund has only 10 percent of its balance remaining, then enter 90 in the field. When the fund reaches its balance warning percent, it will appear in yellow when you apply funds to copies.

Check the Propagate box to propagate funds. When you propagate a fund, the system will create a new fund for the following fiscal year with the same parameters as your current fund. All of the settings transfer except for the year and the amount of money in the fund. Propagation occurs during the fiscal year close-out operation.

Check the Rollover box if you want to roll over remaining encumbrances and funds into the same fund next year. If you need the ability to roll over encumbrances without rolling over funds, go to the Library Settings Editor (Admin > Local Administration > Library Settings Editor) and set Allow funds to be rolled over without bringing the money along to True.

You must add money to the fund before you can begin using it. Click the hyperlinked name of the fund. Click the Create Allocation button. Select a Funding Source from which the allocation will be drawn and then enter an amount for the allocation. The Note field is optional.

29.2.3. Fund Tags (Optional)

You can apply tags to funds so that you can group funds for easy reporting. For example, you have three funds for children’s materials: Children’s Board Books, Children’s DVDs, and Children’s CDs. Assign a fund tag of children’s to each fund. When you need to report on the amount that has been spent on all children’s materials, you can run a report on the fund tag to find total expenditures on children’s materials rather than reporting on each individual fund.

To create a fund tag, select Admin > Server Administration > Acquisitions > Fund Tags. Click the New Fund Tag button. Select a owning library and add the name for the fund tag.

To apply a fund tag to a fund, select Admin > Server Administration > Acquisitions > Funds. Click on the hyperlinked name for the fund. Click the Tags tab and then click the Add Tag button. Select the tag from the dropdown menu.

29.3. Ordering

29.3.1. Providers (Required)

Providers are the vendors from whom you order titles.

To add a provider record, select Admin > Server Administration > Acquisitions > Providers.

Enter information about the provider. At a minimum, you need to add a Provider Name, Code, Owner, and Currency. You also need to select the Active checkbox to use the provider.

29.3.2. Distribution Formulas (Optional)

If you are ordering for a multi-branch library system, distribution formulas are a useful way to specify the number of copies that should be distributed to specific branches and copy locations.

To create a distribution formula, select Admin > Server Administration > Acquisitions > Distribution Formulas. Click the New Formula button. Enter the formula name and select the owning library. Ignore the Skip Count field.

Click New Entry. Select an Owning Library from the drop down menu. This indicates the branch that will receive the items.

Select a Shelving Location from the drop down menu.

In the Item Count field, enter the number of items that should be distributed to that branch and copy location. You can enter the number or use the arrows on the right side of the field.

Keep adding entries until the distribution formula is complete.

29.3.3. Helpful acquisitions Library Settings

There are several acquisitions Library Settings available that will help with acquisitions workflow. These settings can be found at Admin > Local Administration > Library Settings Editor.

Default circulation modifier - Automatically applies a default circulation modifier to all of your acquisitions copies. Useful if you use a specific circulation modifier for on-order copies.

Default copy location - Automatically applies a default copy location (e.g. On Order) to acquisitions copies.

Temporary barcode prefix - Applies a unique prefix to the barcode that is automatically generated during the acquisitions process.

Temporary call number prefix - Applies a unique prefix to the start of the call number that is automatically generated during the acquisitions process.

29.3.4. Preparing for order record loading

If your library is planning to upload order records in a batch, you need to add some information to your provider records so that Evergreen knows how to map the copy data contained in the order record.

Retrieve the record for the provider that has supplied the order records by selecting Admin > Server Administration > Acquisitions > Providers. Click on the hyperlinked Provider name.

In the top frame, add the MARC tag that contains your holdings data in the Holdings Tag field (this tag can also be entered at the time you create the provider record.)

To map the tag’s subfields to the appropriate copy data, click the Holding Subfield tab. Click the New Holding Subfield button and select the copy data that you are mapping. Add the subfield that contains that data and click Save.

If your vendor is sending other data in a MARC tag that needs to be mapped to a field in acquisitions, you can do so by clicking the Attribute Definitions tab. As an example, if you need to import the PO Name, you could set up an attribute definition by adding an XPath similar to:

code => purchase_order
xpath => //*[@tag="962"]/*[@code="p"]
Is Identifier => false

where 962 is the holdings tag and p is the subfield that contains the PO Name.

29.3.5. Preparing to send electronic orders from Evergreen

If your library wants to transmit electronic order information to a vendor, you will need to configure your server to use EDI. You need to install the EDI translator and EDI scripts on your server by following the instructions in the Evergreen 2.3 documentation. (http://docs.evergreen-ils.org/2.3/_installation.html)

Configure your provider’s EDI information by selecting Admin > Server Administration > Acquisitions > EDI Accounts. Give the account a name in the Label box.

Host is the vendor-assigned FTP/SFTP/SSH hostname.

Username is the vendor-assigned FTP/SFTP/SSH username.

Password is the vendor-assigned FTP/SFTP/SSH password.

Account This field enables you to add a supplemental password for entry to a remote system after log in has been completed. This field is optional for the ILS but may be required by your provider.

Owner is the organizational unit who owns the EDI account

Last Activity is the date of last activity for the account

Provider is a link to the codes for the Provider record.

Path is the path on the vendor’s server where Evergreen will deposit its outgoing order files.

Incoming Directory is the path on the vendor’s server where Evergreen will retrieve incoming order responses and invoices.

Vendor Account Number is the Vendor assigned account number.

Vendor Assigned Code is usually a sub-account designation. It can be used with or without the Vendor Account Number.

You now need to add this EDI Account and the SAN code to the provider’s record.

Select Admin > Server Administration > Acquisitions > Providers.

Click the hyperlinked Provider name.

Select the account you just created in the EDI Default field.

Add the vendor-provided SAN code to the SAN field.

The last step is to add your library’s SAN code to Evergreen.

Select Admin > Server Administration > Organizational Units.

Select your library from the organizational hierarchy in the left pane.

Click the Addresses tab and add your library’s SAN code to the SAN field.

Chapter 30. Designing your catalog

When people want to find things in your Evergreen system, they will check the catalog. In Evergreen, the catalog is made available through a web interface, called the OPAC (Online Public Access Catalog). In the latest versions of the Evergreen system, the OPAC is built on a set of programming modules called the Template Toolkit. You will see the OPAC sometimes referred to as the TPAC.

In this chapter, we’ll show you how to customize the OPAC, change it from its default configuration, and make it your own.

30.1. Configuring and customizing the public interface

The public interface is referred to as the TPAC or Template Toolkit (TT) within the Evergreen community. The template toolkit system allows you to customize the look and feel of your OPAC by editing the template pages (.tt2) files as well as the associated style sheets.

30.1.1. Locating the default template files

The default URL for the TPAC on a default Evergreen system is http://localhost/eg/opac/home (adjust localhost to match your hostname or IP address).

The default template file is installed in /openils/var/templates/opac.

You should generally avoid touching the installed default template files, unless you are contributing changes for Evergreen to adopt as a new default. Even then, while you are developing your changes, consider using template overrides rather than touching the installed templates until you are ready to commit the changes to a branch. See below for information on template overrides.

30.1.2. Mapping templates to URLs

The mapping for templates to URLs is straightforward. Following are a few examples, where <templates> is a placeholder for one or more directories that will be searched for a match:

http://localhost/eg/opac/home ⇒ /openils/var/<templates>/opac/home.tt2

http://localhost/eg/opac/advanced ⇒ /openils/var/<templates>/opac/advanced.tt2

http://localhost/eg/opac/results ⇒ /openils/var/<templates>/opac/results.tt2

The template files themselves can process, be wrapped by, or include other template files. For example, the home.tt2 template currently involves a number of other template files to generate a single HTML file.

Example Template Toolkit file: opac/home.tt2.

[%  PROCESS "opac/parts/header.tt2";
    WRAPPER "opac/parts/base.tt2";
    INCLUDE "opac/parts/topnav.tt2";
    ctx.page_title = l("Home") %]
    <div id="search-wrapper">
      [% INCLUDE "opac/parts/searchbar.tt2" %]
    </div>
    <div id="content-wrapper">
        <div id="main-content-home">
             <div class="common-full-pad"></div>
             [% INCLUDE "opac/parts/homesearch.tt2" %]
             <div class="common-full-pad"></div>
        </div>
     </div>
[% END %]

Note that file references are relative to the top of the template directory.

30.1.3. How to override template files

Overrides for template files or TPAC pages go in a directory that parallels the structure of the default templates directory. The overrides then get pulled in via the Apache configuration.

The following example demonstrates how to create a file that overrides the default "Advanced search page" (advanced.tt2) by adding a new templates_custom directory and editing the new file in that directory.

bash$ mkdir -p /openils/var/templates_custom/opac
bash$ cp /openils/var/templates/opac/advanced.tt2 \
         /openils/var/templates_custom/opac/.
bash$ vim /openils/var/templates_custom/opac/advanced.tt2

30.1.4. Configuring the custom templates directory in Apache’s eg.conf

You now need to teach Apache about the new custom template directory. Edit /etc/apache2/sites-available/eg.conf and add the following <Location /eg> element to each of the <VirtualHost> elements in which you want to include the overrides. The default Evergreen configuration includes a VirtualHost directive for port 80 (HTTP) and another one for port 443 (HTTPS); you probably want to edit both, unless you want the HTTP user experience to be different from the HTTPS user experience.

<VirtualHost *:80>
    # <snip>

    # - absorb the shared virtual host settings
    Include eg_vhost.conf
    <Location /eg>
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_custom"
    </Location>

    # <snip>
</VirtualHost>

Finally, reload the Apache configuration to pick up the changes. You should now be able to see your change at http://localhost/eg/opac/advanced where localhost is the hostname of your Evergreen server.

30.1.5. Adjusting colors for your public interface

You may adjust the colors of your public interface by editing the colors.tt2 file. The location of this file is in /openils/var/templates/opac/parts/css/colors.tt2. When you customize the colors of your public interface, remember to create a custom file in your custom template folder and edit the custom file and not the file located in you default template.

30.1.6. Adjusting fonts in your public interface

Font sizes can be changed in the colors.tt2 file located in /openils/var/templates/opac/parts/css/. Again, create and edit a custom template version and not the file in the default template.

Other aspects of fonts such as the default font family can be adjusted in /openils/var/templates/opac/css/style.css.tt2.

30.1.7. Media file locations in the public interface

The media files (mostly PNG images) used by the default TPAC templates are stored in the repository in Open-ILS/web/images/ and installed in /openils/var/web/images/.

30.1.8. Changing some text in the public interface

Out of the box, TPAC includes a number of placeholder text and links. For example, there is a set of links cleverly named Link 1, Link 2, and so on in the header and footer of every page in TPAC. Here is how to customize that for a custom templates skin.

To begin with, find the page(s) that contain the text in question. The simplest way to do that is with the grep -s command. In the following example, search for files that contain the text "Link 1":

bash$ grep -r "Link 1" /openils/var/templates/opac
/openils/var/templates/opac/parts/topnav_links.tt2
4:            <a href="http://example.com">[% l('Link 1') %]</a>

Next, copy the file into our overrides directory and edit it with vim.

Copying the links file into the overrides directory.

bash$ cp /openils/var/templates/opac/parts/topnav_links.tt2 \
/openils/var/templates_custom/opac/parts/topnav_links.tt2
bash$ vim /openils/var/templates_custom/opac/parts/topnav_links.tt2

Finally, edit the link text in opac/parts/header.tt2. Content of the opac/parts/header.tt2 file.

<div id="gold-links-holder">
    <div id="gold-links">
        <div id="header-links">
            <a href="http://example.com">[% l('Link 1') %]</a>
            <a href="http://example.com">[% l('Link 2') %]</a>
            <a href="http://example.com">[% l('Link 3') %]</a>
            <a href="http://example.com">[% l('Link 4') %]</a>
            <a href="http://example.com">[% l('Link 5') %]</a>
        </div>
    </div>
</div>

For the most part, the page looks like regular HTML, but note the [%_(" ")%] that surrounds the text of each link. The [% ... %] signifies a TT block, which can contain one or more TT processing instructions. l(" ... "); is a function that marks text for localization (translation); a separate process can subsequently extract localized text as GNU gettext-formatted PO (Portable Object) files.

As Evergreen supports multiple languages, any customization to Evergreen’s default text must use the localization function. Also, note that the localization function supports placeholders such as [_1], [_2] in the text; these are replaced by the contents of variables passed as extra arguments to the l() function.

Once the link and link text has been edited to your satisfaction, load the page in a Web browser and see the live changes immediately.

30.1.9. Adding translations to PO file

After you have added custom text in translatable form to a TT2 template, you need to add the custom strings and its translations to the PO file containing the translations. Evergreen PO files are stored in /openils/var/template/data/locale/

The PO file consists of pairs of the text extracted from the code: Message ID denoted as msgid and message string denoted as msgstr. When adding the custom string to PO file:

The line with English expressions must start with msgid. The English term must be enclosed in double apostrophes.

The line with translation start with /msgstr/. The translation to local language must be and enclosed in enclosed in double apostrophes.

It is recommended to add a note in which template and on which line the particular string is located. The lines with notes must be marked as comments i.e., start with number sign (#)

Example:

# ---------------------------------------------------------------------
# The lines below contains the custom strings manually added to the catalog
# ---------------------------------------------------------------------

#: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
msgid "Union Catalog of the Czech Republic"
msgstr "Souborný katalog České republiky"

#: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
msgid "Uniform Information Gateway "
msgstr "Jednotná informační brána"

It is good practice to save backup copy of the original PO file before changing it.

After making changes, restart Apache to make the changes take effect. As root run the command:

service apache2 restart

30.1.10. Adding and removing MARC fields from the record details display page

It is possible to add and remove the MARC fields and subfields displayed in the record details page. In order to add MARC fields to be displayed on the details page of a record, you will need to map the MARC code to variables in the /openils/var/templates/opac/parts/misc_util.tt2 file.

For example, to map the template variable args.pubdates to the date of publication MARC field 260, subfield c, add these lines to misc_util.tt2:

args.pubdates = [];
FOR sub IN xml.findnodes('//*[@tag="260"]/*[@code="c"]');
    args.pubdates.push(sub.textContent);
END;
args.pubdate = (args.pubdates.size) ? args.pubdates.0 : ''

You will then need to edit the /openils/var/templates/opac/parts/record/summary.tt2 file in order to get the template variable for the MARC field to display.

For example, to display the date of publication code you created in the misc_util.tt2 file, add these lines:

[% IF attrs.pubdate; %]
    <span itemprop="datePublished">[% attrs.pubdate | html; %]</span>
[% END; %]

You can add any MARC field to your record details page. Moreover, this approach can also be used to display MARC fields in other pages, such as your results page.

30.2. Setting the default physical location for your library environment

physical_loc is an Apache environment variable that sets the default physical location, used for setting search scopes and determining the order in which copies should be sorted. This variable is set in /etc/apache2/sites-available/eg.conf. The following example demonstrates the default physical location being set to library ID 104:

SetEnv physical_loc 104

30.3. Setting a default language and adding optional languages

OILSWebLocale adds support for a specific language. Add this variable to the Virtual Host section in /etc/apache2/eg_vhost.conf.

OILSWebDefaultLocale specifies which locale to display when a user lands on a page in TPAC and has not chosen a different locale from the TPAC locale picker. The following example shows the fr_ca locale being added to the locale picker and being set as the default locale:

PerlAddVar OILSWebLocale "fr_ca"
PerlAddVar OILSWebLocale "/openils/var/data/locale/opac/fr-CA.po"
PerlAddVar OILSWebDefaultLocale "fr-CA"

Below is a table of the currently supported languages packaged with Evergreen:

Language
Code
PO file

Arabic - Jordan

ar_jo

/openils/var/data/locale/opac/ar-JO.po

Armenian

hy_am

/openils/var/data/locale/opac/hy-AM.po

Czech

cs_cz

/openils/var/data/locale/opac/cs-CZ.po

English - Canada

en_ca

/openils/var/data/locale/opac/en-CA.po

English - Great Britain

en_gb

/openils/var/data/locale/opac/en-GB.po

*English - United States

en_us

not applicable

French - Canada

fr_ca

/openils/var/data/locale/opac/fr-CA.po

Portuguese - Brazil

pt_br

/openils/var/data/locale/opac/pt-BR.po

Spanish

es_es

/openils/var/data/locale/opac/es-ES.po

*American English is built into Evergreen so you do not need to set up this language and there are no PO files.

30.3.1. Updating translations in Evergreen using current translations from Launchpad

Due to Evergreen release workflow/schedule, some language strings may already have been translated in Launchpad, but are not yet packaged with Evergreen. In such cases, it is possible to manually replace the PO file in Evergreen with an up-to-date PO file downloaded from Launchpad.

Visit the Evergreen translation site in Launchpad

Select required language (e.g. Czech or Spanish)

Open the tpac template and then select option Download translation. Note: to be able to download the translation file you need to be logged in to Launchpad.

Select PO format and submit the request for download button. You can also request for download of all existitng templates and languages at once, see https://translations.launchpad.net/evergreen/master/+export. The download link will be sent You to email address provided.

Download the file and name it according to the language used (e.g., cs-CZ.po for Czech or es-ES.po for Spanish)

Copy the downloaded file to /openils/var/template/data/locale. It is a good practice to backup the original PO file before.

Be sure that the desired language is set as default, using the Default language procedures.

Analogously, to update the web staff client translations, download the translation template webstaff and copy it to openils/var/template/data/locale/staff.

Changes require web server reload to take effect. As root run the command

service apache2 restart

30.4. Editing the formats select box options in the search interface.

You may wish to remove, rename or organize the options in the formats select box. This can be accomplished from the staff client.

From the staff client, navigate to Admin > Server Administration > Marc Coded Value Maps

Select Type from the Record Attribute Type select box.

Double click on the format type you wish to edit.

To change the label for the type, enter a value in the Search Label field.

To move the option to a top list separated by a dashed line from the others, check the Is Simple Selector check box.

To hide the type so that it does not appear in the search interface, uncheck the OPAC Visible checkbox.

Changes will be immediate.

30.5. Adding and removing search fields in advanced search

It is possible to add and remove search fields on the advanced search page by editing the opac/parts/config.tt2 file in your template directory. Look for this section of the file:

search.adv_config = [
    {adv_label => l("Item Type"), adv_attr => ["mattype", "item_type"]},
    {adv_label => l("Item Form"), adv_attr => "item_form"},
    {adv_label => l("Language"),  adv_attr => "item_lang"},
    {adv_label => l("Audience"),  adv_attr => ["audience_group", "audience"], adv_break => 1},
    {adv_label => l("Video Format"), adv_attr => "vr_format"},
    {adv_label => l("Bib Level"), adv_attr => "bib_level"},
    {adv_label => l("Literary Form"), adv_attr => "lit_form", adv_break => 1},
    {adv_label => l("Search Library"), adv_special => "lib_selector"},
    {adv_label => l("Publication Year"), adv_special => "pub_year"},
    {adv_label => l("Sort Results"), adv_special => "sort_selector"},
];

For example, if you delete the line:

{adv_label => l("Language"),  adv_attr => "item_lang"},

the language field will no longer appear on your advanced search page. Changes will appear immediately after you save your changes.

You can also add fields based on Search Facet Groups that you create in the staff client’s Local Administration menu. This can be helpful if you want to simplify your patrons' experience by presenting them with only certain limiters (e.g. the most commonly used languages in your area). To do this,

Click Admin → Local Administration → Search Facet Groups.

Click New.

Enter descriptive values into the code and label fields. The owner needs to be set to your consortium.

Once the Facet Group is created, click on the blue hyperlinked code value.

Click the New button to create the necessary values for your field.

Go to the opac/parts/config.tt2 file, and add a line like the following, where Our Library’s Field is the name you’d like to be displayed next to your field, and facet_group_code is the code you’ve added using the staff client.

 {adv_label => l("Our Library's Field"), adv_filter => "facet_group_code"},

30.6. Changing the display of facets and facet groups

Facets can be reordered on the search results page by editing the opac/parts/config.tt2 file in your template directory.

Edit the following section of config.tt2, changing the order of the facet categories according to your needs:

facet.display = [
    {facet_class => 'author',  facet_order => ['personal', 'corporate']},
    {facet_class => 'subject', facet_order => ['topic']},
    {facet_class => 'series',  facet_order => ['seriestitle']},
    {facet_class => 'subject', facet_order => ['name', 'geographic']}
];

You may also change the default number of facets appearing under each category by editing the facet.default_display_count value in config.tt2. The default value is 5.

30.7. Change Date Format in Patron Account View

Libraries with same-day circulations may want their patrons to be able to view the due time as well as due date when they log in to their OPAC account. To accomplish this, go to opac/myopac/circs.tt2. Find the line that reads:

[% date.format(due_date, DATE_FORMAT) %]

Replace it with:

[% date.format(due_date, '%D %I:%M %p') %]

30.8. Including External Content in Your Public Interface

The public interface allows you to include external services and content in your public interface. These can include book cover images, user reviews, table of contents, summaries, author notes, annotations, user suggestions, series information among other services. Some of these services are free while others require a subscription.

The following are some of the external content services which you can configure in Evergreen.

30.8.1. OpenLibrary

The default install of Evergreen includes OpenLibrary book covers. The settings for this are controlled by the <added_content> section of /openils/conf/opensrf.xml. Here are the key elements of this configuration:

<module>OpenILS::WWW::AddedContent::OpenLibrary</module>

This section calls the OpenLibrary perl module. If you wish to link to a different book cover service other than OpenLibrary, you must refer to the location of the corresponding Perl module. You will also need to change other settings accordingly.

<timeout>1</timeout>

Max number of seconds to wait for an added content request to return data. Data not returned within the timeout is considered a failure.

<retry_timeout>600</retry_timeout>

This setting is the amount of time to wait before we try again.

<max_errors>15</max_errors>

Maximum number of consecutive lookup errors a given process can have before added content lookups are disabled for everyone. To adjust the site of the cover image on the record details page edit the config.tt2 file and change the value of the record.summary.jacket_size. The default value is "medium" and the available options are "small", "medium" and "large."

30.8.2. ChiliFresh

ChiliFresh is a subscription-based service which allows book covers, reviews and social interaction of patrons to appear in your catalog. To activate ChiliFresh, you will need to open the Apache configuration file /etc/apache2/eg_vhost.conf and edit several lines:

Uncomment (remove the "#" at the beginning of the line) and add your ChiliFresh account number:

#SetEnv OILS_CHILIFRESH_ACCOUNT

Uncomment this line and add your ChiliFresh Profile:

#SetEnv OILS_CHILIFRESH_PROFILE

Uncomment the line indicating the location of the Evergreen JavaScript for ChiliFresh:

#SetEnv OILS_CHILIFRESH_URL http://chilifresh.com/on-site /js/evergreen.js

Uncomment the line indicating the secure URL for the Evergreen JavaScript :

#SetEnv OILS_CHILIFRESH_HTTPS_URL https://secure.chilifresh.com/on-site/js/evergreen.js

30.8.3. Content Café

Content Café is a subscription-based service that can add jacket images, reviews, summaries, tables of contents and book details to your records.

In order to activate Content Café, edit the /openils/conf/opensrf.xml file and change the <module> element to point to the ContentCafe Perl Module:

<module>OpenILS::WWW::AddedContent::ContentCafe</module>

To adjust settings for Content Café, edit a couple of fields with the <ContentCafe> Section of /openils/conf/opensrf.xml.

Edit the userid and password elements to match the user id and password for your Content Café account.

This provider retrieves content based on ISBN or UPC, with a default preference for ISBNs. If you wish for UPCs to be preferred, or wish one of the two identifier types to not be considered at all, you can change the "identifier_order" option in opensrf.xml. When the option is present, only the identifier(s) listed will be sent.

30.8.4. Obalkyknih.cz

30.8.4.1. Setting up Obalkyknih.cz account

If your library wishes to use added content provided by Obalkyknih.cz, a service based in the Czech Republic, you have to create an Obalkyknih.cz account. Please note that the interface is only available in Czech. After logging in your Obalkyknih.cz account, you have to add your IP address and Evergreen server address to your account settings. (In case each library uses an address of its own, all of these addresses have to be added.)

30.8.4.2. Enabling Obalkyknih.cz in Evergreen

Set obalkyknih_cz.enabled to true in /openils/var/templates/opac/parts/config.tt2:

obalkyknih_cz.enabled = 'true';

Enable added content from Obalkyknih.cz in /openils/conf/opensrf.xml configuration file (and – at the same time – disable added content from Open Library, i.e., Evergreen’s default added content provider):

<!-- <module>OpenILS::WWW::AddedContent::OpenLibrary</module> -->
<module>OpenILS::WWW::AddedContent::ObalkyKnih</module>

Using default settings for Obalkyknih.cz means all types of added content from Obalkyknih.cz are visible in your online catalog. If the module is enabled, book covers are always displayed. Other types of added content (summaries, ratings or tables of contents) can be:

switched off using false option,

switched on again using true option.

The following types of added content are used:

summary (or annotation)

tocPDF (table of contents available as image)

tocText (table of contents available as text)

review (user reviews)

An example of how to switch off summaries:

<summary>false</summary>

30.8.5. Google Analytics

Google Analytics is a free service to collect statistics for your Evergreen site. Statistic tracking is disabled by default through the Evergreen client software when library staff use your site within the client, but active when anyone uses the site without the client. This was a preventive measure to reduce the potential risks for leaking patron information. In order to use Google Analytics you will first need to set up the service from the Google Analytics website at http://www.google.com/analytics/. To activate Google Analytics you will need to edit config.tt2 in your template. To enable the service set the value of google_analytics.enabled to true and change the value of google_analytics.code to be the code in your Google Analytics account.

30.8.6. NoveList

Novelist is a subscription-based service providing reviews and recommendation for books in you catalog. To activate your Novelist service in Evergreen, open the Apache configuration file /etc/apache2/eg_vhost.conf and edit the line:

#SetEnv OILS_NOVELIST_URL

You should use the URL provided by NoveList.

30.8.7. RefWorks

RefWorks is a subscription-based online bibliographic management tool. If you have a RefWorks subscription, you can activate RefWorks in Evergreen by editing the config.tt2 file located in your template directory. You will need to set the ctx.refworks.enabled value to true. You may also set the RefWorks URL by changing the ctx.refworks.url setting on the same file.

30.8.8. SFX OpenURL Resolver

An OpenURL resolver allows you to find electronic resources and pull them into your catalog based on the ISBN or ISSN of the item. In order to use the SFX OpenURL resolver, you will need to subscribe to the Ex Libris SFX service. To activate the service in Evergreen edit the config.tt2 file in your template. Enable the resolver by changing the value of openurl.enabled to true and change the openurl.baseurl setting to point to the URL of your OpenURL resolver.

30.8.9. Syndetic Solutions

Syndetic Solutions is a subscription service providing book covers and other data for items in your catalog. In order to activate Syndetic, edit the /openils/conf/opensrf.xml file and change the <module> element to point to the Syndetic Perl Module:

<module>OpenILS::WWW::AddedContent::Syndetic</module>

You will also need to edit the <userid> element to be the user id provided to you by Syndetic.

Then, you will need to uncomment and edit the <base_url> element so that it points to the Syndetic service:

<base_url>http://syndetics.com/index.aspx</base_url>

For changes to be activated for your public interface you will need to restart Evergreen and Apache.

The Syndetic Solutions provider retrieves images based on the following identifiers found in bibliographic records:

ISBN

UPC

ISSN

30.8.10. Clear External/Added Content Cache

On the catalog’s record summary page, there is a link for staff that will forcibly clear the cache of the Added Content for that record. This is helpful for when the Added Content retrieved the wrong cover jacket art, summary, etc. and caches the wrong result.

Once clicked, there is a pop up that will display what was cleared from the cache.

You will need to reload the record in the staff client to obtain the new images from your Added Content Supplier.

30.8.11. Configure a Custom Image for Missing Images

You can configure a "no image" image other than the standard 1-pixel blank image. The example eg_vhost.conf file provides examples in the comments. Note: Evergreen does not provide default images for these.

30.9. Including Locally Hosted Content in Your Public Interface

It is also possible to show added content that has been generated locally by placing the content in a specific spot on the web server. It is possible to have local book jackets, reviews, TOC, excerpts or annotations.

30.9.1. File Location and Format

By default the files will need to be placed in directories under /openils/var/web/opac/extras/ac/ on the server(s) that run Apache.

The files need to be in specific folders depending on the format of the added content. Local Content can only be looked up based on the record ID at this time.

URL Format: http://catalog/opac/extras/ac/{type}/{format}/r/{recordid}

type is one of jacket, reviews, toc, excerpt or anotes.

format is type dependent:

for jacket, one of small, medium or large

others, one of html, xml or json … html is the default for non-image added content

recordid is the bibliographic record id (bre.id).

30.9.2. Example

If you have some equipment that you are circulating such as a laptop or eBook reader and you want to add an image of the equipment that will show up in the catalog.

If you are adding jacket art for a traditional type of media (book, CD, DVD) consider adding the jacket art to the http://openlibrary.org project instead of hosting it locally. This would allow other libraries to benefit from your work.

Make note of the Record ID of the bib record. You can find this by looking at the URL of the bib in the catalog. http://catalog/eg/opac/record/123, 123 is the record ID. These images will only show up for one specific record.

Create 3 different sized versions of the image in png or jpg format.

Small - 80px x 80px - named 123-s.jpg or 123-s.png - This is displayed in the browse display.

Medium - 240px x 240px - named 123-m.jpg or 123-m.png - This is displayed on the summary page.

Large - 400px x 399px - named 123-l.jpg or 123-l.png - This is displayed if the summary page image is clicked on.

The image dimensions are up to you, use what looks good in your catalog.

Next, upload the images to the evergreen server(s) that run apache, and move/rename the files to the following locations/name. You will need to create directories that are missing.

Small - Move the file 123-s.jpg to /openils/var/web/opac/extras/ac/jacket/small/r/123

Medium - Move the file 123-m.jpg to /openils/var/web/opac/extras/ac/jacket/medum/r/123.

Large - Move the file 123-l.jpg to /openils/var/web/opac/extras/ac/jacket/large/r/123.

The system doesn’t need the file extension to know what kind of file it is.

Reload the bib record summary in the web catalog and your new image will display.

30.10. Sitemap generator

A sitemap directs search engines to the pages of interest in a web site so that the search engines can intelligently crawl your site. In the case of Evergreen, the primary pages of interest are the bibliographic record detail pages.

The sitemap generator script creates sitemaps that adhere to the http://sitemaps.org specification, including:

limiting the number of URLs per sitemap file to no more than 50,000 URLs;

providing the date that the bibliographic record was last edited, so that once a search engine has crawled all of your sites' record detail pages, it only has to reindex those pages that are new or have changed since the last crawl;

generating a sitemap index file that points to each of the sitemap files.

30.10.1. Running the sitemap generator

The sitemap_generator script must be invoked with the following argument:

--lib-hostname: specifies the hostname for the catalog (for example, --lib-hostname https://catalog.example.com); all URLs will be generated appended to this hostname

Therefore, the following arguments are useful for generating multiple sitemaps per Evergreen instance:

--lib-shortname: limit the list of record URLs to those which have copies owned by the designated library or any of its children;

--prefix: provides a prefix for the sitemap index file names

Other options enable you to override the OpenSRF configuration file and the database connection credentials, but the default settings are generally fine.

Note that on very large Evergreen instances, sitemaps can consume hundreds of megabytes of disk space, so ensure that your Evergreen instance has enough room before running the script.

30.10.2. Scheduling

To enable search engines to maintain a fresh index of your bibliographic records, you may want to include the script in your cron jobs on a nightly or weekly basis.

Sitemap files are generated in the same directory from which the script is invoked, so a cron entry will look something like:

12 2 * * * cd /openils/var/web && /openils/bin/sitemap_generator

30.11. Troubleshooting TPAC errors

If there is a problem such as a TT syntax error, it generally shows up as an ugly server failure page. If you check the Apache error logs, you will probably find some solid clues about the reason for the failure. For example, in the following example, the error message identifies the file in which the problem occurred as well as the relevant line numbers.

Example error message in Apache error logs:

bash# grep "template error" /var/log/apache2/error_log
[Tue Dec 06 02:12:09 2011] [warn] [client 127.0.0.1] egweb: template error:
 file error - parse error - opac/parts/record/summary.tt2 line 112-121:
  unexpected token (!=)\n  [% last_cn = 0;\n        FOR copy_info IN
  ctx.copies;\n            callnum = copy_info.call_number_label;\n

Chapter 31. Borrowing items: who, what, for how long

Circulation policies pull together user, library, and item data to determine how library materials circulate, such as: which patrons, from what libraries can borrow what types of materials, for how long, and with what overdue fines.

Individual elements of the circulation policies are configured using specific interfaces, and should be configured prior to setting up the circulation policies.

31.1. Data elements that affect your circulation policies

There are a few data elements which must be considered when setting up your circulation policies.

31.1.1. Copy data

Several fields set via the copy editor are commonly used to affect the circulation of an item.

Circulation modifier - Circulation modifiers are fields used to control circulation policies on specific groups of items. They can be added to copies during the cataloging process. New circulation modifiers can be created in the staff client by navigating to Admin > Server Administration > Circulation Modifiers.

Circulate? flag - The circulate? flag in the copy editor can be set to False to disallow an item from circulating.

Reference? flag - The reference? flag in the copy editor can also be used as a data element in circulation policies.

31.1.2. Copy location data

To get to the Copy Locations Editor, navigate to Admin > Local Administration > Copy Locations Editor.

Set OPAC Visible to "No" to hide all copies in a copy location from the public catalog. (You can also hide individual copies using the Copy Editor.)

Set Hold Verify to "Yes" if when a copy checks in you want to always ask for staff confirmation before capturing a hold.

Set Checkin Alert to "Yes" to allow routing alerts to display when copies are checked in.

Set Holdable to "No" to prevent copies in an entire copy location from being placed on hold.

Set Circulate to "No" to disallow circulating copies in an entire copy location.

If you delete a copy location, it will be removed from display in the staff client and the catalog, but it will remain in the database. This allows you to treat a copy location as deleted without losing statistical information for circulations related to that copy location.

Copy locations can also be used as a data element in circulation policies.

31.1.3. User data

Finally, several characteristics of specific patrons can affect circulation policies. You may modify these characteristics in Search → Search for Patrons or Circulation → Register Patron.

The user permission group is also commonly used as a data element in circulation policies.

Other user data that can be used for circulation policies include the juvenile flag in the user record.

31.2. Circulation Rules

Loan duration describes the length of time for a checkout. You can also identify the maximum renewals that can be placed on an item.

You can find Circulation Duration Rules by navigating to Admin > Server Administration > Circulation Duration Rules.

Recurring fine describes the amount assessed for daily and hourly fines as well as fines set for other regular intervals. You can also identify any grace periods that should be applied before the fine starts accruing.

You can find Recurring Fine Rules by navigating to Admin > Server Administration > Circulation Recurring Fine Rules.

Max fine describes the maximum amount of fines that will be assessed for a specific circulation. Set the Use Percent field to True if the maximum fine should be a percentage of the item’s price.

You can find Circ Max Fine Rules by navigating to Admin > Server Administration > Circulation Max Fine Rules.

These rules generally cause the most variation between organizational units.

Loan duration and recurring fine rate are designed with 3 levels: short, normal, and extended loan duration, and low, normal, and high recurring fine rate. These values are applied to specific items, when copy records are created.

When naming these rules, give them a name that clearly identifies what the rule does. This will make it easier to select the correct rule when creating your circ policies.

31.2.1. Circulation Limit Sets

Circulation Limit Sets allow you to limit the maximum number of copies for different types of materials that a patron can check out at one time. Evergreen supports creating these limits based on circulation modifiers, copy locations, or circ limit groups, which allow you to create limits based on MARC data. The below instructions will allow you to create limits based on circulation modifiers.

Configure the circulation limit sets by selecting Admin > Local Administration > Circulation Limit Sets.

Items Out - the maximum number of items circulated to a patron at the same time.

Depth - Enter the Min Depth, or the minimum depth, in the org tree that Evergreen will consider as valid circulation libraries for counting items out. The min depth is based on org unit type depths. For example, if you want the items in all of the circulating libraries in your consortium to be eligible for restriction by this limit set when it is applied to a circulation policy, then enter a zero (0) in this field.

Global - Check the box adjacent to Global Flag if you want all of the org units in your consortium to be restricted by this limit set when it is applied to a circulation policy. Otherwise, Evergreen will only apply the limit to the direct ancestors and descendants of the owning library.

Linked Limit Groups - add any circulation modifiers, copy locations, or circ limit groups that should be part of this limit set.

Example Your library (BR1) allows patrons to check out up to 5 videos at one time. This checkout limit should apply when your library’s videos are checked out at any library in the consortium. Items with DVD, BLURAY, and VHS circ modifiers should be included in this maximum checkout count.

To create this limit set, you would add 5 to the Items Out field, 0 to the Depth field and select the Global Flag. Add the DVD, BLURAY and VHS circ modifiers to the limit set.

31.3. Creating Circulation Policies

Once you have identified your data elements that will drive circulation policies and have created your circulation rules, you are ready to begin creating your circulation policies.

If you are managing a small number of rules, you can create and manage circulation policies in the staff client via Admin > Local Administration > Circulation Policies. However, if you are managing a large number of policies, it is easier to create and locate rules directly in the database by updating config.circ_matrix_matchpoint.

The config.circ_matrix_matchpoint table is central to the configuration of circulation parameters. It collects the main set of data used to determine what rules apply to any given circulation. It is useful for us to think of their columns in terms of match columns, those that are used to match the particulars of a given circulation transaction, and result columns, those that return the various parameters that are applied to the matching transaction.

Circulation policies by checkout library or owning library?

If your policies should follow the rules of the library that checks out the item, select the checkout library as the Org Unit(org_unit).

If your policies should follow the rules of the library that owns the item, select the consortium as the Org Unit (org_unit) and select the owning library as the Copy Circ Lib (copy_circ_lib).

Renewal policies can be created by setting Renewals? (is_renewal) to True.

You can apply the duration rules, recurring fine rules, maximum fine rules, and circulation sets created in the above sets when creating the circulation policy.

31.3.1. Best practices for creating policies

Start by replacing the default consortium-level circ policy with one that contains a majority of your libraries' duration, recurring fine, and max fine rules. This first rule will serve as a default for all materials and permission groups.

If many libraries in your consortium have rules that differ from the default for particular materials or people, set a consortium-wide policy for that circ modifier or that permission group.

After setting these consortium defaults, if a library has a circulation rule that differs from the default, you can then create a rule for that library. You only need to change the parameters that are different from the default parameters. The rule will inherit the values for the other parameters from that default consortium rule.

Try to avoid unnecessary repetition.

Try to get as much agreement as possible among the libraries in your consortium.

Example 1

In this example, the consortium has decided on a 21_day_2_renew loan rule for general materials, i.e. books, etc. Most members do not charge overdue fines. System 1 charges 25 cents per day to a maximum of $3.00, but otherwise uses the default circulation duration.

Example 2

This example includes a basic set of fields and creates a situation where items with a circ modifier of "book" or "music" can be checked out, but "dvd" items will not circulate. The associated rules would apply during checkouts.

Example 3

This example builds on the earlier example and adds some more complicated options.

It is still true that "book" and "music" items can be checked out, while "dvd" is not circulated. However, now we have added new rules that state that "Adult" patrons of "SYS1" can circulate "dvd" items.

31.3.2. Settings Relevant to Circulation

The following circulation settings, available via Admin > Local Administration > Library Settings Editor, can also affect your circulation duration, renewals and fine policy.

Auto-Extend Grace Periods - When enabled, grace periods will auto-extend. By default this will be only when they are a full day or more and end on a closed date, though other options can alter this.

Auto-Extending Grace Periods extend for all closed dates - If enabled and Grace Periods auto-extending is turned on, grace periods will extend past all closed dates they intersect, within hard-coded limits.

Auto-Extending Grace Periods include trailing closed dates - If enabled and Grace Periods auto-extending is turned on, grace periods will include closed dates that directly follow the last day of the grace period.

Checkout auto renew age - When an item has been checked out for at least this amount of time, an attempt to check out the item to the patron that it is already checked out to will simply renew the circulation.

Cap Max Fine at Item Price - This prevents the system from charging more than the item price in overdue fines.

Lost Item Billing: New Min/Max Price Settings - Patrons will be billed at least the Min Price and at most the Max price, even if the item’s price is outside that range. To set a fixed price for all lost items, set min and max to the same amount.

Charge fines on overdue circulations when closed - Normally, fines are not charged when a library is closed. When set to True, fines will be charged during scheduled closings and normal weekly closed days.

Chapter 32. Hard due dates

This feature allows you to specify a specific due date within your circulation policies. This is particularly useful for academic and school libraries, who may wish to make certain items due at the end of a semester or term.

To work with hard due dates, you will need the CREATE_CIRC_DURATION, UPDATE_CIRC_DURATION, and DELETE_CIRC_DURATION permissions at the consortium level.

32.1. Creating a hard due date

Setting up hard due dates is a two-step process. You must first create a hard due date, and then populate it with specific values.

To create a hard due date:

Click Admin → Server Administration → Hard Due Date Changes.

Click New Hard Due Date.

In the Name field, enter a name for your hard due date. Note that each hard due date can have multiple values, so it’s best to use a generic name here, such as "End of semester."

In the Owner field, select the appropriate org unit for your new hard due date.

In the Current Ceiling Date field, select any value. This field is required, but its value will be overwritten in subsequent steps, so you may enter an arbitrary date here.

Check the Always Use? checkbox if you want items to only receive the due dates you specify, regardless of when they would ordinarily be due. If you leave this box unchecked, your specified due dates will serve as "ceiling" values that limit, rather than override, other circulation rules. In other words, with this box checked, items may be due only on the specified dates. With the box unchecked, items may be due on or before the specified dates, simply not after.

Click Save.

To add date values to your hard due date:

Click the hyperlinked name of the due date you just created.

Click on New Hard Due Date Value

In the Ceiling Date field, enter the specific date you would like items to be due.

In the Active Date field, enter the date you want this specific due date value to take effect.

Click Save.

Each Hard Due Date can include multiple values. For example, you can repeat these steps to enter specific due dates for several semesters using this same screen.

After creating a hard due date and assigning it values, you can apply it by adding it to a circulation policy.

Chapter 33. TPac Configuration and Customization

33.1. Template toolkit documentation

For more general information about template toolkit see: official documentation.

The purpose of this chapter is to focus on the Evergreen-specific uses of Template Toolkit (TT) in the OPAC.

33.2. TPAC URL

The URL for the TPAC on a default Evergreen system is http://localhost/eg/opac/home (adjust localhost to match your hostname or IP address, naturally!)

33.3. Perl modules used directly by TPAC

Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader.pm

Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Account.pm

Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Container.pm

Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Record.pm

Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Search.pm

Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/Util.pm

33.4. Default templates

The source template files are found in Open-ILS/src/templates/opac.

These template files are installed in /openils/var/templates/opac.

NOTE. You should generally avoid touching the installed default template files, unless you are contributing changes that you want Evergreen to adopt as a new default. Even then, while you are developing your changes, consider using template overrides rather than touching the installed templates until you are ready to commit the changes to a branch. See below for information on template overrides.

33.5. Apache configuration files

The base Evergreen configuration file on Debian-based systems can be found in /etc/apache2/sites-enabled/eg.conf. This file defines the basic virtual host configuration for Evergreen (hostnames and ports), then single-sources the bulk of the configuration for each virtual host by including /etc/apache2/eg_vhost.conf.

33.6. TPAC CSS and media files

The CSS files used by the default TPAC templates are stored in the repo in Open-ILS/web/css/skin/default/opac/ and installed in /openils/var/web/css/skin/default/opac/.

The media files—mostly PNG images—used by the default TPAC templates are stored in the repo in Open-ILS/web/images/ and installed in /openils/var/web/images/.

33.7. Mapping templates to URLs

The mapping for templates to URLs is straightforward. Following are a few examples, where <templates> is a placeholder for one or more directories that will be searched for a match:

http://localhost/eg/opac/home ⇒ /openils/var/<templates>/opac/home.tt2

http://localhost/eg/opac/advanced ⇒ /openils/var/<templates>/opac/advanced.tt2

http://localhost/eg/opac/results ⇒ /openils/var/<templates>/opac/results.tt2

The template files themselves can process, be wrapped by, or include other template files. For example, the home.tt2 template currently involves a number of other template files to generate a single HTML file:

Example Template Toolkit file: opac/home.tt2. 

[%  PROCESS "opac/parts/header.tt2";
    WRAPPER "opac/parts/base.tt2";
    INCLUDE "opac/parts/topnav.tt2";
    ctx.page_title = l("Home") %]
    <div id="search-wrapper">
        [% INCLUDE "opac/parts/searchbar.tt2" %]
    </div>
    <div id="content-wrapper">
        <div id="main-content-home">
            <div class="common-full-pad"></div>
            [% INCLUDE "opac/parts/homesearch.tt2" %]
            <div class="common-full-pad"></div>
        </div>
    </div>
[% END %]

We will dissect this example in some more detail later, but the important thing to note is that the file references are relative to the top of the template directory.

33.8. How to override templates

Overrides for templates go in a directory that parallels the structure of the default templates directory. The overrides then get pulled in via the Apache configuration.

In the following example, we demonstrate how to create a file that overrides the default "Advanced search page" (advanced.tt2) by adding a new templates directory and editing the new file in that directory.

Adding an override for the Advanced search page (example). 

bash$ mkdir -p /openils/var/templates_custom/opac
bash$ cp /openils/var/templates/opac/advanced.tt2 \
         /openils/var/templates_custom/opac/.
bash$ vim /openils/var/templates_custom/opac/advanced.tt2

We now need to teach Apache about the new templates directory. Open eg.conf and add the following <Location /eg> element to each of the <VirtualHost> elements in which you want to include the overrides. The default Evergreen configuration includes a VirtualHost directive for port 80 (HTTP) and another one for port 443 (HTTPS); you probably want to edit both, unless you want the HTTP user experience to be different from the HTTPS user experience.

Configuring the custom templates directory in Apache’s eg.conf. 

<VirtualHost *:80>
    # <snip>

    # - absorb the shared virtual host settings
    Include eg_vhost.conf
    <Location /eg>
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_algoma"
    </Location>

    # <snip>
</VirtualHost>

Finally, reload the Apache configuration to pick up the changes:

Reloading the Apache configuration. 

bash# /etc/init.d/apache2 reload

You should now be able to see your change at http://localhost/eg/opac/advanced

33.8.1. Defining multiple layers of overrides

You can define multiple layers of overrides, so if you want every library in your consortium to have the same basic customizations, and then apply library-specific customizations, you can define two template directories for each library.

In the following example, we define the template_CONS directory as the set of customizations to apply to all libraries, and template_BR# as the set of customizations to apply to library BR1 and BR2.

As the consortial customizations apply to all libraries, we can add the extra template directory directly to eg_vhost.conf:

Apache configuration for all libraries (eg_vhost.conf). 

# Templates will be loaded from the following paths in reverse order.
PerlAddVar OILSWebTemplatePath "/openils/var/templates"
PerlAddVar OILSWebTemplatePath "/openils/var/templates_CONS"

Then we define a virtual host for each library to add the second layer of customized templates on a per-library basis. Note that for the sake of brevity we only show the configuration for port 80.

Apache configuration for each virtual host (eg.conf). 

<VirtualHost *:80>
    ServerName br1.concat.ca
    DocumentRoot /openils/var/web/
    DirectoryIndex index.html index.xhtml
    Include eg_vhost.conf
    <Location /eg>
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR1"
    </Location>
</VirtualHost>

<VirtualHost *:80>
    ServerName br2.concat.ca
    DocumentRoot /openils/var/web/
    DirectoryIndex index.html index.xhtml
    Include eg_vhost.conf
    <Location /eg>
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_BR2"
    </Location>
</VirtualHost>

33.9. Changing some text in the TPAC

Out of the box, the TPAC includes a number of placeholder text and links. For example, there is a set of links cleverly named Link 1, Link 2, and so on in the header and footer of every page in the TPAC. Let’s customize that for our templates_BR1 skin.

To begin with, we need to find the page(s) that contain the text in question. The simplest way to do that is with the handy utility ack, which is much like grep but with built-in recursion and other tricks. On Debian-based systems, the command is ack-grep as ack conflicts with an existing utility. In the following example, we search for files that contain the text "Link 1":

Searching for text matching "Link 1". 

bash$ ack-grep "Link 1" /openils/var/templates/opac
/openils/var/templates/opac/parts/topnav_links.tt2
4:            <a href="http://example.com">[% l('Link 1') %]</a>

Next, we copy the file into our overrides directory and edit it with vim:

Copying the links file into the overrides directory. 

bash$ cp /openils/var/templates/opac/parts/topnav_links.tt2 \
         /openils/var/templates_BR1/opac/parts/topnav_links.tt2
bash$ vim /openils/var/templates_BR1/opac/parts/topnav_links.tt2

Finally, we edit the link text in opac/parts/header.tt2.

Content of the opac/parts/header.tt2 file. 

<div id="gold-links-holder">
    <div id="gold-links">
        <div id="header-links">
            <a href="http://example.com">[% l('Link 1') %]</a>
            <a href="http://example.com">[% l('Link 2') %]</a>
            <a href="http://example.com">[% l('Link 3') %]</a>
            <a href="http://example.com">[% l('Link 4') %]</a>
            <a href="http://example.com">[% l('Link 5') %]</a>
        </div>
    </div>
</div>

For the most part, the page looks like regular HTML, but note the [%_(" ")%] that surrounds the text of each link. The [% ... %] signifies a TT block, which can contain one or more TT processing instructions. l(" ... "); is a function that marks text for localization (translation); a separate process can subsequently extract localized text as GNU gettext-formatted PO files.

NOTE. As Evergreen supports multiple languages, any customizations to Evergreen’s default text must use the localization function. Also, note that the localization function supports placeholders such as [_1], [_2] in the text; these are replaced by the contents of variables passed as extra arguments to the l() function.

Once we have edited the link and link text to our satisfaction, we can load the page in our Web browser and see the live changes immediately (assuming we are looking at the BR1 overrides, of course).

33.10. Troubleshooting

If there is a problem such as a TT syntax error, it generally shows up as a an ugly server failure page. If you check the Apache error logs, you will probably find some solid clues about the reason for the failure. For example, in the following example the error message identifies the file in which the problem occurred as well as the relevant line numbers:

Example error message in Apache error logs. 

bash# grep "template error" /var/log/apache2/error_log
[Tue Dec 06 02:12:09 2011] [warn] [client 127.0.0.1] egweb: template error:
  file error - parse error - opac/parts/record/summary.tt2 line 112-121:
  unexpected token (!=)\n  [% last_cn = 0;\n        FOR copy_info IN
  ctx.copies;\n            callnum = copy_info.call_number_label;\n

Chapter 34. Creating a New Skin: the Bare Minimum

When you adopt the TPAC as your catalog, you must create a new skin. This involves a combination of overriding template files and setting Apache directives to control the look and feel of your customized TPAC.

34.1. Apache directives

There are a few Apache directives and environment variables of note for customizing TPAC behavior. These directives should generally live within a <vhost> section of your Apache configuration.

OILSWebDefaultLocale specifies which locale to display when a user lands on a page in the TPAC and has not chosen a different locale from the TPAC locale picker. The following example shows the fr_ca locale being added to the locale picker and being set as the default locale:

PerlAddVar OILSWebLocale "fr_ca"
PerlAddVar OILSWebLocale "/openils/var/data/locale/opac/fr-CA.po"
PerlAddVar OILSWebDefaultLocale "fr-CA"

physical_loc is an Apache environment variable that sets the default physical location, used for setting search scopes and determining the order in which copies should be sorted. The following example demonstrates the default physical location being set to library ID 104:

SetEnv physical_loc 104

34.2. Customizing templates

When you install Evergreen, the TPAC templates include many placeholder images, text, and links. You should override most of these to provide your users with a custom experience that matches your library. Following is a list of templates that include placeholder images, text, or links that you should override.

All paths are relative to /openils/var/templates/opac

parts/config.tt2: contains many configuration settings that affect the behavior of the TPAC, including:

hiding the Place Hold button for available items

enabling RefWorks support for citation management

adding OpenURL resolution for electronic resources

enabling Google Analytics tracking for your TPAC

displaying the "Forgot your password?" prompt

controlling the size of cover art on the record details page

defining which facets to display, and in which order

controlling basic and advanced search options

controlling if the "Show More Details" button is visible or activated by default in OPAC search results

hiding phone notification options (useful for libraries that do not do phone notifications)

disallowing password or e-mail changes (useful for libraries that use centralized authentication or single sign-on systems)

displaying a maintenance message in the public catalog and KPAC (this is controlled by the ctx.maintenance_message variable)

displaying previews of books when available from Google Books. This is controlled by the ctx.google_books_preview variable, which is set to 0 by default to protect the privacy of users who might not want to share their browsing behavior with Google.

disabling the "Group Formats and Editions" search. This is controlled by setting the metarecords.disabled variable to 1.

setting the default search to a Group Formats and Editions search. This is done by setting the search.metarecord_default variable to 1.

parts/footer.tt2 and parts/topnav_links.tt2: contains customizable links. Defaults like Link 1 will not mean much to your users!

parts/homesearch.tt2: holds the large Evergreen logo on the home page of the TPAC. Substitute your library’s logo, or if you are adventurous, create a "most recently added items" carousel… and then share your customization with the Evergreen community.

parts/topnav_logo.tt2: holds the small Evergreen logo that appears on the top left of every page in the TPAC. You will also want to remove or change the target of the link that wraps the logo and leads to the Evergreen site.

parts/login/form.tt2: contains some assumptions about terminology and examples that you might prefer to change to be more consistent with your own site’s existing practices. For example, you may not use PIN at your library because you want to encourage users to use a password that is more secure than a four-digit number.

parts/login/help.tt2: contains links that point to http://example.com, images with text on them (which is not an acceptable practice for accessibility reasons), and promises of answers to frequently asked questions that might not exist at your site.

parts/login/password_hint.tt2: contains a hint about your users' password on first login that is misleading if your library does not set the initial password for an account to the last four digits of the phone number associated with the account.

parts/myopac/main_refund_policy.tt2: describes the policy for refunds for your library.

parts/myopac/prefs_hints.tt2: suggests that users should have a valid email on file so they can receive courtesy and overdue notices. If your library does not send out email notices, you should edit this to avoid misleading your users.

myopac/update_password_msg.tt2: defines the password format that needs to be used when setting a user password. If your Evergreen site has set Password format regex in the Library Settings Editor, you should update the language to describe the format that should be used.

password_reset.tt2: in the msg_map section, you might want to change the NOT_STRONG text that appears when the user tries to set a password that does not match the required format. Ideally, this message will tell the user how they should format the password.

parts/css/fonts.tt2: defines the font sizes for the TPAC in terms of one base font size, and all other sizes derived from that in percentages. The default is 12 pixels, but some design sites strongly suggest a base font size of 16 pixels. Perhaps you want to try 1em as a base to respect your users' preferences. You only need to change one number in this file if you want to experiment with different options for your users.

parts/css/colors.tt2: chances are your library’s official colors do not match Evergreen’s wall of dark green. This file defines the colors in use in the standard Evergreen template. In theory you should be able to change just a few colors and everything will work, but in practice you will need to experiment to avoid light-gray-on-white low-contrast combinations.

The following are templates that are less frequently overridden, but some libraries benefit from the added customization options.

parts/advanced/numeric.tt2: defines the search options of the Advanced Search > Numeric search. If you wanted to add a bib call number search option, which is different from the item copy call number; you would add the following code to numeric.tt2.

<option value="identifier|bibcn">[% l('Bib Call Number') %]</option>

Chapter 35. Auto Suggest in Catalog Search

The auto suggest feature suggestions for completing search terms as the user enters his search query. Ten suggestions are the default, but the number of suggestions is configurable at the database level. Scroll through suggestions with your mouse, or use the arrow keys to scroll through the suggestions. Select a suggestion to view records that are linked to this suggestion. This feature is not turned on by default. You must turn it on in the Admin module.

35.1. Enabling this Feature

To enable this feature, click Admin → Server Administration → Global Flags.

Scroll down to item 10, OPAC.

Double click anywhere in the row to edit the fields.

Check the box adjacent to Enabled to turn on the feature.

The Value field is optional. If you checked Enabled in step 4, and you leave this field empty, then Evergreen will only suggest searches for which there are any corresponding MARC records.

If you checked Enabled in step 4, and you enter the string, opac_visible, into this field, then Evergreen will suggest searches for which there are matching MARC records with copies within your search scope. For example, it will suggest MARC records with copies at your branch.

Click Save.

35.2. Using this Feature

Enter search terms into the basic search field. Evergreen will automatically suggest search terms.

Select a suggestion to view records that are linked to this suggestion.

Chapter 36. Authentication Proxy

To support integration of Evergreen with organizational authentication systems, and to reduce the proliferation of user names and passwords, Evergreen offers a service called open-ils.auth_proxy. If you enable the service, open-ils.auth_proxy supports different authentication mechanisms that implement the authenticate method. You can define a chain of these authentication mechanisms to be tried in order within the <authenticators> element of the opensrf.xml configuration file, with the option of falling back to the native mode that uses Evergreen’s internal method of password authentication.

This service only provides authentication. There is no support for automatic provisioning of accounts. To authenticate using any authentication system, the user account must first be defined in the Evergreen database. The user will be authenticated based on the Evergreen username and must match the user’s ID on the authentication system.

In order to activate Authentication Proxy, the Evergreen system administrator will need to complete the following steps:

Edit opensrf.xml.

Set the open-ils.auth_proxy app settings enabled tag to true

Add the authenticator to the list of authenticators or edit the existing example authenticator:

<authenticator>
        <name>ldap</name>
        <module>OpenILS::Application::AuthProxy::LDAP_Auth</module>
        <hostname>name.domain.com</hostname>
        <basedn>ou=people,dc=domain,dc=com</basedn>
        <authid>cn=username,ou=specials,dc=domain,dc=com</authid>
        <id_attr>uid</id_attr>
        <password>my_ldap_password_for_authid_user</password>
        <login_types>
                <type>staff</type>
                <type>opac</type>
        </login_types>
        <org_units>
                <unit>103</unit>
                <unit>104</unit>
        </org_units>
</authenticator>

name : Used to identify each authenticator.

module : References to the perl module used by Evergreen to process the request.

hostname : Hostname of the authentication server.

basedn : Location of the data on your authentication server used to authenticate users.

authid : Administrator ID information used to connect to the Authentication server.

id_attr : Field name in the authenticator matching the username in the Evergreen database.

password : Administrator password used to connect to the authentication server. Password for the authid.

login_types : Specifies which types of logins will use this authenticator. This might be useful if staff use a different LDAP directory than general users.

org_units : Specifies which org units will use the authenticator. This is useful in a consortium environment where libraries will use separate authentication systems.

Restart Evergreen and Apache to activate configuration changes.

If using proxy authentication with library employees that will use the Admin > Change Operator: New feature in the client software, then add "temp" as a login_types.

Chapter 37. Kid’s OPAC Configuration

37.1. Configuration

37.1.1. Apache

The KPAC is already included and ready to be used with new Evergreen installs. So you only need to change the apache config if you need to change template locations or if you want to use a different kpac.xml config file. The defaults for the KPAC are set in /etc/apache2/eg_vhosts.conf.

<Location /eg/kpac>
    PerlSetVar OILSWebContextLoader "OpenILS::WWW::EGKPacLoader"
    PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example"
</Location>

37.1.2. XML Configuration File

The XML configuration file defines the layout of the kid’s OPAC.

It is read with each restart/reload of the Apache web server.

The file lives by default at /openils/conf/kpac.xml.example

There are two top-level elements: <pages> and <layout>.

The layout defines the owning org unit and the start page, both by ID.

At runtime, the layout is determined by the context org unit. If no configuration is defined for the context org unit, the layout for the closest ancestor is used.

<layout owner="1" page="1"/>

The pages section is a container for <page> elements.

Each page defines an ID, the number of columns to display for the page, the page name, and an icon.

<page id="1" columns="5" name="Home" img="/images/home.jpg">

Each page is a container of cells

Each cell defines

type (topic, search, link)

name

icon

content

The content for type="topic" cells is the ID of the page this topic jumps to. The name and img for the referenced page is used as the display content.

<cell type="topic">12</cell>

The content for type="search" cells is the search query. The name and img are used for the display content.

<cell name="Piano" img="category.png" type="search">su:piano</cell>

The content for type="link" cells is the URL. The name and img are used for the display content.

<cell name="Clarinet" img="category.png"
    type="link">http://en.wikipedia.org/wiki/Clarinet</cell>

37.1.3. Skin Configuration

The following example enables you to configure the alternate skin (Monster Skin, kpac2) for the Kids Catalog.

You should be familiar with how the Evergreen TPAC handles template folders before you make these changes.

If you already have a custom template directory setup you can copy the Open-ILS/examples/web/templates/kpac files to that directory instead, and then skip any Apache config changes.

% cp -r Open-ILS/examples/web/css/skin/kpac2 /openils/var/web/css/skin/
% cp -r Open-ILS/examples/web/images/kpac/* /openils/var/web/images/kpac/ #does not clobber
% mkdir /openils/var/templates_kpac2
% cp -r Open-ILS/examples/web/templates/kpac /openils/var/templates_kpac2/
% cp -r /openils/var/web/css/skin/default/kpac/fonts /openils/var/web/css/skin/kpac2/kpac

Then set up 443/80 vhosts for serving the alternate skin in eg.conf, something along the lines of:

<VirtualHost *:80>
    ServerName xyz.dev198.esilibrary.com:80
    DocumentRoot /openils/var/web/
    DirectoryIndex index.html index.xhtml
    Include eg_vhost.conf
    <Location /eg/kpac>
        #Point to a different kpac.xml config file if needed
        #PerlSetVar KPacConfigFile "/openils/conf/kpac.xml.example"
        PerlAddVar OILSWebTemplatePath "/openils/var/templates_kpac2"
    </Location>
</VirtualHost>

37.2. Considerations for Community Adoption

The templates for the Kid’s OPAC were developed long before the TPAC was integrated into Evergreen and it has many of the same limitations that were part of the TPAC.

Fixed width elements (divs, images, etc.), which complicates the addition of new features and local customizations.

Images with text, which prevents l10n/i18n.

While the KPAC does not attempt to match the color scheme of any one institution, it’s inconsistent with the standard Evergreen color palette. Creating an additional skin to act as the Evergreen default my be necessary.

37.3. Outstanding Development (Unsponsored)

Port the XML configuration file to a DB structure, complete with UI for managing the various components and upgrade path.

Chapter 38. Customizable Toolbar

By default, two toolbars are available in the staff client: circulation and cataloging. This feature enables you to customize toolbars in the staff client. You can create toolbars for specific org unit(s), workstation(s), or login(s).

38.1. Configure Toolbar

Click Admin → Workstation Administration → Toolbars → Configure Toolbars.

Click New Toolbar.

Enter label for toolbar.

Click Ok.

Select one of the buttons in the Available panel. The Button ID describes that action that the button will take, and the Label will display in the toolbar.

Click the --> (A) button to add the selected function to the Selected panel on the bottom right side of the screen. To remove a button, click the <-- (R) button.

Continue adding buttons if desired. The buttons will display in the order that you add them. If you want to reorder the buttons, click the Up or Down buttons.

To separate buttons onto left and right sides of the screen on the same toolbar, select toolbarspacer, and click --> (A).

To add a dividing line between buttons that appear on the same side of the screen, select toolbarseparator, and click --> (A).

At the bottom of the screen, choose the owner of this toolbar. If you click Owning Org Unit, then the owning org unit that you specify will display this toolbar. Select the owning org unit from the drop down menu. The rule of parental inheritance applies, so all child units will inherit the toolbars of their parental units. If you click Owning Workstation, then the workstation to which you are logged in when you created the toolbar will display this toolbar. If you select Owning User, then your login has access to that toolbar.

When you are finished creating the toolbar, click Save Toolbar. Any toolbar to which you have access displays under Admin → Workstation Administration → Toolbars → Current.

Permissions

ADMIN_TOOLBAR - Allow a user to create, edit, and delete custom toolbars

Chapter 39. Patron Address City/State/County Pre-Populate by ZIP Code

This feature saves staff time and increases accuracy when entering patron address information by automatically filling in the City, State and County information based on the ZIP code entered by the staff member.

Released: Evergreen 0.1, available in all versions.

Please be aware of the following when using this feature.

ZIP codes do not always match 1 to 1 with City, State and County. ZIP codes were designed for postal delivery and represent postal delivery zones that may cover more than one city, state or county.

It is currently only possible to have one match per ZIP code, but you can add an alert to those entries to prompt staff to double check the entered data.

Only the first 5 digits of the ZIP are used. ZIP+4 is not currently supported.

The zips.txt data is loaded once at service startup and stored in memory, so changes to the zips.txt data file require that Evergreen be restarted. Specifically, you need to restart the "open-ils.search" OpenSRF service.

39.1. Scoping and Permissions

There are no staff client permissions associated with this feature since there is no staff client interface.

This feature affects all users of the system; there is no way to have separate settings per Org Unit.

39.2. Setup Steps

39.2.1. Step 1 - Setup Data File

The default location and name of the data file is /openils/var/data/zips.txt on your Evergreen server. You can choose a different location if needed.

The file format of your zips.txt will look like this (delimited by the .):

ID|StateAbb|City|ZIP|IsDefault|StateID|County|AreaCode|AlertMesg

The only fields that are used are StateAbb, City, ZIP, IsDefault, County and AlertMesg.

Most fields can be left blank if the information is not available and that data will not be entered.

Data Field Descriptions

ID - ID field to uniquely identify this row. Not required, can be left blank.

StateAbb - State abbreviation like "MN" or "ND".

City - Name of city.

ZIP - ZIP code, only first 5 digits used.

IsDefault - Must be set to 1 for the row to be used. Easy way to disable/enable a row.

StateID - Unknown and unused.

County - County name.

AreaCode - Phone number area code, unused.

AlertMesg - Message to display to staff to alert them of any special circumstances.

The Address Alerts feature can also be used to alert staff about certain addresses.

Here is an example of what the data file should look like.

Example zips.txt. 

|MN|Moorhead|56561|1||Clay||
|MN|Moorhead|56562|1||Clay||
|MN|Moorhead|56563|1||Clay||
|MN|Sabin|56580|1||Clay||
|MN|Ulen|56585|1||Clay||
|MN|Lake Itasca|56460|1||Clearwater County||
|MN|Bagley|56621|1||Clearwater||
|MN|Clearbrook|56634|1||Clearwater||
|MN|Gonvick|56644|1||Clearwater||

39.2.2. Step 2 - Enable Feature

The next step is to tell the system to use the zips.txt file that you created. This is done by editing /openils/conf/opensrf.xml. Look about halfway into the file and you may very well see a commented section in the file that looks similar to this:

          <!-- zip code database file -->
          <!--<zips_file>/openils/var/data/zips.txt</zips_file>-->
     </app_settings>
</open-ils.search>

Uncomment the area by . .. Change the file path if you placed your file in a different location. The file should look like this after you are done.

          <!-- zip code database file -->
          <zips_file>/openils/var/data/zips.txt</zips_file>
     </app_settings>
</open-ils.search>

Save and Restart. Save your changes to the opensrf.xml file, restart Evergreen and restart Apache.

The specific opensrf services you need to restart are "opensrf.setting" and "open-ils.search".

39.2.3. Step 3 - Test

Open up the staff client and try to register a new patron. When you get to the address section, enter a ZIP code that you know is in your zips.txt file. The data from the file that matches your ZIP will auto fill the city, state and county fields.

39.3. ZIP Code Data

There are several methods you can use to populate your zips.txt with data.

39.3.1. Manual Entry

If you only have a few communities that you serve, entering data manually may be the simplest approach.

39.3.2. Geonames.org Data

Geonames.org provides free ZIP code to city, state and county information licensed under the Creative Commons Attribution 3.0 License, which means you need to put a link to them on your website. Their data includes primary city, state and county information only. It doesn’t include info about which other cities are included in a ZIP code. Visit http://www.geonames.org for more info.

The following code example shows you how to download and reformat the data into the zips.txt format. You have the option to filter the data to only include certain states also.

## How to get a generic Evergreen zips.txt for free
wget http://download.geonames.org/export/zip/US.zip
unzip US.zip
cut -f2,3,5,6 US.txt \
| perl -ne 'chomp; @f=split(/\t/); print "|" . join("|", (@f[2,1,0], "1", "", $f[3], "")), "|\n";' \
> zips.txt

##Optionally filter the data to only include certain states
egrep "^\|(ND|MN|WI|SD)\|" zips.txt  > zips-mn.txt

39.3.3. Commercial Data

There are many vendors that sell databases that include ZIP code to city, state and county information. A web search will easily find them. Many of the commercial vendors will include more information on which ZIP codes cover multiple cities, counties and states, which you could use to populate the alert field.

39.3.4. Existing Patron Database

Another possibility is to use your current patron database to build your zips.txt. Pull out the current ZIP, city, state, county unique rows and use them to form your zips.txt.

Small Sites. For sites that serve a small geographic area (less than 30 ZIP codes), an sql query like the following will create a zips.txt for you. It outputs the number of matches as the first field and sorts by ZIP code and number of matches. You would need to go through the resulting file and deal with duplicates manually.

psql egdb26 -A -t -F $'|' \
 -c "SELECT count(substring(post_code from 1 for 5)) as zipcount, state, \
 city, substring(post_code from 1 for 5) as pc, \
 '1', '', county, '', '' FROM actor.usr_address \
 group by pc, city, state, county \
 order by pc, zipcount DESC" > zips.txt

Larger Sites. For larger sites Ben Ostrowsky at ESI created a pair of scripts that handles deduping the results and adding in county information. Instructions for use are included in the files.

http://git.esilibrary.com/?p=migration-tools.git;a=blob;f=elect_ZIPs

http://git.esilibrary.com/?p=migration-tools.git;a=blob;f=enrich_ZIPs

39.4. Development

If you need to make changes to how this feature works, such as to add support for other postal code formats, here is a list of the files that you need to look at.

Zips.pm - contains code for loading the zips.txt file into memory and replying to search queries. Open-ILS / src / perlmods / lib / OpenILS / Application / Search / Zips.pm

register.js - This is where patron registration logic is located. The code that queries the ZIP search service and fills the address is located here. Open-ILS / web / js / ui / default / actor / user / register.js

Chapter 40. Phonelist.pm Module

PhoneList.pm is a mod_perl module for Apache that works with Evergreen to generate callings lists for patron holds or overdues. It outputs a csv file that can be fed into an auto-dialer script to call patrons with little or no staff intervention. It is accessed and configured via a special URL and passing any parameters as a Query String on the URL. The parameters are listed in the table below.

Table 40.1. Parameters for the phonelist program:

user

Your Evergreen login. Typically your library’s circ account. If you leave this off, you will be prompted to login.

passwd

The password for your Evergreen login. If you leave this off you will be prompted to login.

ws_ou

The ID of the system or branch you want to generate the list for (optional). If your account does not have the appropriate permissions for the location whose ID number you have entered, you will get an error.

skipemail

If present, skip patrons with email notification (optional).

addcount

Add a count of items on hold (optional). Only makes sense for holds.

overdue

Makes a list of patrons with overdues instead of holds. If an additional, numeric parameter is supplied, it will be used as the number of days overdue. If no such extra parameter is supplied, then the default of 14 days is used.

The URL is

https://your.evergreen-server.tld/phonelist

A couple of examples follow:

https://your.evergreen-server.tld/phonelist?user=circuser&passwd=password&skipemail

The above example would sign in as user circuser with password of password and get a list of patrons with holds to call who do not have email notification turned on. It would run at whatever branch is normally associated with circuser.

https://your.evergreen-server.tld/phonelist?skipemail

The above example would do more or less the same, but you would be prompted by your browser for the user name and password.

If your browser or download script support it, you may also use conventional HTTP authentication parameters.

https://user:password@your.evergreen-server.tld/phonelist?overdue&ws_ou=2

The above logs in as user with password and runs overdues for location ID 2.

The following sections provide more information on getting what you want in your output.

40.1. Adding Parameters

If you are not familiar with HTTP/URL query strings, the format is quite simple.

You add parameters to the end of the URL, the first parameter is separated from the URL page with a question mark (?) character. If the parameter is to be given an extra value, then that value follows the parameter name after an equals sign (=). Subsequent parameters are separated from the previous parameter by an ampersand (&).

Here is an example with 1 parameter that has no value:

https://your.evergreen-server.tld/phonelist?skipemail

An example of 1 argument with a value:

https://your.evergreen-server.tld/phonelist?overdue=21

An example of 2 arguments, 1 with a value and 1 without:

https://your.evergreen-server.tld/phonelist?overdue=21&skipemail

Any misspelled or parameters not listed in the table above will be ignored by the program.

40.2. Output

On a successful run, the program will return a CSV file named phone.csv. Depending on your browser or settings you will alternately be prompted to open or save the file. Your browser may also automatically save the file in your Downloads or other designated folder. You should be able to open this CSV file in Excel, LibreOffice Base, any other spread sheet program, or a text editor.

If you have made a mistake and have mistyped your user name or password, or if you supply a ws_ou parameter with an ID where your user name does not have permission to look up holds or overdue information, then you will get an error returned in your browser.

Should your browser appear to do absolutely nothing at all. This is normal. When there is no information for you to download, the server will return a 200 NO CONTENT message to your browser. Most browsers respond to this message by doing nothing at all. It is possible for there to be no information for you to retrieve if you added the skipemail option and all of your notices for that day were sent via email, or if you ran this in the morning and then again in the afternoon and there was no new information to gather.

The program does indicate that it has already looked at a particular hold or overdue and will skip it on later runs. This prevents duplicates to the same patron in the same run. It will, however, create a duplicate for the same patron if a different copy is put on hold for that patron in between two runs.

The specific content of the CSV file will vary if you are looking at holds or overdues. The specific contents are described in the appropriate sections below.

40.3. Holds

The phonelist program will return a list of patrons with copies on hold by default, so long as you do not use the overdue parameter. You may optionally get a number of items that patron currently has on hold by adding the addcount parameter.

As always, you can add the skipemail parameter to skip patrons with email notifications of their overdues, see Skipping patrons with email notification of holds as described below.

Table 40.2. Columns in the holds CSV file:

Name

Patron’s name first and last.

Phone

Patron’s phone number.

Barcode

Patron’s barcode.

Count

Number of copies on hold, if addcount parameter is used, otherwise this column is not present in the file.

40.4. Overdues

If you add the overdue parameter, you can get a list of patrons with overdue copies instead of a list of patrons with copies on the hold shelf. By default, this will give you a list of patrons with copies that are 14 days overdue. If you’d like to specify a different number of days you can add the number after the parameter with an equals sign:

https://your.evergreen-server.tld/phonelist?overdue=21&ws_ou=2

The above will retrieve a list of patrons who have items that are 21 days overdue at the location with ID of 2.

The number of days is an exact lookup. This means that the program will look only at patrons who have items exactly 14 days or exactly the number of days specified overdue. It does not pull up any that are less than or greater than the number of days specified.

As always, you can add the skipemail parameter to skip patrons with email notifications of their overdues, see Skipping patrons with email notification of holds as described below.

Table 40.3. Columns in the overdues CSV file:

Name

Patron’s name first and last.

Phone

Patron’s phone number.

Barcode

Patron’s barcode.

Titles

A colon-separated list of titles that the patron has overdue.

40.5. Skipping patrons with email notification of holds

Skipping patrons who have email notification for their holds or overdues is very simple. You just need to add the skipemail parameter on the URL query string. Doing so will produce the list without the patrons who have email notification for overdues, or for all of their holds. Please note that if a patron has multiple holds available, and even one of these holds requests a phone-only notification, then that patron will still show on the list. For this option to exclude a patron from the holds list, the patron must request email notification on all of their current holds. In practice, we find that this is usually the case.

40.6. Using the ws_ou parameter

Generally, you will not need to use the ws_ou parameter when using the phonelist program. The phonelist will look up the branch where your login account works and use that location when generating the list. However, if you are part of a multi-branch systems in a consortium, then the ws_ou parameter will be of interest to you. You can use it to specify which branch, or the whole system, you wish to search when running the program.

40.7. Automating the download

If you’d like to automate the download of these files, you should be able to do so using any HTTP programming toolkit. Your client must accept cookies and follow any redirects in order to function.

Chapter 41. SIP Server

SIP, standing for Standard Interchange Protocol, was developed by the 3M corporation to be a common protocol for data transfer between ILS' (referred to in SIP as an ACS, or Automated Circulation System) and a third party device. Originally, the protocol was developed for use with 3M SelfCheck (often abbreviated SC, not to be confused with Staff Client) systems, but has since expanded to other companies and devices. It is now common to find SIP in use in several other vendors' SelfCheck systems, as well as other non-SelfCheck devices. Some examples include:

Patron Authentication (computer access, subscription databases)

Automated Material Handling (AMH)

The automated sorting of items, often to bins or book carts, based on shelving location or other programmable criteria

41.1. Installing the SIP Server

This is a rough intro to installing the SIP server for Evergreen.

41.1.1. Getting the code

Current SIP server code lives at in the Evergreen git repository:

cd /opt
git clone git://git.evergreen-ils.org/SIPServer.git SIPServer

41.1.2. Configuring the Server

Type the following commands from the command prompt:

$ sudo su opensrf
$ cd /openils/conf
$ cp oils_sip.xml.example oils_sip.xml

Edit oils_sip.xml. Change the commented out <server-params> section to this:

<server-params
   min_spare_servers='1'
   max_spare_servers='2'
   min_servers='3'
   max_servers='25'
             />

max_servers will directly correspond to the number of allowed SIP clients. Set the number accordingly, but bear in mind that too many connections can exhaust memory. On a 4G RAM/4 CPU server (that is also running evergreen), it is not recommended to exceed 100 SIP client connections.

41.1.3. Adding SIP Users

Type the following commands from the command prompt:

$ sudo su opensrf
$ cd /openils/conf

In the <accounts> section, add SIP client login information. Make sure that all <logins> use the same institution attribute, and make sure the institution is listed in <institutions>. All attributes in the <login> section will be used by the SIP client.

In Evergreen, create a new profile group called SIP. This group should be a sub-group of Users (not Staff or Patrons). Set Editing Permission as group_application.user.sip_client and give the group the following permissions:

COPY_CHECKIN
COPY_CHECKOUT
CREATE_PAYMENT
RENEW_CIRC
VIEW_CIRCULATIONS
VIEW_COPY_CHECKOUT_HISTORY
VIEW_PERMIT_CHECKOUT
VIEW_USER
VIEW_USER_FINES_SUMMARY
VIEW_USER_TRANSACTIONS

OR use SQL like:

INSERT INTO permission.grp_tree (name,parent,description,application_perm)
VALUES ('SIP', 1, 'SIP2 Client Systems', 'group_application.user.sip_client');

INSERT INTO
  permission.grp_perm_map (grp, perm, depth, grantable)
SELECT
  g.id, p.id, 0, FALSE
FROM
  permission.grp_tree g,
  permission.perm_list p
WHERE
  g.name = 'SIP' AND
  p.code IN (
    'COPY_CHECKIN',
    'COPY_CHECKOUT',
    'RENEW_CIRC',
    'VIEW_CIRCULATIONS',
    'VIEW_COPY_CHECKOUT_HISTORY',
    'VIEW_PERMIT_CHECKOUT',
    'VIEW_USER',
    'VIEW_USER_FINES_SUMMARY',
    'VIEW_USER_TRANSACTIONS'
 );

Verify:

SELECT *
FROM permission.grp_perm_map pgpm
    INNER JOIN permission.perm_list ppl ON pgpm.perm = ppl.id
    INNER JOIN permission.grp_tree pgt ON pgt.id = pgpm.grp
WHERE pgt.name = 'SIP';

For each account created in the <login> section of oils_sip.xml, create a user (via the staff client user editor) that has the same username and password and put that user into the SIP group.

The expiration date will affect the SIP users' connection so you might want to make a note of this somewhere.

41.1.4. Running the server

To start the SIP server type the following commands from the command prompt:

$ sudo su opensrf

$ oils_ctl.sh -a [start|stop|restart]_sip

41.1.5. Logging-SIP

41.1.5.1. Syslog

It is useful to log SIP requests to a separate file especially during initial setup by modifying your syslog config file.

Edit syslog.conf.

$ sudo vi /etc/syslog.conf  # maybe /etc/rsyslog.conf

Add this:

local6.*                -/var/log/SIP_evergreen.log

Syslog expects the logfile to exist so create the file.

$ sudo touch /var/log/SIP_evergreen.log

Restart sysklogd.

$ sudo /etc/init.d/sysklogd restart

41.1.5.2. Syslog-NG

Edit logging config.

sudo vi /etc/syslog-ng/syslog-ng.conf

Add:

# +SIP2+ for Evergreen
filter    f_eg_sip { level(warn, err, crit) and facility(local6); };
destination eg_sip { file("var/log/SIP_evergreen.log"); };
log { source(s_all); filter(f_eg_sip); destination(eg_sip); };

Syslog-ng expects the logfile to exist so create the file.

$ sudo touch /var/log/SIP_evergreen.log

Restart syslog-ng

$ sudo /etc/init.d/syslog-ng restart

41.1.6. Testing Your SIP Connection

In the root directory of the SIPServer code:

$ cd SIPServer/t

Edit SIPtest.pm, change the $instid, $server, $username, and $password variables. This will be enough to test connectivity. To run all tests, you’ll need to change all the variables in the Configuration section.

$ PERL5LIB=../ perl 00sc_status.t

This should produce something like:

1..4
ok 1 - Invalid username
ok 2 - Invalid username
ok 3 - login
ok 4 - SC status

Don’t be dismayed at Invalid Username. That’s just one of the many tests that are run.

41.1.7. More Testing

Once you have opened up either the SIP OR SIP2 ports to be accessible from outside you can do some testing via telnet. In the following tests:

Replace $server with your server hostname (or localhost if you want to skip testing external access for now);

Replace $username, $password, and $instid with the corresponding values in the <accounts> section of your SIP configuration file;

Replace the $user_barcode and $user_password variables with the values for a valid user.

Replace the $item_barcode variable with the values for a valid item.

Start by testing your ability to log into the SIP server:

We are using 6001 here which is associated with SIP2 as per our configuration.

$ telnet $server 6001
Connected to $server.
Escape character is '^]'.
9300CN$username|CO$password|CP$instid

If successful, the SIP server returns a 941 result. A result of 940, however, indicates an unsuccessful login attempt. Check the <accounts> section of your SIP configuration and try agin.

Once you have logged in successfully, replace the variables in the following line and paste it into the telnet session:

2300120080623    172148AO$instid|AA$user_barcode|AC$password|AD$user_password

If successful, the SIP server returns the patron information for $user_barcode, similar to the following:

24  Y           00120100113    170738AEFirstName MiddleName LastName|AA$user_barcode|BLY|CQY
|BHUSD|BV0.00|AFOK|AO$instid|

The response declares it is a valid patron BLY with a valid password CQY and shows the user’s $name.

To test the SIP server’s item information response, issue the following request:

1700120080623    172148AO$instid|AB$item_barcode|AC$password

If successful, the SIP server returns the item information for $item_barcode, similar to the following:

1803020120160923    190132AB30007003601852|AJRégion de Kamouraska|CK001|AQOSUL|APOSUL|BHCAD
|BV0.00|BGOSUL|CSCA2 PQ NR46 73R

The response declares it is a valid item, with the title, owning library, permanent and current locations, and call number.

41.2. SIP Communication

SIP generally communicates over a TCP connection (either raw sockets or over telnet), but can also communicate via serial connections and other methods. In Evergreen, the most common deployment is a RAW socket connection on port 6001.

SIP communication consists of strings of messages, each message request and response begin with a 2-digit “command” - Requests usually being an odd number and responses usually increased by 1 to be an even number. The combination numbers for the request command and response is often referred to as a Message Pair (for example, a 23 command is a request for patron status, a 24 response is a patron status, and the message pair 23/24 is patron status message pair). The table in the next section shows the message pairs and a description of them.

For clarification, the “Request” is from the device (selfcheck or otherwise) to the ILS/ACS. The response is… the response to the request ;).

Within each request and response, a number of fields (either a fixed width or separated with a | [pipe symbol] and preceded with a 2-character field identifier) are used. The fields vary between message pairs.

Pair

Name

Supported?

Details

01

Block Patron

Yes

01/Block_Patron - ACS responds with 24 Patron Status Response

09-10

Checkin

Yes (with extensions)

09/10_Checkin

11-12

Checkout

Yes (no renewals)

11/12_Checkout

15-16

Hold

Partially supported

15/16_Hold

17-18

Item Information

Yes (no extensions)

17/18_Item_Information

19-20

Item Status Update

No

19/20_Item_Status_Update - Returns Patron Enable response, but doesn’t make any changes in EG

23-24

Patron Status

Yes

23/24_Patron_Status - 63/64 “Patron Information” preferred

25-26

Patron Enable

No

25/26_Patron_Enable - Used during system testing and validation

29-30

Renew

Yes

29/30_Renew

35-36

End Session

Yes

35/36_End_Session

37-38

Fee Paid

Yes

37/38_Fee_Paid

63-64

Patron Information

Yes (no extensions)

63/64_Patron_Information

65-66

Renew All

Yes

65/66_Renew_All

93-94

Login

Yes

93/94_Login - Must be first command to Evergreen ACS (via socket) or SIP will terminate

97-96

Resend last message

Yes

97/96_Resend

99-98

SC-ACS Status

Yes

99/98_SC_and_ACS_Status

41.2.1. 01 Block Patron

A selfcheck will issue a Block Patron command if a patron leaves their card in a selfcheck machine or if the selfcheck detects tampering (such as attempts to disable multiple items during a single item checkout, multiple failed pin entries, etc).

In Evergreen, this command does the following:

User alert message: CARD BLOCKED BY SELF-CHECK MACHINE (this is independent of the AL Blocked Card Message field).

Card is marked inactive.

The request looks like:

01<card retained><date>[fields AO, AL, AA, AC]

Card Retained: A single character field of Y or N - tells the ACS whether the SC has retained the card (ex: left in the machine) or not.

Date: An 18 character field for the date/time when the block occurred.

Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, “Z” (3 blanks and a Z) represents UTC(GMT/Zulu)

Fields: See Fields for more details.

The response is a 24 “Patron Status Response” with the following:

Charge privileges denied

Renewal privileges denied

Recall privileges denied (hard-coded in every 24 or 64 response)

hold privileges denied

Screen Message 1 (AF): blocked

Patron

41.2.2. 09/10 Checkin

~The request looks like:

09<No block (Offline)><xact date><return date>[Fields AP,AO,AB,AC,CH,BI]

No Block (Offline): A single character field of Y or N - Offline transactions are not currently supported so send N.

xact date: an 18 character field for the date/time when the checkin occurred. Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, “Z” (3 blanks and a Z) represents UTC(GMT/Zulu)

Fields: See Fields for more details.

The response is a 10 “Checkin Response” with the following:

10<resensitize><magnetic media><alert><xact date>[Fields AO,AB,AQ,AJ,CL,AA,CK,CH,CR,CS,CT,CV,CY,DA,AF,AG]

Example (with a remote hold):

09N20100507    16593720100507    165937APCheckin Bin 5|AOBR1|AB1565921879|ACsip_01|

101YNY20100623    165731AOBR1|AB1565921879|AQBR1|AJPerl 5 desktop reference|CK001|CSQA76.73.P33V76 1996
|CTBR3|CY373827|DANicholas Richard Woodard|CV02|

Here you can see a hold alert for patron CY 373827, named DA Nicholas Richard Woodard, to be picked up at CT “BR3”. Since the transaction is happening at AO “BR1”, the alert type CV is 02 for hold at remote library. The possible values for CV are:

00: unknown

01: local hold

02: remote hold

03: ILL transfer (not used by EG)

04: transfer

99: other

The logic for Evergreen to determine whether the content is magnetic_media comes from either legacy circ scripts or search_config_circ_modifier. The default is non-magnetic. The same is true for media_type (default 001). Evergreen does not populate the collection_code because it does not really have any, but it will provide the call_number where available.

Unlike the item_id (barcode), the title_id is actually a title string, unless the configuration forces the return of the bib ID.

Don’t be confused by the different branches that can show up in the same response line.

AO is where the transaction took place,

AQ is the “permanent location”, and

CT is the destination location (i.e., pickup lib for a hold or target lib for a transfer).

41.2.3. 11/12 Checkout

41.2.4. 15/16 Hold

Evergreen supports the Hold message for the purpose of canceling holds. It does not currently support creating hold requests via SIP2.

41.2.5. 17/18 Item Information

The request looks like:

17<xact_date>[fields: AO,AB,AC]

The request is very terse. AC is optional.

The following response structure is for SIP2. (Version 1 of the protocol had only 6 total fields.)

18<circulation_status><security_marker><fee_type><xact_date>
[fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]

Example:

1720060110    215612AOBR1|ABno_such_barcode|

1801010120100609    162510ABno_such_barcode|AJ|

1720060110    215612AOBR1|AB1565921879|

1810020120100623    171415AB1565921879|AJPerl 5 desktop reference|CK001|AQBR1|APBR1|BGBR1
|CTBR3|CSQA76.73.P33V76 1996|

The first case is with a bogus barcode. The latter shows an item with a circulation_status of 10 for in transit between libraries. The known values of circulation_status are enumerated in the spec.

EXTENSIONS: The CT field for destination location and CS call number are used by Automated Material Handling systems.

41.2.6. 19/20 Item Status Update

41.2.7. 23/24 Patron Status

Example:

2300120060101    084235AOUWOLS|AAbad_barcode|ACsip_01|ADbad_password|

24YYYY          00120100507    013934AE|AAbad_barcode|BLN|AOUWOLS|

2300120060101    084235AOCONS|AA999999|ACsip_01|ADbad_password|

24  Y           00120100507    022318AEDoug Fiander|AA999999|BLY|CQN|BHUSD|BV0.00|AFOK|AOCONS|

2300120060101    084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|

24  Y           00120100507    022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|

The BL field (SIP2, optional) is valid patron, so the N value means bad_barcode doesn’t match a patron, the Y value means 999999 does.

The CQ field (SIP2, optional) is valid password, so the N value means bad_password doesn’t match 999999’s password, the Y means userpassword does.

So if you were building the most basic SIP2 authentication client, you would check for |CQY| in the response to know the user’s barcode and password are correct (|CQY| implies |BLY|, since you cannot check the password unless the barcode exists). However, in practice, depending on the application, there are other factors to consider in authentication, like whether the user is blocked from checkout, owes excessive fines, reported their card lost, etc. These limitations are reflected in the 14-character patron status string immediately following the 24 code. See the field definitions in your copy of the spec.

41.2.8. 25/26 Patron Enable

Not yet supported.

41.2.9. 29/30 Renew

Evergreen supports the Renew message.

41.2.10. 35/36 End Session

3520100505    115901AOBR1|AA999999|

36Y20100507    161213AOCONS|AA999999|AFThank you!|

The Y/N code immediately after the 36 indicates success/failure. Failure is not particularly meaningful or important in this context, and for evergreen it is hardcoded Y.

41.2.11. 37/38 Fee Paid

Evergreen supports the Fee Paid message.

41.2.12. 63/64 Patron Information

Attempting to retrieve patron info with a bad barcode:

6300020060329    201700          AOBR1|AAbad_barcode|

64YYYY          00020100623    141130000000000000000000000000AE|AAbad_barcode|BLN|AOBR1|

Attempting to retrieve patron info with a good barcode (but bad patron password):

6300020060329    201700          AOBR1|AA999999|ADbadpwd|

64  Y           00020100623    141130000000000000000000000000AA999999|AEDavid J. Fiander|BHUSD|BV0.00
|BD2 Meadowvale Dr. St Thomas, ON Canada

90210|BEdjfiander@somemail.com|BF(519) 555 1234|AQBR1|BLY|CQN|PB19640925|PCPatrons
|PIUnfiltered|AFOK|AOBR1|

See 23/24 Patron Status for info on BL and CQ fields.

41.2.13. 65/66 Renew All

Evergreen supports the Renew All message.

41.2.14. 93/94 Login

Example:

9300CNsip_01|CObad_value|CPBR1|

[Connection closed by foreign host.]
...

9300CNsip_01|COsip_01|CPBR1|

941

941 means successful terminal login. 940 or getting dropped means failure.

41.2.15. 97/96 Resend

41.2.16. 99/98 SC and ACS Status

99<status code><max print width><protocol version>

All 3 fields are required:

0: SC is OK

1: SC is out of paper

2: SC shutting down

status code - 1 character

max print width - 3 characters - the integer number of characters the client can print

protocol version - 4 characters - x.xx

98<on-line status><checkin ok><checkout ok><ACS renewal policy>
<status update ok><offline ok><timeout period>

<retries allowed><date/time sync><protocol version><institution id>
<library name><supported messages><terminal

location><screen message><print line>

Example:

9910302.00

98YYYYNN60000320100510    1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|

The Supported Messages field BX appears only in SIP2, and specifies whether 16 different SIP commands are supported by the ACS or not.

41.2.17. Fields

All fixed-length fields in a communication will appear before the first variable-length field. This allows for simple parsing. Variable-length fields are by definition delimited, though there will not necessarily be an initial delimiter between the last fixed-length field and the first variable-length one. It would be unnecessary, since you should know the exact position where that field begins already.

Chapter 42. Apache Rewrite Tricks

It is possible to use Apache’s Rewrite Module features to perform a number of useful tricks that can make people’s lives much easier.

42.1. Short URLs

Making short URLs for common destinations can simplify making printed media as well as shortening or simplifying what people need to type. These are also easy to add and require minimal maintenance, and generally can be implemented with a single line addition to your eg_vhost.conf file.

# My Account - http://host.ext/myaccount -> My Account Page
RewriteRule ^/myaccount https://%{HTTP_HOST}/eg/opac/myopac/main [R]

# ISBN Search - http://host.ext/search/isbn/<ISBN NUMBER> -> Search Page
RewriteRule ^/search/isbn/(.*) /eg/opac/results?_special=1&qtype=identifier|isbn&query=$1 [R]

42.2. Domain Based Content with RewriteMaps

One creative use of Rewrite features is domain-based configuration in a single eg_vhost.conf file. Regardless of how many VirtualHost blocks use the configuration you don’t need to duplicate things for minor changes, and can in fact use wildcard VirtualHost blocks to serve multiple subdomains.

For the wildcard blocks you will want to use a ServerAlias directive, and for SSL VirtualHost blocks ensure you have a wildcard SSL certificate.

ServerAlias *.example.com

For actually changing things based on the domain, or subdomain, you can use RewriteMaps. Each RewriteMap is generally a lookup table of some kind. In the following examples we will generally use text files, though database lookups and external programs are also possible.

Note that in the examples below we generally store things in Environment Variables. From within Template Toolkit templates you can access environment variables with the ENV object.

Template Toolkit ENV example, link library name/url if set. 

[% IF ENV.eglibname && ENV.egliburl %]<a href="[% ENV.egliburl %]">[% ENV.eglibname %]</a>[% END %]

The first lookup to do is a domain to identifier, allowing us to re-use identifiers for multiple domains. In addition we can also supply a default identifier, for when the domain isn’t present in the lookup table.

Apache Config. 

# This internal map allows us to lowercase our hostname, removing case issues in our lookup table
# If you prefer uppercase you can use "uppercase int:toupper" instead.
RewriteMap lowercase int:tolower
# This provides a hostname lookup
RewriteMap eglibid txt:/openils/conf/libid.txt
# This stores the identifier in a variable (eglibid) for later use
# In this case CONS is the default value for when the lookup table has no entry
RewriteRule . - [E=eglibid:${eglibid:${lowercase:%{HTTP_HOST}}|CONS}]

Contents of libid.txt File. 

# Comments can be included
# Multiple TLDs for Branch 1
branch1.example.com BRANCH1
branch1.example.net BRANCH1
# Branches 2 and 3 don't have alternate TLDs
branch2.example.com BRANCH2
branch3.example.com BRANCH3

Once we have identifiers we can look up other information, when appropriate. For example, say we want to look up library names and URLs:

Apache Config. 

# Library Name Lookup - Note we provide no default in this case.
RewriteMap eglibname txt:/openils/conf/libname.txt
RewriteRule . - [E=eglibname:${eglibname:%{ENV:eglibid}}]
# Library URL Lookup - Also with no default.
RewriteMap egliburl txt:/openils/conf/liburl.txt
RewriteRule . - [E=egliburl:${egliburl:%{ENV:eglibid}}]

Contents of libname.txt File. 

# Note that we cannot have spaces in the "value", so instead &#32; is used. &nbsp; is also an option.
BRANCH1 Branch&#32;One
BRANCH2 Branch&#32;Two
BRANCH3 Branch&#32;Three
CONS Example&#32;Consortium&#32;Name

Contents of liburl.txt File. 

BRANCH1 http://branch1.example.org
BRANCH2 http://branch2.example.org
BRANCH3 http://branch3.example.org
CONS http://example.org

Or, perhaps set the "physical location" variable for default search/display library:

Apache Config. 

# Lookup "physical location" IDs
RewriteMap eglibphysloc txt:/openils/conf/libphysloc.txt
# Note: physical_loc is a variable used in the TTOPAC and should not be re-named
RewriteRule . - [E=physical_loc:${eglibphysloc:%{ENV:eglibid}}]

Contents of libphysloc.txt File. 

BRANCH1 4
BRANCH2 5
BRANCH3 6
CONS 1

Going further, you could also replace files to be downloaded, such as images or stylesheets, on the fly:

Apache Config. 

# Check if a file exists based on eglibid and the requested file name
# Say, BRANCH1/opac/images/main_logo.png
RewriteCond %{DOCUMENT_ROOT}/%{ENV:eglibid}%{REQUEST_URI} -f
# Serve up the eglibid version of the file instead
RewriteRule (.*) /%{ENG:eglibid}$1

Note that template files themselves cannot be replaced in that manner.

Chapter 43. Apache Access Handler Perl Module

The OpenILS::WWW::AccessHandler Perl module is intended for limiting patron access to configured locations in Apache. These locations could be folder trees, static files, non-Evergreen dynamic content, or other Apache features/modules. It is intended as a more patron-oriented and transparent version of the OpenILS::WWW::Proxy and OpenILS::WWW:Proxy::Authen modules.

Instead of using Basic Authentication the AccessHandler module instead redirects to the OPAC for login. Once logged in additional checks can be performed, based on configured variables:

Permission Checks (at Home OU or specified location)

Home OU Checks (Org Unit or Descendant)

"Good standing" Checks (Not Inactive or Barred)

Use of the module is a simple addition to a Location block in Apache:

<Location /path/to/be/protected>
    PerlAccessHandler OpenILS::WWW::AccessHandler
    # For each option you wish to set:
    PerlSetVar OPTION "VALUE"
</Location>

The available options are:

OILSAccessHandlerLoginURL

Default: /eg/opac/login

The page to redirect to when Login is needed

OILSAccessHandlerLoginURLRedirectVar

Default: redirect_to

The variable the login page wants the "destination" URL stored in

OILSAccessHandlerFailURL

Default: <unset>

URL to go to if Permission, Good Standing, or Home OU checks fail. If not set a 403 error is generated instead. To customize the 403 you could use an ErrorDocument statement.

OILSAccessHandlerCheckOU

Default: <User Home OU>

Org Unit to check Permissions at and/or to load Referrer from. Can be a shortname or an ID.

OILSAccessHandlerPermission

Default: <unset>

Permission, or comma- or space-delimited set of permissions, the user must have to access the protected area.

OILSAccessHandlerGoodStanding

Default: 0

If set to a true value the user must be both Active and not Barred.

OILSAccessHandlerHomeOU

Default: <unset>

An Org Unit, or comma- or space-delimited set of Org Units, that the user’s Home OU must be equal to or a descendant of to access this resource. Can be set to shortnames or IDs.

OILSAccessHandlerReferrerSetting

Default: <unset>

Library Setting to pull a forced referrer string out of, if set.

As the AccessHandler module does not actually serve the content it is protecting, but instead merely hands control back to Apache when it is done authenticating, you can protect almost anything else you can serve with Apache.

43.1. Use Cases

The general use of this module is "protect access to something else" - what that something else is will vary. Some possibilities:

Apache features

Automatic Directory Indexes

Proxies (see below)

Electronic Databases

Software on other servers/ports

Non-Evergreen software

Timekeeping software for staff

Specialized patron request packages

Static files and folders

Semi-public Patron resources

Staff-only downloads

43.2. Proxying Websites

One potentially interesting use of the AccessHandler module is to protect an Apache Proxy configuration. For example, after installing and enabling mod_proxy, mod_proxy_http, and mod_proxy_html you could proxy websites like so:

<Location /proxy/>
    # Base "Rewrite URLs" configuration
    ProxyHTMLLinks  a       href
    ProxyHTMLLinks  area        href
    ProxyHTMLLinks  link        href
    ProxyHTMLLinks  img     src longdesc usemap
    ProxyHTMLLinks  object      classid codebase data usemap
    ProxyHTMLLinks  q       cite
    ProxyHTMLLinks  blockquote  cite
    ProxyHTMLLinks  ins     cite
    ProxyHTMLLinks  del     cite
    ProxyHTMLLinks  form        action
    ProxyHTMLLinks  input       src usemap
    ProxyHTMLLinks  head        profile
    ProxyHTMLLinks  base        href
    ProxyHTMLLinks  script      src for

    # To support scripting events (with ProxyHTMLExtended On)
    ProxyHTMLEvents onclick ondblclick onmousedown onmouseup \
            onmouseover onmousemove onmouseout onkeypress \
            onkeydown onkeyup onfocus onblur onload \
            onunload onsubmit onreset onselect onchange

    # Limit all Proxy connections to authenticated sessions by default
    PerlAccessHandler OpenILS::WWW::AccessHandler

    # Strip out Evergreen cookies before sending to remote server
    RequestHeader edit Cookie "^(.*?)ses=.*?(?:$|;)(.*)$" $1$2
    RequestHeader edit Cookie "^(.*?)eg_loggedin=.*?(?:$|;)(.*)$" $1$2
</Location>

<Location /proxy/example/>
    # Proxy example.net
    ProxyPass http://www.example.net/
    ProxyPassReverse http://www.example.net/
    ProxyPassReverseCookieDomain example.net example.com
    ProxyPassReverseCookiePath / /proxy/example/

    ProxyHTMLEnable On
    ProxyHTMLURLMap http://www.example.net/ /proxy/example/
    ProxyHTMLURLMap / /proxy/mail/
    ProxyHTMLCharsetOut *

    # Limit to BR1 and BR3 users
    PerlSetVar OILSAccessHandlerHomeOU "BR1,BR3"
</Location>

As mentioned above, this can be used for multiple reasons. In addition to websites such as online databases for patron use you may wish to proxy software for staff or patron use to make it appear on your catalog domain, or perhaps to keep from needing to open extra ports in a firewall.

Chapter 44. ebook_api service

The open-ils.ebook_api service looks up title and patron information from specified ebook vendor APIs.

The Evergreen catalog accesses data from this service through OpenSRF JS bindings.

The OpenILS::Utils::HTTPClient module is required for this service.

Chapter 45. hold-targeter service

The open-ils.hold-targeter service is used to target holds.

Part V. Using the Browser Staff Client

Chapter 46. Introduction

This part of the documentation deals with general Browser Client usage including logging in, navigation and shortcuts.

For information about the XUL client, consult the Evergreen 2.11 documentation.

Chapter 47. Logging into Evergreen

47.1. Registering a Workstation

Before logging into Evergreen, you must first register a workstation from your browser.

You will need the permissions to add workstations to your network. If you do not have these permissions, ask your system administrator for assistance.

When you login for the first time, you will arrive at a screen asking that you register your workstation

Create a unique workstation name.

Click Register

After confirming the new workstation is listed in the Workstations Registered With This Browser menu, click Use Now to return to the login page. Your newly-registered workstation should be selected by default on the login page.

47.2. Basic Login,

The default URL to log into the client is https://localhost/eg/staff/login

Enter your Username and Password.

Verify that the correct workstation is selected and click Sign In.

47.3. Logging Out

To log out of the client:

Click the menu button to the right of your user name in the top-right corner of the window.

Select Log Out

Exiting all browser windows will automatically log you out of the web client. If you only close the tab where the web client is loaded, you will remain logged in.

Chapter 48. Best Practices for Using the Browser

48.1. Pop-up Blockers

Before using the web client, be sure to disable pop-up blockers for your Evergreen system’s domain.

In Chrome, select Settings from the Chrome menu and click on Content settings in the advanced section. Select Popups and then add your domain to the Allowed list.

In Firefox, select Preferences from the Firefox menu and then select the Content panel. Click the Exceptions button and add your domain to the Allowed Sites list.

48.2. Setting Browser Defaults for Web Client

To ensure that staff can easily get to the web client portal page on login without additional steps, you can set the browser’s home page to default to the web client.

48.2.1. Setting the Web Client as the Home Page in Chrome

In the top-right corner of your browser, click the Chrome menu.

Select Settings.

In the On startup section, select Open a specific page or set of pages.

Click the Set Pages link.

Add https://localhost/eg/staff/ to the Enter URL box and click OK.

48.2.2. Setting the Web Client as the Home Page in Firefox

In the top-right corner of your browser, click the menu button.

Click Options.

In the When Firefox starts: dropdown menu, select Show my home page.

In the Home Page box, add https://localhost/eg/staff/ and click OK.

48.3. Tab Buttons and Keyboard Shortcuts

Now that the client will be loaded in a web browser, users can use browser-based tab controls and keyboard shortcuts to help with navigation. Below are some tips for browser navigation that can be used in Chrome and Firefox on Windows PCs.

Use CTRL-T or click the browser’s new tab button to open a new tab.

Use CTRL-W or click the x in the tab to close the tab.

Undo closing a tab by hitting CTRL-Shift-Tab.

To open a link from the web client in a new tab, CTRL-click the link or right-click the link and select Open Link in New Tab. Using this method, you can also open options from the web client’s dropdown menus in a new tab

Navigate from one tab to another using CTRL-Tab on the keyboard.

48.3.1. Setting New Tab Behavior

Some users may want to automatically open the web client’s portal page in a new tab. Neither Chrome nor Firefox will open your home page by default when you open a new tab. However, both browsers have optional add-ons that will allow you to set the browsers to automatically open the home page whenever open opening a new tab. These add-ons may be useful for those libraries that want the new tab to open to the web client portal page.

Chapter 49. Column Picker

From many screens and lists, you can click on the column picker drop-down menu to change which columns are displayed.

When data are displayed in columns, you can add new columns, remove them, and change the display width. After customizing the display you may save your changes for future sessions under that login by choosing Save Columns from the drop-down menu. Some libraries use generic accounts and for those who do, staff need to be aware that their changes will be visible to anybody who uses the same staff account.

Some lists have a different design, and some of them can also be customized. Simply right-click the header row of any of the columns, and the column picker will appear. When you are finished customizing the display, scroll to the bottom of the Column Picker window and click Save.

Chapter 50. Recent Staff Searches

This feature enables you to view your recent searches as you perform them in the staff client. The number of searches that you can view is configurable. This feature is only available through the staff client; it is not available to patrons in the OPAC.

50.1. Administrative Settings

By default, ten searches will be saved as you search the staff client. If you want to change the number of saved searches, then you can configure the number of searches that you wish to save through the Library Settings Editor in the Admin module.

To configure the number of recent staff searches:

Click Admin → Local Administration → Library Settings Editor.

Scroll to OPAC: Number of staff client saved searches to display on left side of results and record details pages

Click Edit.

Select a Context from the drop down menu.

Enter the number of searches that you wish to save in the Value field.

Click Update Setting

To retain this setting, the system administrator must restart the web server.

If you do not want to save any searches, then you can turn off this feature.

To deactivate this feature:

Follow steps 1-4 (one through four) as listed in the previous section.

In the value field, enter 0 (zero).

Click Update Setting. This will prevent you from viewing any saved searches.

50.2. Recent Staff Searches

Evergreen will save staff searches that are entered through either the basic or advanced search fields. To view recent staff searches:

Enter a search term in either the basic or advanced search fields.

Your search results for the current search will appear in the middle of the screen. The most recent searches will appear on the left side of the screen.

Chapter 51. Workstation Administration

51.1. Copy Editor: Copy Location Name First

By default, when editing item records, library code is displayed in front of shelving location in Shelving Location field. You may reverse the order by going to Admin → Workstation Administration → Copy Editor: Copy Location Name First. Simply click it to make copy location name displayed first. The setting is saved on the workstation.

51.2. Font and Sound Settings

51.2.1. In the Staff Client

You may change the size of displayed text or turn staff client sounds on and off. These settings are specific to each workstation and stored on local hard disk. They do not affect OPAC font sizes.

Select Admin → Workstation Administration → Global Font and Sound Settings.

To turn off the system sounds, like the noise that happens when a patron with a block is retrieved, check the disable sound box and click Save to Disk.

To change the size of the font, pick the desired option and click Save to Disk.

51.2.2. In the OPAC

It is also possible to zoom in and zoom out when viewing the OPAC in the staff client, making the font appear larger or smaller. (This will not affect other screens.) Use CTRL + + (plus sign, to zoom in), CTRL + - (minus sign, to zoom out), and CTRL + 0 (to restore default). The workstation will remember the setting.

51.3. Select Hotkeys

All or partial hotkeys can be turned on or off. It can be done for a particular workstation:

Navigate to Admin → Workstation Administration → Hotkeys → Current.

Select Default, Minimal, and None.

Default: including all hotkeys

Minimal: including those hotkeys using CTRL key

None: excluding all hotkeys

Go back to the above menu.

Click Set Workstation Default to Current.

To clear the existing default click Clear Workstation Default.

You can use the Toggle Hotkeys button, included in some toolbars, on top right corner, to switch your selected Hotkeys on or off for the current login session. It has the same effect as when you click Disable Hotkeys on the Hotkeys menu.

51.4. Configure Printers

Use the Printer Settings Editor to configure printer output for each workstation. If left unconfigured Evergreen will use the default printer set in the workstation’s operating system (Windows, OSX, Ubuntu, etc).

Evergreen printing works best if you are using recent, hardware-specific printer drivers.

Select Admin → Workstation Administration → Printer Settings Editor.

Select the Printer Context. At a minimum set the Default context on each Evergreen workstation. Repeat the procedure for other contexts if they differ from the default (e.g. if spine labels should output to a different printer.

Default: Default settings for staff client print functions (set for each workstation).

Receipt: Settings for printing receipts.

Label: Printer settings for spine and pocket labels.

Mail: Settings for printing mailed notices (not yet active).

Offline: Applies to all printing from the Offline Interface.

After choosing Printer Context click Set Default Printer and Print Test Page and follow the prompts. If successful, test output will print to your chosen printer.

(optional) To further format or customize printed output click Page Settings and adjust settings. When finished click OK and print another test page to view changes.

51.4.1. Advanced Settings

If you followed the steps above and still cannot print there are two alternate print strategies:

DOS LPTI Print (sends unformatted text directly to the parallel port)

Custom/External Print (configuration required)

Evergreen cannot print using the Windows Generic/Text Only driver. If this driver is the only one available try one of the alternate print strategies instead.

51.5. Receipt Template Editor

There are many default receipt templates included with the Evergreen staff client. These templates are saved on individual workstations. Customization can be done workstation by workstation or by exporting the templates to import to other workstations.

All receipts in Evergreen follow a basic format of a Header, Line item and Footer.

The receipt templates follow full W3C html. http://w3schools.com/html/default.asp.

The Receipt Template Editor can be found at: Admin → Workstation Administration → Receipt Template Editor

The Editor can also be found on the default home page of the staff client.

Receipts come in various types: Bills, checkout, items, holds, transits and Payments.

To edit a Receipt:

Select Admin → Workstation Administration → Receipt Template Editor.

Choose the Receipt in the drop down list.

Make edits to the Receipt on the right hand side.

Click out of the section you are editing to see what your changes will look right on the Left hand side.

Click 'Save Locally' in the Upper right hand corner.

Receipt templates use macros for various pieces of information coming from the Evergreen database. Macros deal with everything from the Library name to the due date of an item. See list Receipt Macros for the macros. You can also click on MACROS on the screen to see the macros that are available for a given receipt.

Remember: Not all Macros listed on the pop up screen will work. The listing of macros are drawn from the table that the receipt pulls information from. Some of the tables will not have any data in some of the fields. Example is the %mbts_xact_finish% on the Bills Current Slip, as this is a list of current bills, they would not have a finish date.

51.5.1. Exporting and importing Customized Receipts

Once you have your receipts set up on one machine you can export your receipts, and then load them on to another machine. Just remember to 'Save Locally' once you import the receipts on the new machine.

51.5.1.1. Exporting templates

As you can only save a template on to the computer you are working on you will need to export the template if you have more than one computer that prints out receipts (i.e., more than one computer on the circulation desk, or another computer in the workroom that you use to checkin items or capture holds with)

Export.

Select the location to save the template to, name the template, and click Save.

Click OK.

51.5.1.2. Importing Templates

Click Import.

Navigate to and select the template that you want to import. Click Open.

Click OK.

Click Save Locally.

Click OK.

51.5.2. Receipt Customizations

Customizing the receipts is fairly simple once you realize what can be placed in each of the sections of the receipts. One thing to remember when customizing receipts to always 'Save Locally'. Checkouts, Hold Slip, Hold Transit Slip are customized below.

Always remember to 'Save Locally'.

51.5.2.1. Print Holds Slip with Landscape Layout

This feature enables you to use Mozilla-specific CSS to print holds with a landscape layout. To use the landscape layout:

Click Admin → Workstation Administration → Receipt Template Editor.

Select hold transit slip from the Template Name drop down menu.

Enter <div> before and after the block of text that you wish to rotate.

Enter the stylesheet text in the <div> bracket that appears before the block of text that you wish to rotate:

<div style="moz-transform: rotate(90deg);">

When you click out of this box, notice that the text in the Preview box on the left side of the screen has rotated 90 degrees.

You can further customize the look of the text by adjusting its height and width. The height and width that you specify will be unique to your printer.

For example, you could add the following height and width to your rotated text:

<div style="moz-transform: rotate(90deg);height: 300px; width: 200px;">

The holds slip will print with the configured text in a landscape layout:

51.5.2.2. Checkout

This is the receipt that prints when items are checked out to individuals. Item you can customize are adding the library logo, adding information about renewals on the bottom of the receipt. If you notice at the end of the Footer the <br/>.<br/>, the allows an auto cut printer a little extra room so it will not cut the phone number off. The period is needed so the extra lines are added.

Header

<img align="center" src="http://www.library.org/images/logo.jpg"><br/>
Welcome to %LIBRARY%!<br/>
You checked out the following items:
<hr/>
<ol>

Line Item

<li>%title%<br/>
By: %author%<br/>
Barcode: %barcode%<br/>
Due: %due_date%

Footer

</ol>
<hr />
%SHORTNAME% %TODAY_TRIM%<br/>
You were helped by %STAFF_FIRSTNAME%<br/>
<br/>
<center>If you want to renew your materials please visit<br/>
www.library.org<br/>
or call us at ###-###-####</center>
<br/>
<br/>
.<br/>

51.5.2.3. Hold_Slip #1

This is the slip that prints when a hold is fulfilled. Things to customize are the patrons name at the top of the slip, Bold the %hold_for_msg%, among others.

Header

<font size="6"><b>%PATRON_LASTNAME%, %PATRON_FIRSTNAME%</b>
</font><br/><br/><br/><br/>
This item needs to be routed to <b>%route_to%</b>:<br/>
Barcode: %item_barcode%<br/>
Title: %item_title%<br/>
<br/>
<b>%hold_for_msg%</b><br/>
Barcode: %PATRON_BARCODE%<br/>
Notify by phone: %notify_by_phone%<br/>
Notify by email: %notify_by_email%<br/>

Line Item

<em>%formatted_note%</em><br/>

Footer

Request date: %request_date%<br/>
<br/>
Slip Date: %TODAY_D% %TODAY_I%:%TODAY_M%<br/>
Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/>.<br/>

51.5.2.4. Hold_Slip #2

This is the slip that prints when a hold is fulfilled. This slip uses the SUBSTR macro to truncate the Patrons Last name to the first 4 characters and the patron’s barcode to the last 5 digits. This slip is designed for libraries that use self-serve holds. So, you will notice a lot of information about the hold is left off of the receipt.

Header

<p style="padding-top:80px; padding-bottom:80px">
<font size="6"><b>
%SUBSTR(0,4)%%PATRON_LASTNAME%%SUBSTR_END%
&nbsp;%SUBSTR(-5)%%PATRON_BARCODE%%SUBSTR_END%
</b></font></p>
</font><br/><br/><br/><br/>
This item needs to be routed to <b>%route_to%</b>:<br/>
Barcode: %item_barcode%<br/>
Title: %item_title%<br/>
<br/>
Notify by phone: %notify_by_phone%<br/>

Line Item

<em>%formatted_note%</em><br/>

Footer

Request date: %request_date%<br/>
<hr style="border: 1px dotted"/><br/>
Slip Date: %TODAY_TRIM%<br/>
Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/>.<br/>

51.5.2.5. Hold_transit_slip

This is the slip that is printed when an Item is needed at another library for a hold. In this customization, the address of the library is removed, The library’s shortname size is increased, and made a little more notable at top, and the patron’s phone number and email address is removed from the slip.

Header

<font size="5">Route to %route_to%</font><br/><br/><br/>
This item needs to be routed to <b>%route_to%</b>:<br/>
%route_to_org_fullname%<br/><br/>
Barcode: %item_barcode%<br/>
Title: %item_title%<br/>
Author: %item_author%<br><br/>
%hold_for_msg%<br/>
Barcode: %PATRON_BARCODE%<br/>

Line Item

<em>%formatted_note%</em><br/>

Footer

<br/>Request date: %request_date%<br/>
Slip Date: %TODAY_TRIM%<br/>
Printed at %SHORTNAME%<br/>
<br/><br/>.<br/>

51.5.3. Receipt Templates

This is a complete list of all the receipts currently in use in Evergreen.

item_status

type

items

description

Listing of items inputted in to Item Status.

default format

header

The following items have been examined:<hr/><ol>

line_item

<li>%title%<br/>Barcode: %barcode%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/><br/>

transit_list

type

transits

description

List of items in transit.

default format

header

Transits:<hr/><ol>

line_item

<li>From: %transit_source% To: %transit_dest_lib%<br/>When: %transit_source_send_time%<br />Barcode: %transit_item_barcode% Title: %transit_item_title%<br/>

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/><br/>

items_out

type

items

description

List of items a patron has checked out.

default format

header

Welcome to %LIBRARY%!<br/>You have the following items:<hr/><ol>

line_item

<li>%title%<br/>Barcode: %barcode% Due: %due_date%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

renew

type

items

description

List of items that have been renewed using the renew item screen

default format

header

Welcome to %LIBRARY%!<br/>You have renewed the following items::<hr/><ol>

line_item

<li>%title%<br/>Barcode: %barcode% Due: %due_date%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

checkout

type

items

description

List of items currently checked out to the patron during this transaction.

default format

header

Welcome to %LIBRARY%!<br/>You checked out the following items::<hr/><ol>

line_item

<li>%title%<br/>Barcode: %barcode% Due: %due_date%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

offline_checkout

type

offline_checkout

description

List of items checked out via the Standalone interface. Remember that Standalone interface does not have access to the database.

default format

header

Patron %patron_barcode%<br/>You checked out the following items::<hr/><ol>

line_item

<li>Barcode: %barcode%<br/>Due: %due_date%

footer

</ol><hr />%TODAY_TRIM%<br/><br/>

checkin

type

items

description

List of items that have just been entered in to the check-in screens.

default format

header

You checked in the following items:<hr/><ol>

line_item

<li>%title%<br/>Barcode: %barcode% Call Number: %call_number%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/><br/>

bill_payment

type

payment

description

Patron payment receipt

default format

header

Welcome to %LIBRARY%!<br/> A receipt of your transaction: <hr/> <table width="100%"> <tr> <td>Original Balance:</td> <td align="right">$%original_balance%</td> </tr> <tr> <td>Payment Method:</td> <td align="right">%payment_type%</td> </tr> <tr> <td>Payment Received:</td> <td align="right">$%payment_received%</td> </tr> <tr> <td>Payment Applied:</td> <td align="right">$%payment_applied%</td> </tr> <tr> <td>Billings Voided:</td> <td align="right">%voided_balance%</td> </tr> <tr> <td>Change Given:</td> <td align="right">$%change_given%</td> </tr> <tr> <td>New Balance:</td> <td align="right">$%new_balance%</td> </tr> </table> <p> Note: %note% </p> <p> Specific bills: <blockquote>

line_item

Bill #%bill_id% %last_billing_type% Received: $%payment%<br />%barcode% %title%<br /><br />

footer

</blockquote> </p> <hr />%SHORTNAME% %TODAY_TRIM%<br/> <br/>

bills_historical

type

bills

description

Listing of bills that have had payments made on them. This is used on the Bill History Transaction screen.

default format

header

Welcome to %LIBRARY%!<br/>You had the following bills:<hr/><ol>

line_item

<dt><b>Bill #%mbts_id%</b> %title% </dt> <dd> <table> <tr valign="top"><td>Date::</td><td>%mbts_xact_start%</td></tr> <tr valign="top"><td>Type:</td><td>%xact_type%</td></tr> <tr valign="top"><td>Last Billing:</td><td>%last_billing_type%<br/>%last_billing_note%</td></tr> <tr valign="top"><td>Total Billed::</td><td>$%total_owed%</td></tr> <tr valign="top"><td>Last Payment::</td><td>%last_payment_type%<br/>%last_payment_note%</td></tr> <tr valign="top"><td>Total Paid::</td><td>$%total_paid%</td></tr> <tr valign="top"><td><b>Balance::</b></td><td><b>$%balance_owed%</b></td></tr> </table><br/>

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/><br/>

bills_current

type

bills

description

Listing of current bills for a patron.

default format

header

Welcome to %LIBRARY%!<br/> You have the following bills:<hr/><ol>

line_item

<dt><b>Bill #%mbts_id%</b></dt> <dd> <table> <tr valign="top"><td>Date:</td><td>%mbts_xact_start%</td></tr> <tr valign="top"><td>Type:</td><td>%xact_type%</td></tr> <tr valign="top"><td>Last Billing:</td><td>%last_billing_type%<br/>%last_billing_note%</td></tr> <tr valign="top"><td>Total Billed:</td><td>$%total_owed%</td></tr> <tr valign="top"><td>Last Payment:</td><td>%last_payment_type%<br/>%last_payment_note%</td></tr> <tr valign="top"><td>Total Paid:</td><td>$%total_paid%</td></tr> <tr valign="top"><td><b>Balance:</b></td><td><b>$%balance_owed%</b></td></tr> </table><br/>

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/><br/>

offline_checkin

type

offline_checkin

description

List of item checked in via Standalone interface. Remember that Standalone interface does not have access to the database.

default format

header

You checked in the following items:<hr/><ol>

line_item

<li>Barcode: %barcode%

footer

</ol><hr />%TODAY_TRIM%<br/><br/>

offline_renew

type

offline_renew

description

List of items renewed via Standalone interface. Remember that Standalone interface does not have access to the database.

default format

header

You renewed the following items:<hr/><ol>

line_item

<li>Barcode: %barcode%

footer

</ol><hr />%TODAY_TRIM%<br/><br/>

offline_inhouse_use

type

offline_inhouse_use

description

List of item marked in-house use via Standalone interface. Remember that Standalone interface does not have access to the database.

default format

header

You marked the following in-house items used:<hr/><ol>

line_item

<li>Barcode: %barcode%Uses: %count%

footer

</ol><hr />%TODAY_TRIM%<br/><br/>

in_house_use

type

items

description

List of items inputted in to the In-house use.

default format

header

You marked the following in-house items used:<hr/><ol>

line_item

<li>Barcode: %barcode%Uses: %uses%<br />%alert_message%

footer

</ol><hr />%TODAY_TRIM%<br/><br/>

holds

type

holds

description

List of items on hold for a patron.

default format

header

Welcome to %LIBRARY%!<br/>You have the following titles on hold:<hr/><ol>

line_item

<li>%title%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

holds_on_bib

type

holds

description

This list is used to print the holds on a title record.

default format

header

Welcome to %LIBRARY%!<br/>You have the following titles on hold:<hr/><ol>

line_item

<li>%title%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

holds_for_patron

description

This list is used to print the holds on a patron record.

type

holds

default format

header

Welcome to %LIBRARY%!<br/>You have the following titles on hold:<hr/><ol>

line_item

<li>%title%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

holds_shelf

type

holds

description

This list is used to print the holds on the holds shelf.

default format

header

Welcome to %LIBRARY%!<br/>You have the following titles on hold:<hr/><ol>

line_item

<li>%title%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

holds_pull_list

type

holds

description

This list is used to print the holds on the holds pull list.

default format

header

Welcome to %LIBRARY%!<br/>You have the following titles on hold:<hr/><ol>

line_item

<li>%title%

footer

</ol><hr />%SHORTNAME% %TODAY_TRIM%<br/>You were helped by %STAFF_FIRSTNAME%<br/><br/>

hold_slip

type

holds

description

This is printed when a hold is fulfilled.

default format

header

This item needs to be routed to <b>%route_to%</b>:<br/>Barcode: %item_barcode%<br/>Title: %item_title%<br/><br/>%hold_for_msg%<br/>Barcode: %PATRON_BARCODE%<br/>Notify by phone: %notify_by_phone%<br/>Notified by text: %notify_by_text%<br/>Notified by email: %notify_by_email%<br/>

line_item

%formatted_note%<br/>

footer

<br/>Request date: %request_date%<br/>Slip Date: %TODAY_TRIM%<br/>Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/><br/>

transit_slip

type

transits

description

This is printed when a item goes into transit.

default format

header

This item needs to be routed to <b>%route_to%</b>:<br/>%route_to_org_fullname%<br/> %street1%<br/>%street2%<br/> %city_state_zip%<br/><br/> Barcode: %item_barcode%<br/> Title: %item_title%<br/> Author: %item_author%<br><br/>

line_item

(Intentionally left blank)

footer

Slip Date: %TODAY_TRIM%<br/>Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/><br/>

hold_transit_slip

type

transits

description

This is printed when a hold goes in-transit to another library.

default format

header

This item needs to be routed to <b>%route_to%</b>:<br/>%route_to_org_fullname%<br/> %street1%<br/>%street2%<br/>%city_state_zip%<br/><br/> Barcode: %item_barcode%<br/> Title: %item_title%<br/> Author: %item_author%<br><br/> %hold_for_msg%<br/>Barcode: %PATRON_BARCODE%<br/> Notify by phone: %notify_by_phone%<br/> Notified by text: %notify_by_text%<br/> Notified by email: %notify_by_email%<br/>

line_item

%formatted_note%<br/>

footer

<br/>Request date: %request_date%<br/>Slip Date: %TODAY_TRIM%<br/>Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/><br/>

holdings_maintenance

type

items

description

This is printed from holding maintenance.

default format

header

Title: %title%<br/> Author: %author%<br/> ISBN: %isbn% Edition: %edition% PubDate: %pubdate%<br/> TCN: %tcn_value% Record ID: %mvr_doc_id%<br/> Creator: %creator% Create Date: %create_date%<br/> Editor: %editor% Edit Date: %edit_date%<hr/>

line_item

%prefix% %tree_location% %suffix% %parts% %acp_status%<br/>

footer

<hr />%SHORTNAME% %TODAY_TRIM%<br/><br/>

51.5.4. Receipt Template Editor Macros

Here is a list of the Receipt Template Macros that are in use on the receipts. There are two types of macros General and type specific. General Macros can be used on any of the receipts. Type specific macros are available depending on the type of the receipt.

51.5.4.1. General Macros

%LIBRARY%

Library full name

%SHORTNAME%

Library Policy Name

%STAFF_FIRSTNAME%

First name of Staff login account

%STAFF_LASTNAME%

Last name of Staff login account

%STAFF_BARCODE%

Barcode of Staff login account

%STAFF_PROFILE%

Profile of Staff login account

%PATRON_FIRSTNAME%

First name of Patron

%PATRON_LASTNAME%

Last name of Patron

%PATRON_BARCODE% or %patron_barcode%

Patron Barcode

%TODAY%

Full Date and time in the format: Wed Sep 21 2011 13:20:44 GMT-0400 (Eastern Daylight Time)

%TODAY_TRIM%

Date and time in a shorted format: 2011-09-21 13:21

%TODAY_m%

Two digit Month: 09

%TODAY_d%

Two digit Day: 21

%TODAY_Y%

Year: 2011

%TODAY_H%

Hour in 24 hour day: 13

%TODAY_I%

Hour in 12 hour format: 1

%TODAY_M%

Minutes of the Hour: 24

%TODAY_D%

date in standard US format: 09/21/11

%TODAY_F%

date in International Standard: 2011-09-21

%-TRIM%

Trims white space before the macro

%TRIM-%

Trims white space after the macro

%SUBSTR(#)%…%SUBSTR_END%

Take substring starting at position # to end of string. If # is negative count backwards from end of string.

%SUBSTR(,)%…%SUBSTR_END%

Same as %SUBSTR(#)%, but limit to second provided number characters after start point. If second number is negative, count backwards instead of forwards.

There are several macros that can carry pre-built contents specific to individual libraries. The contents can be set up in local administration. For details see Library Settings. Though text can be hard-coded in receipt templates, the pre-built contents will be automatically applied to receipts printed from all workstations without editing each template.

%INCLUDE(notice_text)%

%INCLUDE(alert_text)%

%INCLUDE(event_text)%

%INCLUDE(footer_text)%%

%INCLUDE(header_text)%

51.5.4.2. Additional Macros for various slip types

Holds

%ROUTE_TO%

It should say Hold Shelf if it is a hold being fulfilled

%item_barcode%

Item Barcode

%item_title%

Item Title

%hold_for_msg%

Hold for Message: this gives the patron’s Name

%PATRON_BARCODE%

Patron’s Barcode

%notify_by_phone%

Phone number listed in the Hold Database. This may not be the same as what is in the Patron’s record, as they can list another number when placing the hold.

%notify_by_email%

Email listed in Hold Database. Same as phone number

%request_date%

The date that the Request was originally placed.

%formatted_note%

Hold Notes (new to 2.1)

%notify_by_text%

SMS contact number (new to 2.2)

Check out

%title%

Title

%author%

Author

%barcode%

Item Barcode

%due_date%

Due Date: formated by the date field in the library settings editor

Payment

%original_balance%

The original balance the patron owes

%payment_received%

How much was received from the patron

%payment_applied%

How much of the payment was applied

%payment_type%

What type of payment was applied: IE Cash

%voided_balance%

Any Voided balance

%change_given%

How much change was given

%new_balance%

The new balance on the account

%note%

Any notes on the annotated payment

%bill_id% or %mbts_id%

The id for the bill in the bill database

%payment%

How much of the payment that was applied was applied to this title

%title%

Title that the payment was applied to.

%last_billing_type%

The type of bill that was last charged to the patron for this title

%last_billing_note%

Notes on the last bill

%last_payment_type%

The type of payment that was last used to pay the bill

%mbts_xact_start%

The date that the bill was started

%last_payment_note%

Notes on last payment

%xact_type%

Type of Biil

%barcode%

Item barcode

%title%

title of item

Bills

%mbts_id%

The id for the bill in the bill database

%title%

Title that the payment was applied to.

%last_billing_type%

The type of bill that was last charged to the patron for this bill

%last_billing_note%

Notes on the last bill

%last_billing_ts%

The time stamp for the last billing

%last_payment_type%

The type of payment that was last used to pay the bill

%last_payment_note%

Notes on last payment

%last_payment_ts%

The time stamp for the last payment

%mbts_xact_start%

The date that the bill was started (currently not working)

%xact_type%

Type of Biil

%title%

title of item

Transit

Transit receipts come into two types, general Transit receipts and Transit slips. Transit receipts are listings of item that are in transits. Transit slips are Slips telling the staff that this item is in transit to another location.

Table 51.1. General Transits

%transit_item_author%

Item author

%transit_item_barcode%

Barcode of item in transit

%transit_item_callnumber%

Call number of item in transit

%transit_item_title%

Title of Item intransit

%transit_dest_lib%

Destination Library

%transit_source_send_time%

Time item was sent intransit

%transit_source%

Library that placed the item intransit.

Table 51.2. Transit Slip

%route_to%

Library Policy Name that the item is in transit to

%route_to_org_fullname%

Library Full Name that the item is in transit to

%street1%

Library Street address Line 1 that the item is in transit to.

%street2%

Library Street address Line 2 that the item is in transit to.

%city_state_zip%

City, State, Zip of Library the Item is in transit to.

%item_barcode%

Item barcode

%item_title%

Item title

%item_author%

Item Author

%hold_for_msg%

Hold for Message: this gives the patron’s name

%PATRON_BARCODE%

Patron’s Barcode

%notify_by_phone%

Phone number listed in the Hold Database. This may not be the same as what is in the Patron’s record, as they can list another number when placing the hold.

%notify_by_email%

Email listed in Hold Database. Same as phone number

%notify_by_text%

SMS contact number (new to 2.2)

%request_date%

Date that the Request was originally placed

Part VI. System Administration From the Staff Client

Chapter 52. Introduction

This part deals with the options in the Server Administration menu found in the staff client.

Chapter 53. Acquisitions Administration

53.1. Acquisitions Settings

Several setting in the Library Settings area of the Admin module pertain to functions in the Acquisitions module. You can access these settings by clicking Admin → Local Administration → Library Settings Editor.

CAT: Delete bib if all copies are deleted via Acquisitions lineitem cancellation - If you cancel a line item, then all of the on order copies in the catalog are deleted. If, when you cancel a line item, you also want to delete the bib record, then set this setting to TRUE.

Allow funds to be rolled over without bringing the money along - enables you to move a fund’s encumbrances from one year to the next without moving unspent money. Unused money is not added to the next year’s fund and is not available for use.

Allows patrons to create automatic holds from purchase requests.

Default circulation modifier - This modifier would be applied to items that are created in the acquisitions module

Default copy location - This copy location would be applied to items that are created in the acquisitions module

Fund Spending Limit for Block - When the amount remaining in the fund, including spent money and encumbrances, goes below this percentage, attempts to spend from the fund will be blocked.

Fund Spending Limit for Warning - When the amount remaining in the fund, including spent money and encumbrances, goes below this percentage, attempts to spend from the fund will result in a warning to the staff.

Rollover Distribution Formulae Funds - When set to true, during fiscal rollover, all distribution formulae will update to use new funds.

Set copy creator as receiver - When receiving a copy in acquisitions, set the copy "creator" to be the staff that received the copy

Temporary barcode prefix - Temporary barcode prefix for items that are created in the acquisitions module

Temporary call number prefix - Temporary call number prefix for items that are created in the acquisitions module

53.2. Cancel/Delay reasons

The Cancel reasons link enables you to predefine the reasons for which a line item or a PO can be cancelled. A default list of reasons appears, but you can add custom reasons to this list. Applying the cancel reason will prevent the item from appearing in a claims list and will allow you to cancel debits associated with the purchase. Cancel reasons also enable you to delay a purchase. For example, you could create a cancel reason of back ordered, and you could choose to keep the debits associated with the purchase.

53.2.1. Create a cancel/delay reason

To add a new cancel reason, click Administration → Server Administration → Acquisitions → Cancel reasons.

Click New Cancel Reason.

Select a using library from the drop-down menu. The using library indicates the organizational units whose staff can use this cancel reason. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units.)

Create a label for the cancel reason. This label will appear when you select a cancel reason on an item or a PO.

Create a description of the cancel reason. This is a free text field and can comprise any text of your choosing.

If you want to retain the debits associated with the cancelled purchase, click the box adjacent to Keep Debits→

Click Save.

53.2.2. Delete a custom cancel/delay reason

You can delete custom cancel reason.

Select the checkbox for the custom cancel reason that should be deleted.

Click the Delete Selected button.

You cannot select the checkbox for any of the default cancel reasons because the system expects those reasons to be available to handle EDI order responses.

53.3. Claiming

Currently, all claiming is manual, but the admin module enables you to build claim policies and specify the action(s) that users should take to claim items.

53.3.1. Create a claim policy

The claim policy link enables you to name the claim policy and specify the organization that owns it.

To create a claim policy, click Admin → Server Administration → Acquisitions → Claim Policies.

Create a claim policy name. No limits exist on the number of characters that can be entered in this field.

Select an org unit from the drop-down menu. The org unit indicates the organizational units whose staff can use this claim policy. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list.

Enter a description. No limits exist on the number of characters that can be entered in this field.

Click Save.

53.3.2. Create a claim type

The claim type link enables you to specify the reason for a type of claim.

To create a claim type, click Admin → Server Administration → Acquisitions → Claim types.

Create a claim type. No limits exist on the number of characters that can be entered in this field.

Select an org unit from the drop-down menu. The org unit indicates the organizational units whose staff can use this claim type. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list.

Enter a description. No limits exist on the number of characters that can be entered in this field.

Click Save.

53.3.3. Create a claim event type

The claim event type describes the physical action that should occur when an item needs to be claimed. For example, the user should notify the vendor via email that the library is claiming an item.

To access the claim event types, click Admin → Server Administration → Acquisitions → Claim event type.

Enter a code for the claim event type. No limits exist on the number of characters that can be entered in this field.

Select an org unit from the drop-down menu. The org unit indicates the organizational units whose staff can use this event type. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list.

Enter a description. No limits exist on the number of characters that can be entered in this field.

If this claim is initiated by the user, then check the box adjacent to Library Initiated.

Currently, all claims are initiated by a user. The ILS cannot automatically claim an issue.

Click Save.

53.3.4. Create a claim policy action

The claim policy action enables you to specify how long a user should wait before claiming the item.

To access claim policy actions, click Admin → Server Administration → Acquisitions →Claim Policy Actions.

Select an Action (Event Type) from the drop-down menu.

Enter an action interval. This field indicates how long a user should wait before claiming the item.

In the Claim Policy ID field, select a claim policy from the drop-down menu.

Click Save.

You can create claim cycles by adding multiple claim policy actions to a claim policy.

53.4. Currency Types

Currency types can be created and applied to funds in the administrative module. When a fund is applied to a copy or line item for purchase, the item will be purchased in the currency associated with that fund.

53.4.1. Create a currency type

To create a new currency type, click Admin → Server Administration → Acquisitions → Currency types.

Enter the currency code. No limits exist on the number of characters that can be entered in this field.

Enter the name of the currency type in Currency Label field. No limits exist on the number of characters that can be entered in this field.

Click Save.

53.4.2. Edit a currency type

To edit a currency type, click your cursor in the row that you want to edit. The row will turn blue.

Double click. The pop-up box will appear, and you can edit the fields.

After making changes, click Save.

From the currency types interface, you can delete currencies that have never been applied to funds or used to make purchases.

53.5. Distribution Formulas

Distribution formulas allow you to specify the number of copies that should be distributed to specific branches. They can also serve as templates allowing you to predefine settings for your copies. You can create and reuse formulas as needed.

53.5.1. Create a distribution formula

Click Admin → Server Administration → Acquisitions →Distribution Formulas.

Click New Formula.

Enter a Formula Name. No limits exist on the number of characters that can be entered in this field.

Choose a Formula Owner from the drop-down menu. The Formula Owner indicates the organizational units whose staff can use this formula. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list.

Ignore the Skip Count field which is currently not used.

Click Save.

Click New Entry.

Select an Owning Library from the drop-down menu. This indicates the branch that will receive the items. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

Select/enter any of the following copy details you want to predefine in the distribution formula.

Copy Location

Fund

Circ Modifier

Collection Code

In the Item Count field, enter the number of items that should be distributed to the branch. You can enter the number or use the arrows on the right side of the field.

Click Apply Changes. The screen will reload.

To view the changes to your formula, click Admin → Server Administration → Acquisitions → Distribution Formulas. The item_count will reflect the entries to your distribution formula.

To edit the Formula Name, click the hyperlinked name of the formula in the top left corner. A pop-up box will enable you to enter a new formula name.

53.5.2. Edit a distribution formula

To edit a distribution formula, click the hyperlinked title of the formula.

53.6. Electronic Data Interchange

Many libraries use Electronic Data Interchange (EDI) accounts to send purchase orders and receive invoices from providers electronically. In Evergreen users can setup EDI accounts and manage EDI messages in the admin module. EDI messages and notes can be viewed in the acquisitions module. See also the EDI Installation Instructions because this is required for use of EDI.

53.6.1. Entering SANs (Standard Address Numbers)

For EDI to work your library must have a SAN and each of your providers must each supply you with their SAN.

A SAN (Standard Address Number) is a unique 7 digit number that identifies your library.

53.6.1.1. Entering a Library’s SAN

These steps only need to be done once per library.

In Evergreen select Admin → Server Administration → Organizational Units

Find your library in the tree on the left side of the page and click on it to open the settings.

Multi-branch library systems will see an entry for each branch but should select their system’s top organization unit.

Click on the Address tab.

Click on the Mailing Address tab.

Enter your library’s SAN in the field labeled SAN.

Click Save.

53.6.1.2. Entering a Provider’s SAN

These steps need to be repeated for every provider with which EDI is used.

In Evergreen select Admin → Server Administration → Acquisitions → Providers.

Click the hyperlinked name of the provider you would like to edit.

Enter your provider’s SAN in the field labeled SAN.

Click Save.

53.6.2. Create an EDI Account

You must create your provider before you create an EDI account for the provider.

Contact your provider requesting the following information:

Host

Username

Password

Path

Incoming Directory

Provider’s SAN

In Evergreen select Admin → Server Administration → Acquisitions → EDI Accounts.

Click New Account. A pop-up will appear.

Fill in the following fields:

In the Label field, enter a name for the EDI account.

In the Host field, enter the requisite FTP or SCP information supplied by your provider. Be sure to include the protocol (e.g. ftp://ftp.vendorname.com)

In the Username field, enter the username supplied by your provider.

In the Password field, enter the password supplied by your provider.

Select your library as the Owner from the drop down menu. Multi-branch libraries should select their top level organizational unit.

The Last Activity updates automatically with any inbound or outbound communication.

In the Provider field, enter the code used in Evergreen for your provider.

In the Path field, enter the path supplied by your provider. The path indicates a directory on the provider’s server where Evergreen will deposit its outgoing order files.

If your vendor requests a specific file extension for EDI purchase orders, such as .ord, enter the name of the directory, followed by a slash, followed by an asterisk, followed by a period, followed by the extension. For example, if the vendor requests that EDI purchase orders be sent to a directory called in with the file extension .ord, your path would be in/*.ord.

In the Incoming Directory field, enter the incoming directory supplied by your provider. This indicates the directory on the vendor’s server where Evergreen will retrieve incoming order responses and invoices.

Don’t worry if your incoming directory is named out or outgoing. From your vendor’s perspective, this directory is outgoing, because it contains files that the vendor is sending to Evergreen. However, from Evergreen’s perspective, these files are incoming.

Click Save.

Click on the link in the Provider field.

Select the EDI account that has just been created from the EDI Default drop down menu.

Click Save.

53.6.3. EDI Messages

The EDI Messages screen displays all incoming and outgoing messages between the library and its providers. To see details of a particular EDI message, including the raw EDIFACT message, double click on a message entry. To find a specific EDI message, the Filter options can be useful. Outside the Admin interface, EDI messages that pertain to a specific purchase order can be viewed from the purchase order interface (See Acquisitions → Purchase Orders).

53.7. Exchange Rates

Exchange rates define the rate of exchange between currencies. Evergreen will automatically calculate exchange rates for purchases. Evergreen assumes that the currency of the purchasing fund is identical to the currency of the provider, but it provides for two unique situations: If the currency of the fund that is used for the purchase is different from the currency of the provider as listed in the provider profile, then Evergreen will use the exchange rate to calculate the price of the item in the currency of the fund and debit the fund accordingly. When money is transferred between funds that use different currency types, Evergreen will automatically use the exchange rate to convert the money to the currency of the receiving fund. During such transfers, however, staff can override the automatic conversion by providing an explicit amount to credit to the receiving fund.

53.7.1. Create an exchange rate

To create a new exchange rate, click Admin → Server Administration → Acquisitions → Exchange Rates.

Click New Exchange Rate.

Enter the From Currency from the drop-down menu populated by the currency types.

Enter the To Currency from the drop-down menu populated by the currency types.

Enter the exchange Ratio.

Click Save.

53.7.2. Edit an exchange rate

Edit an exchange rate just as you would edit a currency type.

53.8. MARC Federated Search

The MARC Federated Search enables you to import bibliographic records into a selection list or purchase order from a Z39.50 source.

Click Acquisitions → MARC Federated Search.

Check the boxes of Z39.50 services that you want to search. Your local Evergreen Catalog is checked by default. Click Submit.

A list of results will appear. Click the Copies link to add copy information to the line item. See Line Item Features for more information.

Click the Notes link to add notes or line item alerts to the line item. See Line Item Features for more information.

Enter a price in the Estimated Price field.

You can save the line item(s) to a selection list by checking the box on the line item and clicking Actions → Save Items to Selection List. You can also create a purchase order from the line item(s) by checking the box on the line item and clicking Actions → Create Purchase Order.

53.9. Fund Tags

You can apply tags to funds so that you can group funds for easy reporting. For example, you have three funds for children’s materials: Children’s Board Books, Children’s DVDs, and Children’s CDs. Assign a fund tag of children’s to each fund. When you need to report on the amount that has been spent on all children’s materials, you can run a report on the fund tag to find total expenditures on children’s materials rather than reporting on each individual fund.

Create a Fund Tag

To create a fund tag, click Admin → Server Administration → Acquisitions → Fund Tags.

Click New Fund Tag. No limits exist on the number of characters that can be entered in this field.

Select a Fund Tag Owner from the drop-down menu. The owner indicates the organizational unit(s) whose staff can use this fund tag. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list.

Enter a Fund Tag Name. No limits exist on the number of characters that can be entered in this field.

Click Save.

53.10. Funding Sources

Funding sources allow you to specify the sources that contribute monies to your fund(s). You can create as few or as many funding sources as you need. These can be used to track exact amounts for accounts in your general ledger. You can then use funds to track spending and purchases for specific collections.

53.10.1. Create a funding source

To create a new funding source, click Admin → Server Administration → Acquisitions → Funding Source.

Enter a funding source name. No limits exist on the number of characters that can be entered in this field.

Select an owner from the drop-down menu. The owner indicates the organizational unit(s) whose staff can use this funding source. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list. For example, if a system is made the owner of a funding source, then users with appropriate permissions at the branches within the system could also use the funding source.

Create a code for the source. No limits exist on the number of characters that can be entered in this field.

Select a currency from the drop-down menu. This menu is populated from the choices in the Currency Types interface.

Click Save.

53.10.2. Allocate credits to funding sources

Apply a credit to this funding source.

Enter the amount of money that the funding source contributes to the organization. Funding sources are not tied to fiscal or calendar years, so you can continue to add money to the same funding source over multiple years, e.g. County Funding. Alternatively, you can name funding sources by year, e.g. County Funding 2010 and County Funding 2011, and apply credits each year to the matching source.

To apply a credit, click on the hyperlinked name of the funding source. The Funding Source Details will appear.

Click Apply Credit.

Enter an amount to apply to this funding source.

Enter a note. This field is optional.

Click Apply.

53.10.3. Allocate credits to funds

If you have already set up your funds, then you can then click the Allocate to Fund button to apply credits from the funding sources to the funds. If you have not yet set up your funds, or you need to add a new one, you can allocate credits to funds from the funds interface. See section 1.2 for more information.

To allocate credits to funds, click Allocate to Fund.

Enter the amount that you want to allocate.

Enter a note. This field is optional.

Click Apply.

53.10.4. Track debits and credits

You can track credits to and allocations from each funding source. These amounts are updated when credits and allocations are made in the Funding Source Details. Access the Funding Source Details by clicking on the hyperlinked name of the Funding Source.

53.11. Funds

Funds allow you to allocate credits toward specific purchases. In the funds interface, you can create funds; allocate credits from funding sources to funds; transfer money between funds; and apply fund tags to funds. Funds are created for a specific year, either fiscal or calendar. These funds are owned by org units. At the top of the funds interface, you can set a contextual org unit and year. The drop-down menu at the top of the screen enables you to focus on funds that are owned by specific organizational units during specific years.

53.11.1. Create a fund

To create a new fund, click Admin → Server Administration → Acquisitions → Funds.

Enter a name for the fund. No limits exist on the number of characters that can be entered in this field.

Create a code for the fund. No limits exist on the number of characters that can be entered in this field.

Enter a year for the fund. This can be a fiscal year or a calendar year. The format of the year is YYYY.

Select an org unit from the drop-down menu. The org unit indicates the organizational units whose staff can use this fund. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list. See section

Select a currency type from the drop-down menu. This menu is comprised of entries in the currency types menu. When a fund is applied to a line item or copy, the price of the item will be encumbered in the currency associated with the fund.

Click the Active box to activate this fund. You cannot make purchases from this fund if it is not active.

Enter a Balance Stop Percent. The balance stop percent prevents you from making purchases when only a specified amount of the fund remains. For example, if you want to spend 95 percent of your funds, leaving a five percent balance in the fund, then you would enter 95 in the field. When the fund reaches its balance stop percent, it will appear in red when you apply funds to copies.

Enter a Balance Warning Percent. The balance warning percent gives you a warning that the fund is low. You can specify any percent. For example, if you want to spend 90 percent of your funds and be warned when the fund has only 10 percent of its balance remaining, then enter 90 in the field. When the fund reaches its balance warning percent, it will appear in yellow when you apply funds to copies.

Check the Propagate box to propagate funds. When you propagate a fund, the ILS will create a new fund for the following fiscal year with the same parameters as your current fund. All of the settings transfer except for the year and the amount of money in the fund. Propagation occurs during the fiscal year close-out operation.

Check the Rollover box if you want to roll over remaining funds into the same fund next year. You should also check this box if you only want to roll over encumbrances into next year’s fund.

Click Save.

53.11.2. Allocate credits from funding sources to funds

Credits can be applied to funds from funding sources using the fund interface. The credits that you apply to the fund can be applied later to purchases.

To access funds, click Admin → Server Administration → Acquisitions → Funds.

Click the hyperlinked name of the fund.

To add a credit to the fund, click the Create Allocation tab.

Choose a Funding Source from the drop-down menu.

Enter an amount that you want to apply to the fund from the funding source.

Enter a note. This field is optional.

Click Apply.

53.11.3. Transfer credits between funds

The credits that you allocate to funds can be transferred between funds if desired. In the following example, you can transfer $500.00 from the Young Adult Fiction fund to the Children’s DVD fund.

To access funds, click Admin → Server Administration → Acquisitions → Funds.

Click the hyperlinked name of the originating fund.

The Fund Details screen appears. Click Transfer Money.

Enter the amount that you would like to transfer.

From the drop-down menu, select the destination fund.

Add a note. This field is optional.

Click Transfer.

53.11.4. Track balances and expenditures

The Fund Details allows you to track the fund’s balance, encumbrances, and amount spent. It also allows you to track allocations from the funding source(s), debits, and fund tags.

To access the fund details, click on the hyperlinked name of the fund that you created.

The Summary allows you to track the following:

Balance - The balance is calculated by subtracting both items that have been invoiced and encumbrances from the total allocated to the fund.

Total Allocated - This amount is the total amount allocated from the Funding Source.

Spent Balance - This balance is calculated by subtracting only the items that have been invoiced from the total allocated to the fund. It does not include encumbrances.

Total Debits - The total debits are calculated by adding the cost of items that have been invoiced and encumbrances.

Total Spent - The total spent is calculated by adding the cost of items that have been invoiced. It does not include encumbrances.

Total Encumbered - The total encumbered is calculated by adding all encumbrances.

53.11.5. Fund reporting

A core source, Fund Summary, is available in the reports interface. This core source enables librarians to easily run a report on fund activity. Fields that are accessible in this interface include Remaining Balance, Total Allocated, Total Encumbered, and Total Spent.

53.11.6. Edit a fund

Edit a fund just as you would edit a currency type.

53.11.7. Perform fiscal year close-out operation

The Fiscal Year Close-Out Operation allows you to deactivate funds for the current year and create analogous funds for the next year. It transfers encumbrances to the analogous funds, and it rolls over any remaining funds if you checked the rollover box when creating the fund.

To access the year end closeout of a fund, click Admin → Server Administration → Acquisitions → Funds.

Click Fund Propagation and Rollover.

Check the box adjacent to Perform Fiscal Year Close-Out Operation.

For funds that have the "Rollover" setting enabled, if you want to move the fund’s encumbrances to the next year without moving unspent money, check the box adjacent to Limit Fiscal Year Close-out Operation to Encumbrances.

The Limit Fiscal Year Close-out Operation to Encumbrances will only display if the Allow funds to be rolled over without bringing the money along Library Setting has been enabled. This setting is available in the Library Setting Editor accessible via Administration → Local Administration → Library Settings Editor.

Notice that the context org unit reflects the context org unit that you selected at the top of the Funds screen.

If you want to perform the close-out operation on the context org unit and its child units, then check the box adjacent to Include Funds for Descendant Org Units.

Check the box adjacent to dry run if you want to test changes to the funds before they are enacted. Evergreen will generate a summary of the changes that would occur during the selected operations. No data will be changed.

Click Process.

Evergreen will begin the propagation process. Evergreen will make a clone of each fund, but it will increment the year by 1.

53.12. Invoice menus

Invoice menus allow you to create drop-down menus that appear on invoices. You can create an invoice item type or invoice payment method.

53.12.1. Invoice item type

The invoice item type allows you to enter the types of additional charges that you can add to an invoice. Examples of additional charge types might include taxes or processing fees. Charges for bibliographic items are listed separately from these additional charges. A default list of charge types displays, but you can add custom charge types to this list. Invoice item types can also be used when adding non-bibliographic items to a purchase order. When invoiced, the invoice item type will copy from the purchase order to the invoice.

To create a new charge type, click Admin → Server Administration → Acquisitions → Invoice Item Type.

Click New Invoice Item Type.

Create a code for the charge type. No limits exist on the number of characters that can be entered in this field.

Create a label. No limits exist on the number of characters that can be entered in this field. The text in this field appears in the drop-down menu on the invoice.

If items on the invoice were purchased with the monies in multiple funds, then you can divide the additional charge across funds. Check the box adjacent to Prorate→ if you want to prorate the charge across funds.

Click Save.

53.12.2. Invoice payment method

The invoice payment method allows you to predefine the type(s) of invoices and payment method(s) that you accept. The text that you enter in the admin module will appear as a drop-down menu in the invoice type and payment method fields on the invoice.

To create a new invoice payment method, click Admin → Server Administration → Acquisitions → Invoice Payment Method.

Click New Invoice Payment Method.

Create a code for the invoice payment method. No limits exist on the number of characters that can be entered in this field.

Create a name for the invoice payment method. No limits exist on the number of characters that can be entered in this field. The text in this field appears in the drop-down menu on the invoice.

Click Save.

Payment methods can be deleted from this screen.

53.13. Line Item Features

Line item alerts are predefined text that can be added to line items that are on selection lists or purchase orders. You can define the alerts from which staff can choose. Line item alerts appear in a pop-up box when the line item, or any of its copies, are marked as received.

53.13.1. Create a line item alert

To create a line item alert, click Administration → Server Administration → Acquisitions → Line Item Alerts.

Click New Line Item Alert Text.

Create a code for the text. No limits exist on the number of characters that can be entered in this field.

Create a description for the text. No limits exist on the number of characters that can be entered in this field.

Select an owning library from the drop-down menu. The owning library indicates the organizational units whose staff can use this alert. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

Click Save.

53.13.2. Line item MARC attribute definitions

Line item attributes define the fields that Evergreen needs to extract from the bibliographic records that are in the acquisitions database to display in the catalog. Also, these attributes will appear as fields in the New Brief Record interface. You will be able to enter information for the brief record in the fields where attributes have been defined.

53.14. Providers

Providers are vendors. You can create a provider profile that includes contact information for the provider, holdings information, invoices, and other information.

53.14.1. Create a provider

To create a new provider, click Admin → Server Administration → Acquisitions → Providers.

Enter the provider name.

Create a code for the provider. No limits exist on the number of characters that can be entered in this field.

Select an owner from the drop-down menu. The owner indicates the organizational units whose staff can use this provider. This menu is populated with the shortnames that you created for your libraries in the organizational units tree (See Admin → Server Administration → Organizational Units).

The rule of parental inheritance applies to this list.

Select a currency from the drop-down menu. This drop-down list is populated by the list of currencies available in the currency types.

A provider must be active in order for purchases to be made from that provider. To activate the provider, check the box adjacent to Active. To deactivate a vendor, uncheck the box.

Add the default # of copies that are typically ordered through the provider. This number will automatically populate the line item’s Copies box on any PO’s associated with this provider. If another quantity is entered during the selection or ordering process, it will override this default. If no number is specified, the default number of copies will be zero.

Select a default claim policy from the drop-down box. This list is derived from the claim policies that can be created

Select an EDI default. This list is derived from the EDI accounts that can be created.

Enter the provider’s email address.

In the Fax Phone field, enter the provider’s fax number.

In the holdings tag field, enter the tag in which the provider places holdings data.

In the phone field, enter the provider’s phone number.

If prepayment is required to purchase from this provider, then check the box adjacent to prepayment required.

Enter the Standard Address Number (SAN) for your provider.

Enter the web address for the provider’s website in the URL field.

Click Save.

53.14.2. Add contact and holdings information to providers

After you save the provider profile, the screen reloads so that you can save additional information about the provider. You can also access this screen by clicking the hyperlinked name of the provider on the Providers screen. The tabs allow you to add a provider address and contact, attribute definitions, and holding subfields. You can also view invoices associated with the provider.

Enter a Provider Address, and click Save.

Required fields for the provider address are: Street 1, city, state, country, post code. You may have multiple valid addresses.

Enter the Provider Contact, and click Save.

Your vendor may include information that is specific to your organization in MARC tags. You can specify the types of information that should be entered in each MARC tag. Enter attribute definitions to correlate MARC tags with the information that they should contain in incoming vendor records. Some technical knowledge is required to enter XPath information. As an example, if you need to import the PO Name, you could set up an attribute definition by adding an XPath similar to:

code => purchase_order
xpath => //*[@tag="962"]/*[@code="p"]
Is Identifier => false

where 962 is the holdings tag and p is the subfield that contains the PO Name.

You may have entered a holdings tag when you created the provider profile. You can also enter holdings subfields. Holdings subfields allow you to specify subfields within the holdings tag to which your vendor adds holdings information, such as quantity ordered, fund, and estimated price.

Click invoices to access invoices associated with a provider.

53.14.3. Edit a provider

Edit a provider just as you would edit a currency type.

You can delete providers only if no purchase orders have been assigned to them.

Chapter 54. Age hold protection

Age hold protection prevents new items from filling holds requested for pickup at a library other than the owning library for a specified period of time.

You can define the protection period in Admin → Server Administration → Age Hold Protect Rules.

The protection period when applied to a copy record can start with the copy record create date (default) or active date. You can change this setting in Admin → Local Administration → Library Settings Editor: Use Active Date for Age Protection.

In addition to time period, you can set the proximity value to define which organizational units are allowed to act as pickup libraries. The proximity values affect holds as follows:

"0" allows only holds where pickup library = owning library

"1" allows holds where pickup library = owning library, parent, and child organizational units

"2" allows holds where pickup library = owning library, parent, child, and/or sibling organizational units

Age protection only applies to individual copy records. You cannot configure age protection rules in hold policies.

54.1. Active date display in OPAC

If a library uses the copy’s active date to calculate holds age protection, the active date will display with the copy details instead of the create date in the staff client view of the catalog. Libraries that do not enable the Use Active Date for Age Protection library setting will continue to display the create date.

Chapter 55. Authorities

55.1. Authority Control Sets

The tags and subfields that display in authority records in Evergreen are proscribed by control sets. The Library of Congress control set is the default control set in Evergreen. In Evergreen release 2.2, you can create customized control sets for authority records. Also, you can define thesauri and authority fields for these control sets.

Patrons and staff will be able to browse authorities in the OPAC. The following fields are browsable by default: author, series, subject, title, and topic. You will be able to add custom browse axes in addition to these default fields.

You can specify the MARC tags and subfields that an authority record should contain. The Library of Congress control set exists in the staff client by default. The control sets feature enables librarians to add or customize new control sets.

To access existing control sets, click Admin → Server Administration → Authorities → Control Sets.

55.1.1. Add a Control Set

Click Admin → Server Administration → Authorities → Control Sets.

Click New Control Set.

Add a Name to the control set. Enter any number of characters.

Add a Description of the control set. Enter any number of characters.

Click Save.

55.2. Thesauri

A thesaurus describes the semantic rules that govern the meaning of words in a MARC record. The thesaurus code, which indicates the specific thesaurus that should control a MARC record, is encoded in a fixed field using the mnemonic Subj in the authority record. Eleven thesauri associated with the Library of Congress control set exist by default in the staff client.

To access an existing thesaurus, click Admin → Server Administration → Authorities → Control Sets, and choose the hyperlinked thesaurus that you want to access, or click Admin → Server Administration → Authorities → Thesauri.

55.2.1. Add a Thesaurus

Click Admin → Server Administration → Authorities → Control Sets, and choose the hyperlinked thesaurus that you want to access, or click Admin → Server Administration → Authorities → Thesauri.

Click New Thesaurus.

Add a Thesaurus Code. Enter any single, upper case character. This character will be entered in the fixed fields of the MARC record.

Add a Name to the thesaurus. Enter any number of characters.

Add a Description of the thesaurus. Enter any number of characters.

55.3. Authority Fields

Authority fields indicate the tags and subfields that should be entered in the authority record. Authority fields also enable you to specify the type of data that should be entered in a tag. For example, in an authority record governed by a Library of Congress control set, the 100 tag would contain a "Heading - Personal Name." Authority fields also enable you to create the corresponding tag in the bibliographic record that would contain the same data.

55.3.1. Create an Authority Field

Click Admin → Server Administration → Authorities → Control Sets.

Click Authority Fields. The number in parentheses indicates the number of authority fields that have been created for the control set.

Click New Authority Field.

Add a Name to the authority field. Enter any number of characters.

Add a Description to describe the type of data that should be entered in this tag. Enter any number of characters.

Select a Main Entry if you are linking the tag(s) to another entry.

Add a tag in the authority record.

Add a subfield in the authority record. Multiple subfields should be entered without commas or spaces.

Add either a value of 1, 2, or leave empty if not applicable for the Non-filing indicator field to denote the which will be the non-filing indicator.

Click Save.

Create the corresponding tag in the bibliographic record that should contain this information. Click the None link in the Controlled Bib Fields column.

Click New Control Set Bib Field.

Add the corresponding tag in the bibliographic record.

Click Save.

55.4. Browse Axes

Authority records can be browsed, by default, along five axes: author, series, subject, title, and topic. Use the Browse Axes feature to create additional axes.

55.4.1. Create a new Browse Axis

Click Admin → Server Administration → Authorities → Browse Axes

Click New Browse Axis.

Add a code. Do not enter any spaces.

Add a name to the axis that will appear in the OPAC. Enter any number of characters.

Add a description of the axis. Enter any number of characters.

Add a sorter attribute. The sorter attribute indicates the order in which the results will be displayed.

Assign the axis to an authority so that users can find the authority record when browsing authorities. Click Admin → Server Administration → Authorities → Control Sets.

Choose the control set to which you will add the axis. Click Authority Fields

Click the link in the Axes column of the tag of your choice.

Click New Browse Axis-Authority Field Map.

Select an Axis from the drop down menu.

Click Save.

Permissions to use this Feature

To use authority control sets, you will need the following permissions:

CREATE_AUTHORITY_CONTROL_SET

UPDATE_AUTHORITY_CONTROL_SET

DELETE_AUTHORITY_CONTROL_SET

Chapter 56. Best-Hold Selection Sort Order

Best-Hold Selection Sort Order allows libraries to configure customized rules for Evergreen to use to select the best hold to fill at opportunistic capture. When a copy is captured for a hold upon check-in, Evergreen evaluates the holds in the system that the item could fill. Evergreen uses a set of rules, or a Best-Hold Selection Sort Order, to determine the best hold to fill with the item. In previous version of Evergreen, there were two sets of rules for Evergreen to use to determine the best hold to fulfill: Traditional and FIFO (First In, First Out). Traditional uses Org Unit Proximity to identify the nearest hold to fill. FIFO follows a strict order of first-in, first-out rules. This feature allows new, custom Best-Hold Selection Sort Orders to be created. Existing Best-Hold Selection Sort Orders can also be modified.

56.1. Preconfigured Best-Hold Orders

Evergreen comes with six preconfigured Best-Hold Selection Sort Orders to choose from:

Traditional

Traditional with Holds-go-home

Traditional with Holds-always-go-home

FIFO

FIFO with Holds-go-home

FIFO with Holds-always-go-home

The Holds-go-home and Holds-always-go-home options allow libraries to determine how long they want to allow items to transit outside of the item’s home library, before it must return to its home library to fulfill any holds that are to be picked up there. Libraries can set this time limit in the library setting Holds: Max foreign-circulation time. The Library Settings Editor can be found under Admin → Local Administration → Library Settings Editor.

56.2. Create a New Best-Hold Selection Sort Order

To create a new Best-Hold Selection Sort Order, go to Admin → Server Administration → Best-Hold Selection Sort Order.

Click Create New.

Assign your Best-Hold Selection Sort Order a Name.

Next, use the Move Up and Move Down buttons to arrange the fields in the order that you would like Evergreen to check when looking for the best hold to fill with a copy at opportunistic capture.

Click Save Changes to create your custom Best-Hold Selection Sort Order.

56.3. Edit an Existing Best-Hold Selection Sort Order

To edit an existing Best-Hold Selection Sort Order, go to Admin → Server Administration → Best-Hold Selection Sort Order.

Click Edit Existing.

Choose the Best-Hold Selection Sort Order that you would like to edit from the drop down menu.

Next, use the Move Up and Move Down buttons to arrange the fields in the new order that you would like Evergreen to check when looking for the best hold to fill with a copy at opportunistic capture.

Click Save Changes to save your edits.

56.4. Choosing the Best-Hold Selection Sort Order

The Best-Hold Selection Sort Order can be set for an Org Unit in the Library Settings Editor.

To select the Best-Hold Selection Sort Order that your Org Unit will use:

Go to Admin → Local Administration → Library Settings Editor.

Locate the setting Holds: Best-hold selection sort order, and click Edit.

Choose the Context org unit for this setting.

Select the Best-hold selection sort order, or Value, from the drop down menu.

Click Update Setting.

56.5. Permissions to use this Feature

To administer the custom Best-Hold Selection Sort Order interface, you need the following permission:

ADMIN_HOLD_CAPTURE_SORT

Chapter 57. Booking Module Administration

57.1. Creating Bookable Non-Bibliographic Resources

Staff with the required permissions (Circulator and above) can create bookable non-bibliographic resources such as laptops, projectors, and meeting rooms.

The following pieces make up a non-bibliographic resource:

Resource Type

Resource Attribute

Resource Attribute Values

Resource

Resource Attribute Map

You need to create resource types and resource attributes (features of the resource types), and add booking items (resources) to individual resource type. Each resource attribute may have multiple values. You need to link the applicable features (resource attributes and values) to individual item (resource) through the Resource Attribute Map. Before you create resources (booking items) you need to have a resource type and associated resource attributes and values, if any, for them.

57.1.1. Create New Resource Type

1) Select Admin -→ Server Administration -→ Booking -→ Resource Types.

2) A list of current resource types will appear. Use Back and Next buttons to browse the whole list.

You may also see cataloged items in the list. Those items have been marked bookable or booked before.

3) To create a new resource type, click New Resource Type in the top right corner, .

4) A box will appear in which you create your new type of resource.

Resource Type Name - Give your resource a name.

Fine Interval - How often will fines be charged? This period can be input in several ways:

second(s), minute(s), hour(s), day(s), week(s), month(s), year(s)

sec(s), min(s)

s, m, h

00:00:30, 00:01:00, 01:00:00

Fine Amount - The amount that will be charged at each Fine Interval.

Owning Library - The home library of the resource.

Catalog Item - (Function not currently available.)

Transferable - This allows the item to be transferred between libraries.

Inter-booking and Inter-circulation Interval - The amount of time required by your library between the return of a resource and a new reservation for the resource. This interval uses * the same input conventions as the Fine Interval.

Max Fine Amount - The amount at which fines will stop generating.

5) Click Save when you have entered the needed information.

6) The new resource type will appear in the list.

57.1.2. Create New Resource Attribute

1) Select Server Administration -→ Booking -→ Resource Attributes.

2) Click New Resource Attribute in the top right corner.

3) A box will appear in which you can add the attributes of the resource. Attributes are categories of descriptive information that are provided to the staff member when the booking request is made. For example, an attribute of a projector may be the type of projector. Other attributes might be the number of seats available in a room, or the computing platform of a laptop.

Resource Attribute Name - Give your attribute a name.

Owning Library - The home library of the resource.

Resource Type - Type in the first letter to list then choose the Resource Type to which the Attribute is applicable.

Is Required - (Function not currently available.)

4) Click Save when the necessary information has been entered.

5) The added attribute will appear in the list.

One resource type may have multiple attributes. You may repeat the above procedure to add more.

57.1.3. Create New Resource Attribute Value

1) One resource attribute may have multiple values. To add new attribute value, select Server Administration → Booking → Resource Attribute Values.

2) Click New Resource Attribute Value in the top right corner.

3) A box will appear in which you assign a value to a particular attribute. Values can be numbers, words, or a combination of them, that describe the particular aspects of the resource that have been defined as Attributes. As all values appear on the same list for selection, values should be as unique as possible. For example, a laptop may have a computing platform that is either PC or Mac.

Owning Library - The home library of the resource.

Resource Attribute - The attribute you wish to assign the value to.

Valid Value - Enter the value for your attribute.

4) Click Save when the required information has been added.

5) The attribute value will appear in the list. Each attribute should have at least two values attached to it; repeat this process for all applicable attribute values.

57.1.4. Create New Resource

1) Add items to a resource type. Click Admin → Server Administration → Booking → Resources.

2) Click New Resource in the top right corner.

3) A box will appear. Add information for the resource.

Owning Library - The home library of the resource.

Resource Type - Type in the first letter of the resource type’s name to list then select the resource type for your item.

Barcode - Barcode for the resource.

Overbook - This allows a single item to be reserved, picked up, and returned by multiple patrons during overlapping or identical time periods.

Is Deposit Required - (Function not currently available.)

Deposit Amount - (Function not currently available.)

User Fee - (Function not currently available.)

4) Click Save when the required information has been added.

5) The resource will appear in the list.

One resource type may have multiple resources attached.

57.1.5. Map Resource Attributes and Values to Resources

1) Use Resource Attribute Maps to bring together the resources and their attributes and values. Select Admin → Server Administration → Booking → Resource Attribute Maps.

2) Click New Resource Attribute Map in the right top corner.

3) A box will appear in which you will map your attributes and values to your resources.

Resource - Enter the barcode of your resource.

Resource Attribute - Select an attribute that belongs to the Resource Type.

Attribute Value - Select a value that belongs to your chosen attribute and describes your resource. If your attribute and value do not belong together you will be unable to save.

4) Click Save once you have entered the required information.

A resource may have multiple attributes and values. Repeat the above steps to map all.

5) The resource attribute map will appear in the list.

Once all attributes have been mapped your resource will be part of a hierarchy similar to the example below.

57.2. Editing Non-Bibliographic Resources

Staff with the required permissions can edit aspects of existing non-bibliographic resources. For example, resource type can be edited in the event that the fine amount for a laptop changes from $2.00 to $5.00.

57.2.1. Editing Resource Types

1) Bring up your list of resource types. Select Admin -→ Server Administration -→ Booking -→ Resource Types.

2) A list of current resource types will appear.

3) Double click anywhere on the line of the resource type you would like to edit.

4) The resource type box will appear. Make your changes and click Save.

5) Following the same procedure you may edit Resource Attributes, Attributes Values, Resources and Attribute Map by selecting them on Admin -→ Server Administration -→ Booking menu.

57.3. Deleting Non-bibliographic Resources

1) To delete a booking resource, go to Admin → Server Administration → Booking → Resources.

2) Select the checkbox in front the resource you want to delete. Click Delete Selected. The resource will disappear from the list.

Following the same procedure you may delete Resource Attributes Maps.

You may also delete Resource Attribute Values, Resource Attributes and Resource Types. But you have to delete them in the reverse order when you create them to make sure the entry is not in use when you try to delete it.

This is the deletion order: Resource Attribute Map/Resources -→ Resource Attribute Values -→ Resource Attributes -→ Resource Types.

Chapter 58. Call Number Prefixes and Suffixes

You can configure call number prefixes and suffixes in the Admin module. This feature ensures more precise cataloging because each cataloger will have access to an identical drop down menu of call number prefixes and suffixes that are used at his library. In addition, it may streamline cataloging workflow. Catalogers can use a drop down menu to enter call number prefixes and suffixes rather than entering them manually. You can also run reports on call number prefixes and suffixes that would facilitate collection development and maintenance.

58.1. Configure call number prefixes

Call number prefixes are codes that precede a call number.

To configure call number prefixes:

Select Admin → Server Administration → Call Number Prefixes.

Click New Prefix.

Enter the call number label that will appear on the item.

Select the owning library from the drop down menu. Staff at this library, and its descendant org units, with the appropriate permissions, will be able to apply this call number prefix.

Click Save.

58.2. Configure call number suffixes

Call number suffixes are codes that succeed a call number.

To configure call number suffixes:

Select Admin → Server Administration → Call Number Suffixes.

Click New Suffix.

Enter the call number label that will appear on the item.

Select the owning library from the drop down menu. Staff at this library, and its descendant org units, with the appropriate permissions, will be able to apply this call number suffix.

Click Save.

58.3. Apply Call Number Prefixes and Suffixes

You can apply call number prefixes and suffixes to items from a pre-configured list in the Unified Volume/Copy Creator. See the document, Unified Volume/Copy Creator, for an example.

Chapter 59. Cash Reports

Cash reports are useful for quickly getting information about money that your library has collected from patrons. This can be helpful in a few different scenarios, such as:

Reconciling a cash drawer at the end of the day.

Seeing how popular a specific payment type is (perhaps when evaluating a food-for-fines program).

To use the cash reports,

Under the Administration menu, choose Local Administration.

Click Cash reports.

Select the time period and library you are interested in. This interface defaults to showing payments accepted during the current day.

Click Submit.

You can click on the names of columns to sort the reports.

You need the VIEW_TRANSACTION permission to view these reports.

These payments are divided into two different types: Desk payments — in which a staff member simply accepted a credit card, check, or cash payment — and User payments — in which a staff member had to make a specific decision about whether to accept a payment of goods or work; or forgave or granted credit to a particular patron.

Chapter 60. Circulation Limit Sets

60.1. Maximum Checkout by Copy Location

This feature enables you to specify the maximum number of checkouts of items by copy location and is an addition to the circulation limit sets. Circulation limit sets refine circulation policies by limiting the number of items that users can check out. Circulation limit sets are linked by name to circulation policies.

To limit checkouts by copy location:

Click Admin → Local Administration → Circulation Limit Sets.

Click New to create a new circulation limit set.

In the Owning Library field, select the library that can create and edit this limit set.

Enter a Name for the circulation set. You will select the Name to link the circulation limit set to a circulation policy.

Enter the number of Items Out that a user can take from this copy location.

Enter the Min Depth, or the minimum depth in the org tree that Evergreen will consider as valid circulation libraries for counting items out. The min depth is based on org unit type depths. For example, if you want the items in all of the circulating libraries in your consortium to be eligible for restriction by this limit set when it is applied to a circulation policy, then enter a zero (0) in this field.

Check the box adjacent to Global Flag if you want all of the org units in your consortium to be restricted by this limit set when it is applied to a circulation policy. Otherwise, Evergreen will only apply the limit to the direct ancestors and descendants of the owning library.

Enter a brief Description of the circulation limit set.

Click Save.

To link the circulation limit set to a circulation policy:

Click Admin → Local Administration → Circulation Policies

Select an existing circulation policy, or create a new one.

Scroll down to the Linked Limit Sets.

Select the Name of the limit set that you want to add to the circulation policy.

Click Add.

Click Save.

Chapter 61. Copy Status

To navigate to the copy status editor from the staff client menu, select Admin → Server Administration → Copy Statuses.

The Copy Status Editor is used to add, edit and delete statuses of copies in your system.

For each status, you can set the following properties:

Holdable - If checked, users can place holds on copies in this status, provided there are no other flags or rules preventing holds. If unchecked, users cannot place holds on copies in this status.

OPAC Visible - If checked, copies in this status will be visible in the public catalog. If unchecked, copies in this status will not be visible in the public catalog, but they will be visible when using the catalog in the staff client.

Sets copy active - If checked, moving a copy that does not yet have an active date to this status will set the active date. If the copy already has an active date, then no changes will be made to the active date. If unchecked, this status will never set the copy’s active date.

Is Available - If checked, copies with this status will appear in catalog searches where "limit to available" is selected as a search filter. Also, copies with this status will check out without status warnings. By default, the "Available" and "Reshelving" statuses have the "Is Available" flag set. The flag may be applied to local/custom statuses via the copy status admin interface.

Evergreen comes pre-loaded with a number of copy statuses.

Table 61.1. Stock copy statuses and default settings

ID
Name
Holdable
OPAC Visible
Sets copy active

0

Available

true

true

true

1

Checked out

true

true

true

2

Bindery

false

false

false

3

Lost

false

false

false

4

Missing

false

false

false

5

In process

true

true

false

6

In transit

true

true

false

7

Reshelving

true

true

true

8

On holds shelf

true

true

true

9

On order

true

true

false

10

ILL

false

false

true

11

Cataloging

false

false

false

12

Reserves

false

true

true

13

Discard/Weed

false

false

false

14

Damaged

false

false

false

15

On reservation shelf

false

false

true

16

Long Overdue

false

false

false

17

Lost and Paid

false

false

false

61.1. Adding Copy Statuses

In the New Status field, enter the name of the new status you wish to add.

Click Add.

Locate your new status and check the Holdable check box if you wish to allow users to place holds on items in this status. Check OPAC Visible if you wish for this status to appear in the public catalog. Check Sets copy active if you wish for this status to set the active date for new items.

Click Save Changes at the bottom of the screen to save changes to the new status.

61.2. Deleting Copy Statuses

Highlight the statuses you wish to delete. Ctrl-click to select more than one status.

Click Delete Selected.

Click OK to verify.

You will not be able to delete statuses if copies currently exist with that status.

61.3. Editing Copy Statuses

Double click on a status name to change its name. Enter the new name.

To change whether a status is holdable, visible in the OPAC, or sets the copy’s active date, check or uncheck the relevant checkbox.

Once you have finished editing the statuses, remember to click Save Changes.

Chapter 62. Floating Groups

Before floating groups copies could float or not. If they floated then they floated everywhere, with no restrictions.

After floating groups where a copy will float is defined by what group it has been assigned to.

62.1. Floating Groups

Each floating group comes with a name and a manual flag, plus zero or more group members. The name is used solely for selection and display purposes.

The manual flag dictates whether or not the "Manual Floating Active" checkin modifier needs to be active for a copy to float. This allows for greater control over when items float. It also prevents automated checkins via SIP2 from triggering floats.

62.2. Floating Group Members

Each member of a floating group references an org unit and has a stop depth, an optional max depth, and an exclude flag.

62.2.1. Org Unit

The org unit and all descendants are included, unless max depth is set, in which case the tree is cut off at the max depth.

62.2.2. Stop Depth

The stop depth is the highest point from the current copy circ library to the checkin library for the item that will be traversed. If the item has to go higher than the stop depth on the tree the member rule in question is ignored.

62.2.3. Max Depth

As mentioned with the org unit, the max depth is the furthest down on the tree from the org unit that gets included. This is based on the entire tree, not just off of the org unit. So in the default tree a max depth of 1 will stop at the system level no matter if org unit is set to CONS or SYS1.

62.2.4. Exclude

Exclude, if set, causes floating to not happen for the member. Excludes always take priority, so you can remove an org unit from floating without having to worry about other rules overriding it.

62.3. Examples

62.3.1. Float Everywhere

This is a default floating rule to emulate the previous floating behavior for new installs and upgrades.

One member:

Org Unit: CONS

Stop Depth: 0

Max Depth: Unset

Exclude: Off

62.3.2. Float Within System

This would permit a copy to float anywhere within a system, but would return to the system if it was returned elsewhere.

One member:

Org Unit: CONS

Stop Depth: 1

Max Depth: Unset

Exclude: Off

62.3.3. Float To All Branches

This would permit a copy to float to any branch, but not to sublibraries or bookmobiles.

One member:

Org Unit: CONS

Stop Depth: 0

Max Depth: 2

Exclude: Off

62.3.4. Float To All Branches Within System

This would permit a copy to float to any branch in a system, but not to sublibraries or bookmobiles, and returning to the system if returned elsewhere.

One member:

Org Unit: CONS

Stop Depth: 1

Max Depth: 2

Exclude: Off

62.3.5. Float Between BR1 and BR3

This would permit a copy to float between BR1 and BR3 specifically, excluding sublibraries and bookmobiles.

It would consist of two members, identical other than the org unit:

Org Unit: BR1 / BR3

Stop Depth: 0

Max Depth: 2

Exclude: Off

62.3.6. Float Everywhere Except BM1

This would allow an item to float anywhere except for BM1. It accomplishes this with two members.

The first includes all org units, just like Float Everywhere:

Org Unit: CONS

Stop Depth: 0

Max Depth: Unset

Exclude: Off

The second excludes BM1:

Org Unit: BM1

Stop Depth: 0

Max Depth: Unset

Exclude: On

That works because excludes are applied first.

62.3.7. Float into, but not out of, BR2

This would allow an item to float into BR2, but once there it would never leave. Why you would want to allow items to float to but not from a single library I dunno, but here it is. This takes advantage of the fact that the rules say where we can float to, but outside of stop depth don’t care where we are floating from.

One member:

Org Unit: BR2

Stop Depth: 0

Max Depth: Unset

Exclude: Off

Chapter 63. MARC Import Remove Fields

MARC Import Remove Fields allows staff to configure MARC tags to be automatically removed from bibliographic records when they are imported into Evergreen. This feature allows specific MARC tags to be removed from records that are imported through three different interfaces:

Cataloging → Import Record from Z39.50

Cataloging → MARC Batch Import/Export

Acquisitions → Load MARC Order Records

63.1. Create a MARC Import Remove Fields profile

To create a MARC Import Remove Fields profile, go to Admin → Server Administration → MARC Import Remove Fields.

Click New Field Group.

Assign the Field Group a Label. This label will appear in the import interfaces.

Assign an Org Unit Owner.

Check the box next to Always Apply if you want Evergreen to apply this Remove Fields profile to all MARC records that are imported through the three affected interfaces. If you do not select Always Apply, staff will have the option to choose which Remove Fields profile to use when importing records.

Click Save.

The profile that you created will now appear in the list of MARC Import Remove Fields.

Click on the hyperlinked ID number. This will bring you into the Remove Fields profile to configure the MARC tags to be removed.

Click New Field.

In the Field, enter the MARC tag to be removed.

Click Save.

Add New Fields until you have configured all the tags needed for this profile.

Click Return to Groups to go back to the list of Remove Field profiles.

63.2. Import Options

The Label for each of the MARC Import Remove Fields profiles will appear on the three affected import screens. To select a profile, check the box next to the desired Label before importing the records.

Cataloging → Import Record from Z39.50

Cataloging → MARC Batch Import/Export

Acquisitions → Load MARC Order Records

63.3. Permissions to use this Feature

The following permissions are required to use this feature:

CREATE_IMPORT_TRASH_FIELD

UPDATE_IMPORT_TRASH_FIELD

DELETE_IMPORT_TRASH_FIELD

Chapter 64. MARC Record Attributes

The MARC Record Attribute Definitions support the ingesting, indexing, searching, filtering, and delivering of bibliographic record attributes.

To Access the MARC Record Attributes, click Admin → Server Administration → MARC Record Attributes

64.1. Multi Valued Fields and Composite Record Attributes

Multi Valued Fields and Composite Record Attributes expands upon the Record Attribute Definitions feature to include capturing all occurrences of multi-valued elements in a record. Multi Valued Fields allows users to say that a bibliographic record contains multiple entries for a particular record attribute. Composite Record Attributes supports the application of a more complicated and nested form of structure to a record attribute definition.

64.1.1. Multi Valued Fields

Multi Valued Fields allows for the capturing of multi-valued elements of a bibliographic record. Through the use of Multi Valued Fields, Evergreen recognizes that records are capable of storing multiple values. Multi Valued Fields are represented in the Record Attribute Definitions interface by a column named Multi-valued?. With Multi-valued? set to True, Evergreen will recognize the bibliographic records in the database that have multiple values mapping to the record attribute definition; it will also track and search on those values in the catalog. This feature will be particularly handy for bibliographic records representing a Blu-ray / DVD combo pack, since both format types can be displayed in the OPAC (if both formats were cataloged in the record).

To edit an existing record attribute definition and set the Multi-valued? field to True:

Click Admin on the menu bar

Hover over Server Administration and click MARC Record Attributes

Double-click on the row of the record attribute definition that needs to be edited

Select the Multi-valued? checkbox

Click Save

64.1.2. Composite Record Attributes

Composite Record Attributes build on top of Evergreen’s ability to support record attributes that contain multiple entries. The Composite Record Attributes feature enables administrators to take a record attribute definition and apply a more complicated and nested form of structure to that particular record attribute. Two new Record Attribute Definitions columns have been added to facilitate the management of the Composite Record Attributes. The Composite attribute? column designates whether or not a particular record attribute definition is also a composite record attribute. The Coded Value Maps column contains a Manage link in each row that allows users to manage the Coded Value Maps for the record attributes.

64.1.3. Coded Value Maps

To manage the Coded Value Maps of a particular record attribute definition, click the Manage link located under the Coded Value Maps column for that record attribute. This will open the Coded Value Maps interface. What administrators see on the Coded Value Maps screen does not define the structure of the composite record attribute; they must go into the Composite Attribute Entry Definitions screen to view this information.

Within the Coded Value Maps screen, there is a column named Composite Definition. The Composite Definition column contains a Manage link that allows users to configure and to edit Composite Record Attribute definitions. In order to enable the Manage link (i.e. have the Manage link display as an option under the Composite Definition column), the Composite attribute? column (located back in the Record Attributes Definition page) must be set to True.

To edit an existing record attribute definition and set the Composite attribute? field to True:

Click Admin on the menu bar

Hover over Server Administration and click MARC Record Attributes

Double-click on the row of the record attribute definition that needs to be edited

Select the Composite attribute? checkbox

Click Save

Now that the Composite attribute? value is set to True, click on the Manage link located under the Coded Value Maps column for the edited record attribute definition. Back in the Coded Value Maps screen, a Manage link should now be exposed under the Composite Definition column. Clicking on a specific coded value’s Manage link will take the user into the Composite Attribute Entry Definitions screen for that specified coded value.

64.1.4. Composite Attribute Entry Definitions

The Composite Attribute Entry Definitions screen is where administrators can locally define and edit Composite Record Attributes for specific coded values. For example: administrators can further refine and distinguish the way a “book” should be defined within their database, by bringing together the right combination of attributes together to truly define what a “book” is in their database.

The top of the Composite Attribute Entry Definitions screen shows a parenthetically defined view of the Composite Data Expression. Below the Composite Data Expression is the Composite Data Tree. The Composite Data Tree is structured off of Boolean Operators, including the support of NOT operations. This nested form can be as deeply defined as it needs to be within the site’s database.

To modify the Composite Attribute Entry Definition, any Boolean Operator can be deleted or have a coded value appended to it. The appended coded value can be any number of Coded Value Maps from any other Record Attribute Definition. So, administrators can choose from all the other existing record attribute definitions and create new nested structures to define entirely new data types.

To modify the Composite Attribute Entry Definition:

Click Add Child for the specific Boolean Operator that needs to be modified, and a new window will open

Select which Record Attribute needs to be represented in the structure under that particular Boolean Operator

Select the Attribute Type from the dropdown options

Select the Value of the Attribute Type from the dropdown options (dropdown options will be based on the Attribute Type selected)

Click Submit

The Composite Data Expression should now include the modification

Once all modifications have been made, click Save Changes on the Composite Attribute Entry Definitions page

64.1.5. Search and Icon Formats

64.1.5.1. Search and Icon Formats

The table below shows all the search and icon formats. In some cases they vary slightly, with the icon format being more restrictive. This is so that things such as a search for "All Books" will include Large Print books yet Large Print books will not show both a "Book" and "Large Print Book" icon.

In the table below "Icon Format Only" portions of the definition are italicized and in square brackets: [Icon format only data]

The definitions use the fixed field types at the end of this document.

Icon

Search Label/Icon Label

Definition

Blu-ray

VR Format:s

All books/Book

Item Type: a,t

Bib Level: a,c,d,m

NOT: Item Form: a,b,c,f,o,q,r,s [,d]

Braille

Item Type: a

Item Form: f

Cassette audiobook

Item Type: i

SR Format: l

Audiocassette music recording

Item Type: j

SR Format: l

CD audiobook

Item Type: i

SR Format: f

CD music recording

Item Type: j

SR Format: f

DVD

VR Format: v

E-audio

Item Type: i

Item Form: o,q,s

E-book

Item Type: a,t

Bib Level: a,c,d,m

Item Form: o,q,s

Equipment, games, toys

Item Type: r

E-video

Item Type: g

Item Form: o,q,s

Kit

Item Type: o,p

Large print book

Item Type: a,t

Bib Level: a,c,d,m

Item Form: d

Map

Item Type: e,f

Microform

Item Form: a,b,c

All music/Music sound recording (unknown format)

Item Type: j

[NOT: SR Format: a,b,c,d,e,f,l]

Phonograph music recording

Item Type: j

SR Format: a,b,c,d,e

Phonograph spoken recording

Item Type: i

SR Format: a,b,c,d,e

Picture

Item type: k

Music score

Item type: c,d

Serials and magazines

Bib Level: b,s

Software and video games

Item Type: m

VHS

VR Format: b

64.1.5.2. Record Types

This table shows the record types currently used in determining elements of search and icon formats. They are based on a combination of the MARC Record Type (LDR 06) and Bibliographic Level (LDR 07) fixed fields.

Record Type

LDR 06

LDR 07

BKS

a,t

a,c,d,m

MAP

e,f

a,b,c,d,i,m,s

MIX

p

c,d,i

REC

i,j

a,b,c,d,i,m,s

SCO

c,d

a,b,c,d,i,m,s

SER

a

b,i,s

VIS

g,k,r,o

a,b,c,d,i,m,s

64.1.5.3. Fixed Field Types

This table details the fixed field types currently used for determining search and icon formats. See the record types section above for how the system determines them.

Label

Record Type

Tag

Position

Item Type

ANY

LDR

06

Bib Level

ANY

LDR

07

Item Format

BKS

006

06

008

23

MAP

006

12

008

29

MIX

006

06

008

23

REC

006

06

008

23

SCO

006

06

008

23

SER

006

06

008

23

VIS

006

12

008

29

SR Format

ANY

007s

03

VR Format

ANY

007v

04

Chapter 65. Org Unit Proximity Adjustments

65.1. Org Unit Proximity Adjustments

Org Unit Proximity Adjustments allow libraries to indicate lending preferences for holds between libraries in an Evergreen consortium. When a hold is placed in Evergreen, the hold targeter looks for copies that can fill the hold. One factor that the hold targeter uses to choose the best copy to fill the hold is the distance, or proximity, between the capturing library and the pickup library for the request. The proximity is based on the number of steps through the org tree that it takes to get from one org unit to another.

Org Unit Proximity between BR1 and BR4 = 4

Org Unit Proximity Adjustments allow libraries to customize the distances between org units, which provides more control over which libraries are looked at when targeting copies to fill a hold. Evergreen can also be configured to take Org Unit Proximity Adjustments into account during opportunistic capture through the creation of a custom Best-Hold Selection Sort Order. See documentation <here> for more information on Best-Hold Selection Sort Order.

An Org Unit Proximity Adjustment can be created to tell Evergreen which libraries to look at first for copies to fill a hold or which library to look at last. This may be useful for accounting for true transit costs or physical distances between libraries. It can also be used to identify libraries that have special lending agreements or preferences. Org Unit Proximity Adjustments can be created for all holds between two org units, or they can be created for holds on specific Copy Locations and Circulation Modifiers.

65.2. Absolute and Relative Adjustments

Two types of proximity adjustments can be created in Evergreen: Absolute adjustments and Relative adjustments.

Absolute proximity adjustments allow you to replace the default proximity distance between two org units. An absolute adjustment could be made to tell the hold targeter to look at a specific library or library system first to find an item to fill a hold, before looking elsewhere in the consortium.

Relative proximity adjustments allows the proximity between org units to be treated as closer or farther from one another than the default distance. A relative proximity adjustment could be used to identify a library that has limited hours or slow transit times to tell the hold targeter to look at that library last for copies to fill a hold.

65.3. Create an Org Unit Proximity Adjustment

To create an Org Unit Proximity Adjustment between two libraries:

In the Admin menu choose Server Administration → Org Unit Proximity Adjustments.

Click New OU Proximity Adjustment.

Choose an Item Circ Lib from the drop down menu.

Choose a Hold Request Lib from the drop down menu.

If this proximity adjustment applies to a specific copy location, select the appropriate Copy Location from the drop down menu.

If this proximity adjustment applies to a specific material type, select the appropriate Circ Modifier from the drop down menu.

If this is an Absolute proximity adjustment, check the box next to Absolute adjustment? If you leave the box blank, a relative proximity adjustment will be applied.

Enter the Proximity Adjustment between the Item Circulating Library and the Request Library.

Click Save.

This will create a one-way proximity adjustment between Org Units. In this example this adjustment will apply to items requested at by a patron BR4 and filled at BR1. To create the reciprocal proximity adjustment, for items requested at BR1 and filled at BR4, create a second proximity adjustment between the two Org Units.

65.4. Permissions to use this Feature

To create Org Unit Proximity Adjustments, you will need the following permission:

ADMIN_PROXIMITY_ADJUSTMENT

Chapter 66. User and Group Permissions

It is essential to understand how user and group permissions can be used to allow staff to fulfill their roles while ensuring that they only have access to the appropriate level.

Permissions in Evergreen are applied to a specific location and system depth based on the home library of the user. The user will only have that permission within the scope provided by the Depth field in relation to his/her working locations.

Evergreen provides group application permissions in order to restrict which staff members have the ability to assign elevated permissions to a user, and which staff members have the ability to edit users in particular groups.

66.1. Staff Accounts

New staff accounts are created in much the same way as patron accounts, using Circulation → Register Patron or Shift+F1. Select one of the staff profiles from the Profile Group drop-down menu.

Each new staff account must be assigned a Working Location which determines its access level in staff client interfaces.

To assign a working location open the newly created staff account using F1 (retrieve patron) or F4 (patron search).

Select Other → User Permission Editor

Place a check in the box next to the desired working location, then scroll to the bottom of the display and click Save.

In multi-branch libraries it is possible to assign more than one working location

66.1.1. Staff Account Permissions

To view a detailed list of permissions for a particular Evergreen account go to Admin (-) → User permission editor in the staff client.

66.1.2. Granting Additional Permissions

A Local System Administrator (LSA) may selectively grant LSA permissions to other staff accounts. In the example below a Circ +Full Cat account is granted permission to process offline transactions, a function which otherwise requires an LSA login.

Log in as a Local System Administrator.

Select Admin (-) → User Permission Editor and enter the staff account barcode when prompted

OR

Retrieve the staff account first, then select Other → User Permission Editor

The User Permission Editor will load (this may take a few seconds). Greyed-out permissions cannot be edited because they are either a) already granted to the account, or b) not available to any staff account, including LSAs.

1) List of permission names.

2) If checked the permission is granted to this account.

3) Depth limits application to the staff member’s library and should be left at the default.

4) If checked this staff account will be able to grant the new privilege to other accounts (not recommended).

To allow processing of offline transactions check the Applied column next to OFFLINE_EXECUTE.

Scroll down and click Save to apply the changes.

Chapter 67. SMS Text Messaging

The SMS Text Messaging feature enables users to receive hold notices via text message. Users can opt-in to this hold notification as their default setting for all holds, or they can receive specific hold notifications via text message. Users can also send call numbers and copy locations via text message.

67.1. Administrative Setup

You cannot receive text messages from Evergreen by default. You must enable this feature to receive hold notices and copy information from Evergreen via text message.

67.1.1. Enable Text Messages

Click Admin → Local Admin → Library Settings Editor.

Select the setting, Enable features that send SMS text messages.

Set the value to True, and click Update Setting.

67.1.2. Authenticate Patrons

By default, you must be logged into your OPAC account to send a text message from Evergreen. However, if you disable this setting, you can text message copy information without having to login to your OPAC account.

To disable the patron login requirement:

Click Admin → Local Administration → Library Settings Editor.

Select the setting, Disable auth requirement for texting call numbers.

Set the value to True, and click Update Setting.

67.1.3. Configure SMS Carriers

A list of SMS carriers that can transmit text messages to users is available in the staff client. Library staff can edit this list, or add new carriers.

To add or edit SMS carriers:

Click Admin → Server Administration → SMS Carriers.

To add a new carrier, click the New Carrier button in the top right corner of the screen. To edit an existing carrier, double click in any white space in the carrier’s row.

Enter a (geographical) Region.

Enter the carrier’s Name.

Enter an Email Gateway. The SMS carrier can provide you with the content for this field. The $number field is converted to the user’s phone number when the text message is generated.

Check the Active box to use this SMS Carrier.

67.1.4. Configure Text Message Templates

Library staff control the content and format of text messages through the templates in Notifications/Action Triggers. Patrons cannot add free text to their text messages.

To configure the text of the SMS text message:

Click Admin → Local Administration → Notifications/Action Triggers.

Create a new A/T and template, or use or modify an existing template. For example, a default template, "Hold Ready for Pickup SMS Notification," notifies users that the hold is ready for pickup.

You can use the default template, or you can edit the template and add content specific to your library. Click the hyperlinked name to view and/or edit the hold notice.

67.2. Receiving Holds Notices via Text Message

You can receive notification that your hold is ready for pickup from a text message that is sent to your mobile phone.

Login to your account.

Search the catalog.

Retrieve a record, and click the Place Hold link.

Select the option to retrieve hold notification via text message.

Choose an SMS Carrier from the drop down menu. NOTE: You can enter your SMS carrier and phone number into your Account Preferences to skip steps five and six.

Enter a phone number.

Click Submit.

67.3. Sending Copy Details via Text Message

You can search the catalog for an item, and, after retrieving results for the item, click a hyperlink to send the copy information in a text message.

Login to your account in the OPAC. NOTE: If you have disabled the setting that requires patron login, then you do not have to login to their accounts to send text messages. See Administrative Setup for more information.

Search the catalog, and retrieve a title with copies.

Click the Text link next to the call number.

The text of the SMS Text Message appears.

Choose an SMS Carrier from the drop down menu. NOTE: You can enter your SMS carrier and phone number into your Account Preferences to skip steps five and six.

Enter a phone number.

Click Submit. NOTE: Message and data rates may apply.

The number and carrier are converted to an email address, and the text message is sent to your mobile phone. The following confirmation message will appear.

Permissions to use this Feature

ADMIN_SMS_CARRIER - Enables users to add/create/delete SMS Carrier entries.

Chapter 68. User Activity Types

The User Activity Types feature enables you to specify the user activity that you want to record in the database. You can use this feature for reporting purposes. This function will also display a last activity date in a user’s account.

68.1. Enabling this Feature

Click Admin → Server Administration → User Activity Types to access the default set of user activity types and to add new ones. The default set of user activity types records user logins to the Evergreen ILS and to third party products that communicate with Evergreen.

The Label is a free text field that enables you to describe the activity that you are tracking.

The Event Caller describes the third party software or Evergreen interface that interacts with the Evergreen database and is responsible for managing the communication between the parties.

The Event Type describes the type of activity that Evergreen is tracking. Currently, this feature only tracks user authentication.

The Event Mechanism describes the framework for communication between the third party software or OPAC and the database. Enter an event mechanism if you want to track the means by which the software communicates with the database. If you do not want to track how the softwares communicate, then leave this field empty.

The Enabled field allows you to specify which types of user activity that you would like to track.

The Transient column enables you to decide how many actions you want to track. If you want to track only the last activity, then enter True. If you want to trace all activity by the user, enter False.

68.2. Using this Feature

The last activity date for user logins appears in the patron’s summary.

Chapter 69. Z39.50 Servers

69.1. Restrict Z39.50 Sources by Permission Group

In Evergreen versions preceding 2.2, all users with cataloging privileges could view all of the Z39.50 servers that were available for use in the staff client. In Evergreen version 2.2, you can use a permission to restrict users' access to Z39.50 servers. You can apply a permission to the Z39.50 servers to restrict access to that server, and then assign that permission to users or groups so that they can access the restricted servers.

69.1.1. Administrative Settings

You can add a permission to limit use of Z39.50 servers, or you can use an existing permission.

You must be authorized to add permission types at the database level to add a new permission.

Add a new permission:

1) Create a permission at the database level.

2) Click Admin → Server Administration → Permissions to add a permission to the staff client.

3) In the New Permission field, enter the text that describes the new permission.

4) Click Add.

5) The new permission appears in the list of permissions.

69.1.2. Restrict Z39.50 Sources by Permission Group

1) Click Admin → Server Administration → Z39.50 Servers

2) Click New Z39.50 Server, or double click on an existing Z39.50 server to restrict its use.

3) Select the permission that you added to restrict Z39.50 use from the drop down menu.

4) Click Save.

5) Add the permission that you created to a user or user group so that they can access the restricted server.

6) Users that log in to the staff client and have that permission will be able to see the restricted Z39.50 server.

As an alternative to creating a new permission to restrict use, you can use a preexisting permission. For example, your library uses a permission group called SuperCat, and only members in this group should have access to a restricted Z39.50 source. Identify a permission that is unique to the SuperCat group (e.g. CREATE_MARC) and apply that permission to the restricted Z39.50 server. Because these users are in the only group with the permission, they will be the only group w/ access to the restricted server.

69.2. Storing Z39.50 Server Credentials

Staff have the option to apply Z39.50 login credentials to each Z39.50 server at different levels of the organizational unit hierarchy. Credentials can be set at the library branch or system level, or for an entire consortium. When credentials are set for a Z39.50 server, searches of the Z39.50 server will use the stored credentials. If a staff member provides alternate credentials in the Z39.50 search interface, the supplied credentials will override the stored ones. Staff have the ability to apply new credentials or clear existing ones in this interface. For security purposes, it is not possible for staff to retrieve or report on passwords.

To set up stored credentials for a Z39.50 server:

1) Go to Admin → Server Administration → Z39.50 Servers.

2) Select a Z39.50 Source by clicking on the hyperlinked source name. This will take you the Z39.50 Attributes for the source.

3) At the top of the screen, select the org unit for which you would like to configure the credentials.

4) Enter the Username and Password, and click Apply Credentials.

Part VII. Local Administration

Chapter 70. Introduction

This part covers the options in the Local Administration menu found in the staff client.

Chapter 71. Library Settings Editor

With the Library Settings Editor one can optionally customize Evergreen’s behavior for a particular library or library system. For descriptions of available settings see the Settings Overview table below.

71.1. Editing Library Settings

To open the Library Settings Editor select Admin → Local Administration → Library Settings Editor.

Settings having effects on the same function or module are grouped together. You may browse the list or search for the entry you want to edit. Type in your search term in the filter box. You may clear or re-apply the filter by clicking Clear Filter or Filter.

To edit an entry click Edit in the line.

Read the instruction in the pop-up window. Make the change. Click Update Setting to save the change. Click Delete Setting if you wish to delete it.

Click History to view the previous values, if any, of a setting. You can revert back to an old value by clicking revert.

Please note that different settings may require different data formats, which are listed in the Settings Overview table. Refer to the Data Types table at the bottom of this page for more information.

71.2. Exporting/Importing Library Settings

To export library settings, click the Export button on the above Library Setting Editor screen. Click Copy in the pop-up window. Those settings displayed on the screen are copied to the clipboard. Paste the contents to a text editor, such as Notepad. Save the file on your computer.

To import library settings, click the Import button on the Library Settings Editor screen. Open your previously saved file and copy the contents. Click Paste in the pop-up window. Click Submit.

71.3. Settings Overview

The settings are grouped together in separate tables based on functions and modules, which are affected by the setting. They are in the same sequence as you see in the staff client. Each table describes the available settings in the group and shows which can be changed on a per-library basis. At the bottom is the table with a list of data types with details about acceptable settings values.

Table 71.1. Acquisitions

Setting
Description
Data type
Notes

Allow funds to be rolled over without bringing money along

Allow funds to be rolled over without bringing the money along. This makes money left in the old fund disappear, modeling its return to some outside entity.

True/False

Allows patrons to create automatic holds from purchase requests.

Allows patrons to create automatic holds from purchase requests.

True/False

Default circulation modifier

Sets the default circulation modifier for use in acquisitions.

Text

Default copy location

Sets the default copy location(shelving location) for use in acquisitions.

Selection list

Fund Spending Limit for Block

When the amount remaining in the fund, including spent money and encumbrances, goes below this percentage, attempts to spend from the fund will be blocked.

Number

Fund Spending Limit for Warning

When the amount remaining in the fund, including spent money and encumbrances, goes below this percentage, attempts to spend from the fund will result in a warning to the staff.

Number

Rollover Distribution Formulae Funds

During fiscal rollover, update distribution formalae to use new funds

True/False

Set copy creator as receiver

When receiving a copy in acquisitions, set the copy "creator" to be the staff that received the copy

True/False

Temporary barcode prefix

Temporary barcode prefix added to temporary item records.

Text

Temporary call number prefix

Temporary call number prefix

Text

Upload Activate PO

Activate the purchase order by default during ACQ file upload

True/False

Upload Create PO

Create a purchase order by default during ACQ file upload

True/False

Upload Default Insufficient Quality Fall-Thru Profile

Default low-quality fall through profile used during ACQ file upload

Selection List

Match Only Merge and Full Overlay are the selections.

Upload Default Match Set

Default match set to use during ACQ file upload

Selection List

Can be set to authority test or biblio

Upload Default Merge Profile

Default merge profile to use during ACQ file upload

Selection List

Match Only Merge and Full Overlay are the selections.

Upload Default Min. Quality Ratio

Default minimum quality ratio used during ACQ file upload

Number

Upload Default Provider

Default provider to use during ACQ file upload

Selection List

This list is populated by your Providers.

Upload Import Non Matching by Default

Import non-matching records by default during ACQ file upload

True/False

Upload Load Items for Imported Records by Default

Load items for imported records by default during ACQ file upload

True/False

Upload Merge on Best Match by Default

Merge records on best match by default during ACQ file upload

True/False

Upload Merge on Exact Match by Default

Merge records on exact match by default during ACQ file upload

True/False

Upload Merge on Single Match by Default

Merge records on single match by default during ACQ file upload

True/False

Table 71.2. Booking and Cataloging

Setting
Description
Data type
Notes

Allow email notify

Permit email notification when a reservation is ready for pick-up.

True/false

Elbow room

Elbow room specifies how far in the future you must make a reservation on an item if that item will have to transit to reach its pick-up location. It secondarily defines how soon a reservation on a given item must start before the check-in process will opportunistically capture it for the reservation shelf.

Duration

Default Classification Scheme

Defines the default classification scheme for new call numbers: 1 = Generic; 2 = Dewey; 3 = LC

Number

It has effect on call number sorting.

Default copy status (fast add)

Default status when a copy is created using the "Fast Item Add" interface.

Selection list

Default: In process

Default copy status (normal)

Default status when a copy is created using the normal volume/copy creator interface.

Selection list

Defines the control number identifier used in 003 and 035 fields

Text

Delete bib if all copies are deleted via Acquisitions line item cancellation.

True/False

Delete volume with last copy

Automatically delete a volume when the last linked copy is deleted.

True/False

Default TRUE

Maximum Parallel Z39.50 Batch Searches

The maximum number of Z39.50 searches that can be in-flight at any given time when performing batch Z39.50 searches

Number

Maximum Z39.50 Batch Search Results

The maximum number of search results to retrieve and queue for each record + Z39 source during batch Z39.50 searches

Number

Spine and pocket label font family

Set the preferred font family for spine and pocket labels. You can specify a list of fonts, separated by commas, in order of preference; the system will use the first font it finds with a matching name. For example, "Arial, Helvetica, serif".

Text

Spine and pocket label font size

Set the default font size for spine and pocket labels

Number

Spine and pocket label font weight

Set the preferred font weight for spine and pocket labels. You can specify "normal", "bold", "bolder", or "lighter".

Text

Spine label left margin

Set the left margin for spine labels in number of characters.

Number

Spine label line width

Set the default line width for spine labels in number of characters. This specifies the boundary at which lines must be wrapped.

Number

Spine label maximum lines

Set the default maximum number of lines for spine labels.

Number

Table 71.3. Circulation

Setting
Description
Data type
Notes

Auto-extend grace periods

When enabled grace periods will auto-extend. By default this will be only when they are a full day or more and end on a closed date, though other options can alter this.

True/False

Auto-extending grace periods extend for all closed dates

It works when the above setting "Auto-Extend Grace Periods" is set to TRUE. If enabled, when the grace period falls on a closed date(s), it will be extended past all closed dates that intersect, but within the hard-coded limits (your library’s grace period).

True/False

Auto-extending grace periods include trailing closed dates

It works when the above setting "Auto-Extend Grace Periods" is set to TRUE. If enabled, grace periods will include closed dates that directly follow the last day of the grace period. A backdated check-in with effective date on the closed dates will assume the item is returned after hours on the last day of the grace period.

True/False

Useful when libraries' book drop equipped with AMH.

Block hold request if hold recipient privileges have expired

True/False

Cap max fine at item price

This prevents the system from charging more than the item price in overdue fines

True/False

Charge fines on overdue circulations when closed

When set to True, fines will be charged during scheduled closings and normal weekly closed days.

True/False

Checkout fills related hold

When a patron checks out an item and they have no holds that directly target the item, the system will attempt to find a hold for the patron that could be fulfilled by the checked out item and fulfills it. On the Staff Client you may notice that when a patron checks out an item under a title on which he/she has a hold, the hold will be treated as filled though the item has not been assigned to the patron’s hold.

True/false

Checkout fills related hold on valid copy only

When filling related holds on checkout only match on items that are valid for opportunistic capture for the hold. Without this set a Title or Volume hold could match when the item is not holdable. With this set only holdable items will match.

True/False

Checkout auto renew age

When an item has been checked out for at least this amount of time, an attempt to check out the item to the patron that it is already checked out to will simply renew the circulation. If the checkout attempt is done within this time frame, Evergreen will prompt for choosing Renewing or Check-in then Checkout the item.

Duration

Display copy alert for in-house-use

Setting to true for an organization will cause an alert to appear with the copy’s alert message, if it has one, when recording in-house-use for the copy.

True/False

Display copy location check in alert for in-house-use

Setting to true for an organization will cause an alert to display a message indicating that the item needs to be routed to its location if the location has check in alert set to true.

True/False

Do not change fines/fees on zero-balance LOST transaction

When an item has been marked lost and all fines/fees have been completely paid on the transaction, do not void or reinstate any fines/fees EVEN IF "Void lost item billing when returned" and/or "Void processing fee on lost item return" are enabled

True/False

Do not include outstanding Claims Returned circulations in lump sum tallies in Patron Display.

In the Patron Display interface, the number of total active circulations for a given patron is presented in the Summary sidebar and underneath the Items Out navigation button. This setting will prevent Claims Returned circulations from counting toward these tallies.

True/False

Hold shelf status delay

The purpose is to provide an interval of time after an item goes into the on-holds-shelf status before it appears to patrons that it is actually on the holds shelf. This gives staff time to process the item before it shows as ready-for-pick-up.

Duration

Include Lost circulations in lump sum tallies in Patron Display.

In the Patron Display interface, the number of total active circulations for a given patron is presented in the Summary sidebar and underneath the Items Out navigation button. This setting will include Lost circulations as counting toward these tallies.

True/False

Invalid patron address penalty

When set, if a patron address is set to invalid, a penalty is applied.

True/False

Item status for missing pieces

This is the Item Status to use for items that have been marked or scanned as having Missing Pieces. In the absence of this setting, the Damaged status is used.

Selection list

Load patron from Checkout

When scanning barcodes into Checkout auto-detect if a new patron barcode is scanned and auto-load the new patron.

True/False

Long-Overdue Check-In Interval Uses Last Activity Date

Use the long-overdue last-activity date instead of the due_date to determine whether the item has been checked out too long to perform long-overdue check-in processing. If set, the system will first check the last payment time, followed by the last billing time, followed by the due date. See also "Long-Overdue Max Return Interval"

True/False

Long-Overdue Items Usable on Checkin

Long-overdue items are usable on checkin instead of going "home" first

True/False

Long-Overdue Max Return Interval

Long-overdue check-in processing (voiding fees, re-instating overdues, etc.) will not take place for items that have been overdue for (or have last activity older than) this amount of time

Duration

Lost check-in generates new overdues

Enabling this setting causes retroactive creation of not-yet-existing overdue fines on lost item check-in, up to the point of check-in time (or max fines is reached). This is different than "restore overdue on lost", because it only creates new overdue fines. Use both settings together to get the full complement of overdue fines for a lost item

True/False

Lost items usable on checkin

Lost items are usable on checkin instead of going home first

True/false

Max patron claims returned count

When this count is exceeded, a staff override is required to mark the item as claims returned.

Number

Maximum visible age of User Trigger Events in Staff Interfaces

If this is unset, staff can view User Trigger Events regardless of age. When this is set to an interval, it represents the age of the oldest possible User Trigger Event that can be viewed.

Duration

Minimum transit checkin interval

In-Transit items checked in this close to the transit start time will be prevented from checking in

Duration

Patron merge address delete

Delete address(es) of subordinate user(s) in a patron merge.

True/False

Patron merge barcode delete

Delete barcode(s) of subordinate user(s) in a patron merge

True/False

Patron merge deactivate card

Mark barcode(s) of subordinate user(s) in a patron merge as inactive.

True/False

Patron Registration: Cloned patrons get address copy

If True, in the Patron editor, addresses are copied from the cloned user. If False, addresses are linked from the cloned user which can only be edited from the cloned user record.

True/False

Printing: custom JavaScript file

Full URL path to a JavaScript File to be loaded when printing. Should implement a print_custom function for DOM manipulation. Can change the value of the do_print variable to false to cancel printing.

Text

Require matching email address for password reset requests

True/False

Restore Overdues on Long-Overdue Item Return

True/False

Restore overdues on lost item return

If true when a lost item is checked in overdue fines are charged (up to the maximum fines amount)

True/False

Specify search depth for the duplicate patron check in the patron editor

When using the patron registration page, the duplicate patron check will use the configured depth to scope the search for duplicate patrons.

Number

Suppress hold transits group

To create a group of libraries to suppress Hold Transits among them. All libraries in the group should use the same unique value. Leave it empty if transits should not be suppressed.

Text

Suppress non-hold transits group

To create a group of libraries to suppress Non-Hold Transits among them. All libraries in the group should use the same unique value. Leave it empty if Non-Hold Transits should not be suppressed.

Text

Suppress popup-dialogs during check-in.

When set to True, no pop-up window for exceptions on check-in. But the accompanying sound will be played.

True/False

Target copies for a hold even if copy’s circ lib is closed

If this setting is true at a given org unit or one of its ancestors, the hold targeter will target copies from this org unit even if the org unit is closed (according to the Org Unit’s closed dates.).

True/False

Set the value to True if you want to target copies for holds at closed circulating libraries. Set the value to False, or leave it unset, if you do not want to enable this feature.

Target copies for a hold even if copy’s circ lib is closed IF the circ lib is the hold’s pickup lib

If this setting is true at a given org unit or one of its ancestors, the hold targeter will target copies from this org unit even if the org unit is closed (according to the Org Unit’s closed dates) IF AND ONLY IF the copy’s circ lib is the same as the hold’s pickup lib.

True/False

Set the value to True if you want to target copies for holds at closed circulating libraries when the circulating library of the item and the pickup library of the hold are the same. Set the value to False, or leave it unset, if you do not want to enable this feature.

Truncate fines to max fine amount

True/False

Default:TRUE

Use Lost and Paid copy status

Use Lost and Paid copy status when lost or long overdue billing is paid

True/False

Void Long-Overdue Item Billing When Returned

True/False

Void Processing Fee on Long-Overdue Item Return

True/False

Void longoverdue item billing when claims returned

True/False

Void longoverdue item processing fee when claims returned

True/False

Void lost item billing when claims returned

True/False

Void lost item billing when returned

If true,when a lost item is checked in the item replacement bill (item price) is voided.

True/False

Void lost item processing fee when claims returned

When an item is marked claims returned that was marked Lost, the item processing fee will be voided.

True/False

Void lost max interval

Items that have been overdue this long will not result in lost charges being voided when returned, and the overdue fines will not be restored, either. Only applies if Circ: Void lost item billing or Circ: Void processing fee on lost item are true.

Duration

Void processing fee on lost item return

Void processing fee when lost item returned

True/False

Warn when patron account is about to expire

If set, the staff client displays a warning this number of days before the expiry of a patron account. Value is in number of days.

Duration

Table 71.4. Credit Card Processing

Setting
Description
Data type
Notes

AuthorizeNet login

Authorize.Net Username

Text

Obtain from Authorize.Net at http://www.authorize.net

AuthorizeNet password

Authorize.Net Password

Text

Obtain from Authorize.Net

AuthorizeNet server

Required if using a developer/test account with Authorize.Net.

Text

Enter the server name from Authorize.Net. This is for use on test or developer account. If using live, leave blank.

AuthorizeNet test mode

Places Authorize.Net transactions in Test Mode

True/False

Enable AuthorizeNet payments

This actually enables use of Authorize.Net

True/False

Enable PayPal payments

This will enable use of PayPal payments through the staff client.

True/False

Enable PayflowPro payments

This will enable the use of PayPal’s Payflow Pro. This is not the same is PayPal.

True/False

Enable Stripe payments

This will enable the use of the stripe credit card processing.

True/False

https://stripe.com

Name default credit processor

This might be "AuthorizeNet", "PayPal", "PayflowPro", or "Stripe".

Text

This sets the company that you will use to process the credit cards.

PayPal login

Enter the PayPal login Username

Text

Obtain from PayPal

PayPal password

Enter the PayPal password.

Text

Obtain from PayPal.

PayPal signature

HASH Signature for PayPal

Text

Enter the HASH obtained from PayPal.

PayPal test mode

Places the PayPal credit card payments in test mode.

True/False

This sends the transactions to PayPal’s development.paypal.com server for testing only.

PayflowPro login/merchant ID

Enter the PayflowPro Merchant ID

Text

Obtain from Payflow Pro Partner.

PayflowPro partner

Enter the Partner ID from your Payflow Partner

Text

This will obtained from your Payflow Pro partner. This can be "PayPal" or "VeriSign", sometimes others.

PayflowPro password

Password for PayflowPro

Text

Obtain from Payflow Pro Partner

PayflowPro test mode

Place Payflow Pro in test mode.

True/False

Do not really process transactions, but stay in test mode - uses pilot-payflowpro.paypal.com instead of the usual host.

PayflowPro vendor

Currently the same as the Payflow Pro login.

Text

Obtain from Payflow Pro partner.

Stripe publishable key

Publishable API Key from stripe.

Text

Stripe secret key

Secret API key from stripe.

Text

Table 71.5. Finances

Setting
Description
Data type
Notes

Allow credit card payments

If enabled, patrons will be able to pay fines accrued at this location via credit card.

True/False

Charge item price when marked damaged

If true Evergreen bills item price to the last patron who checked out the damaged item. Staff receive an alert with patron information and must confirm the billing.

True/false

Charge lost on zero

If set to True, default item price will be charged when an item is marked lost even though the price in item record is 0.00 (same as no price). If False, only processing fee, if used, will be charged.

True/false

Charge processing fee for damaged items

Optional processing fee billed to last patron who checked out the damaged item. Staff receive an alert with patron information and must confirm the billing.

Number(Dollar)

Disabled when set to 0

Default item price

Replacement charge for lost items if price is unset in the Copy Editor. Does not apply if item price is set to $0

Number(dollars)

Disable Patron Credit

Do not allow patrons to accrue credit or pay fines/fees with accrued credit

True/False

Leave transaction open when long overdue balance equals zero

Leave transaction open when long-overdue balance equals zero. This leaves the lost copy on the patron record when it is paid

True/False

Leave transaction open when lost balance equals zero

Leave transaction open when lost balance equals zero. This leaves the lost copy on the patron record when it is paid

True/False

Long-Overdue Materials Processing Fee

The amount charged in addition to item price when an item is marked Long-Overdue

Number

Currency

Lost materials processing fee

The amount charged in addition to item price when an item is marked lost.

Number

Currency

Maximum Item Price

When charging for lost items, limit the charge to this as a maximum.

Number

Currency

Minimum Item Price

When charging for lost items, charge this amount as a minimum.

Number

Currency

Negative Balance Interval (DEFAULT)

Amount of time after which no negative balances (refunds) are allowed on circulation bills. The "Prohibit negative balance on bills" setting must also be set to "true".

Duration

Negative Balance Interval for Lost

Amount of time after which no negative balances (refunds) are allowed on bills for lost/long overdue materials. The "Prohibit negative balance on bills for lost materials" setting must also be set to "true".

Duration

Negative Balance Interval for Overdues

Amount of time after which no negative balances (refunds) are allowed on bills for overdue materials. The "Prohibit negative balance on bills for overdue materials" setting must also be set to "true".

Duration

Prohibit negative balance on bills (Default)

Default setting to prevent negative balances (refunds) on circulation related bills. Set to "true" to prohibit negative balances at all times or, when used in conjunction with an interval setting, to prohibit negative balances after a set period of time.

True/False

Prohibit negative balance on bills for lost materials

Prevent negative balances (refunds) on bills for lost/long overdue materials. Set to "true" to prohibit negative balances at all times or, when used in conjunction with an interval setting, to prohibit negative balances after an interval of time.

True/False

Prohibit negative balance on bills for overdue materials

Prevent negative balances (refunds) on bills for lost/long overdue materials. Set to "true" to prohibit negative balances at all times or, when used in conjunction with an interval setting, to prohibit negative balances after an interval of time.

True/False

Void Overdue Fines When Items are Marked Long-Overdue

If true overdue fines are voided when an item is marked Long-Overdue

True/False

Void overdue fines when items are marked lost

If true overdue fines are voided when an item is marked lost

True/False

Table 71.6. GUI: Graphic User Interface

Setting
Description
Data type
Notes

Alert on empty bib records

Alert staff when the last copy for a record is being deleted.

True/False

Button bar

If TRUE, the staff client button bar appears by default on all workstations registered to your library; staff can override this setting at each login.

True/False

Cap results in Patron Search at this number.

The maximum number of results returned per search. If 100 is set up here, any search will return 100 records at most.

Number

Default Country for New Addresses in Patron Editor

This is the default Country for new addresses in the patron editor.

Text

Default hotkeyset

Default Hotkeyset for clients (filename without the .keyset). Examples: Default, Minimal, and None

Text

Individual workstations' default overrides this setting.

Default ident type for patron registration

This is the default Ident Type for new users in the patron editor.

Selection list

Default showing suggested patron registration fields

Instead of All fields, show just suggested fields in patron registration by default.

True/False

Disable the ability to save list column configurations locally.

GUI: Disable the ability to save list column configurations locally. If set, columns may still be manipulated, however, the changes do not persist. Also, existing local configurations are ignored if this setting is true.

True/False

Example for Day_phone field on patron registration

The example on validation on the Day_phone field in patron registration.

Text

Example for Email field on patron registration

The example on validation on the Email field in patron registration.

Text

Example for Evening-phone on patron registration

The example on validation on the Evening-phone field in patron registration.

Text

Example for Other-phone on patron registration

The example on validation on the Other-phone field in patron registration.

Text

Example for phone fields on patron registration

The example on validation on phone fields in patron registration. Applies to all phone fields without their own setting.

Text

Example for Postal Code field on patron registration

The example on validation on the Postal Code field in patron registration.

Text

Format Dates with this pattern.

Format Dates with this pattern (examples: "yyyy-MM-dd" for "2010-04-26, "MMM d, yyyy" for "Apr 26, 2010"). Formats are effective in display (not editing) area.

Text

Format Times with this pattern.

Format Times with this pattern (examples: "h:m:s.SSS a z" for "2:07:20.666 PM Eastern Daylight Time", "HH:mm" for "14:07"). Formats are effective in display (not editing) area.

Text

GUI: Hide these fields within the Item Attribute Editor.

Sets which fields in the Item Attribute Editor to hide in the staff client.

Text

This is useful to hide attributes that are not used.

Horizontal layout for Volume/Copy Creator/Editor.

The main entry point for this interface is in Holdings Maintenance, Actions for Selected Rows, Edit Item Attributes / Call Numbers / Replace Barcodes. This setting changes the top and bottom panes (if FALSE) for that interface into left and right panes (if TRUE).

True/False

Idle timeout

If you want staff client windows to be minimized after a certain amount of system idle time, set this to the number of seconds of idle time that you want to allow before minimizing (requires staff client restart).

Number

Items Out Claims Returned display setting

Value is a numeric code, describing which list the circulation should appear while checked out and whether the circulation should continue to appear in the bottom list, when checked in with outstanding fines. 1 = top list, bottom list. 2 = bottom list, bottom list. 5 = top list, do not display. 6 = bottom list, do not display.

Number

Items Out Long-Overdue display setting

Value is a numeric code, describing which list the circulation should appear while checked out and whether the circulation should continue to appear in the bottom list, when checked in with outstanding fines. 1 = top list, bottom list. 2 = bottom list, bottom list. 5 = top list, do not display. 6 = bottom list, do not display.

Number

Items Out Lost display setting

Value is a numeric code, describing which list the circulation should appear while checked out and whether the circulation should continue to appear in the bottom list, when checked in with outstanding fines. 1 = top list, bottom list. 2 = bottom list, bottom list. 5 = top list, do not display. 6 = bottom list, do not display.

Number

Max user activity entries to retrieve (staff client)

Sets the maximum number of recent user activity entries to retrieve for display in the staff client.

Number

Maximum previous checkouts displayed

The maximum number of previous circulations the staff client will display when investigating item details

Number

Patron circulation summary is horizontal

True/False

Record in-house use: # of uses threshold for Are You Sure? dialog.

In the Record In-House Use interface, a submission attempt will warn if the # of uses field exceeds the value of this setting.

Number

Record In-House Use: Maximum # of uses allowed per entry.

The # of uses entry in the Record In-House Use interface may not exceed the value of this setting.

Number

Regex for barcodes on patron registration

The Regular Expression for validation on barcodes in patron registration.

Regular Expression

Regex for Day_phone field on patron registration

Regular expression

Regex for Email field on patron registration

The Regular Expression on validation on the Email field in patron registration.

Regular expression

Regex for Evening-phone on patron registration

The Regular Expression on validation on the Evening-phone field in patron registration.

Regular expression

Regex for Other-phone on patron registration

The Regular Expression on validation on the Other-phone field in patron registration.

Regular expression

Regex for phone fields on patron registration

The Regular Expression on validation on phone fields in patron registration. Applies to all phone fields without their own setting.

Regular expression

^(?:(?:\+?1\s*(?:[.-]\s*)?)?(?:\(\s*([2-9]1[02-9]|[2-9][02-8]1|[2-9][02-8][02-9])\s*\)|([2-9]1[02-9]|[2-9][02-8]1|[2-9][02-8][02-9]))\s*(?:[.-]\s*)?)?([2-9]1[02-9]|[2-9][02-9]1|[2-9][02-9]{2})\s*(?:[.-]\s*)?([0-9]{4})(?:\s*(?:#|x\.?|ext\.?|extension)\s*(\d+))?$ is a US phone number

Regex for Postal Code field on patron registration

The Regular Expression on validation on the Postal Code field in patron registration.

Regular expression

Require at least one address for Patron Registration

Enforces a requirement for having at least one address for a patron during registration. If set to False, you need to delete the empty address before saving the record. If set to True, deletion is not allowed.

True/False

Require XXXXX field on patron registration

The XXXXX field will be required on the patron registration screen.

True/False

XXXXX can be Country, State, Day-phone, Evening-phone, Other-phone, DOB, Email, or Prefix.

Require staff initials for entry/edit of patron standing penalties and messages.

Appends staff initials and edit date into patron standing penalties and messages.

True/False

Require staff initials for entry/edit of patron notes.

Appends staff initials and edit date into patron note content.

True/False

Require staff initials for entry/edit of copy notes.

Appends staff initials and edit date into copy note content.

True/False

Show billing tab first when bills are present

If true accounts for patrons with bills will open to the billing tab instead of check out

True/false

Show XXXXX field on patron registration

The XXXXX field will be shown on the patron registration screen. Showing a field makes it appear with required fields even when not required. If the field is required this setting is ignored.

True/False

Suggest XXXXX field on patron registration

The XXXXX field will be suggested on the patron registration screen. Suggesting a field makes it appear when suggested fields are shown. If the field is shown or required this setting is ignored.

True/False

Toggle off the patron summary sidebar after first view.

When true, the patron summary sidebar will collapse after a new patron sub-interface is selected.

True/False

URL for remote directory containing list column settings.

The format and naming convention for the files found in this directory match those in the local settings directory for a given workstation. An administrator could create the desired settings locally and then copy all the tree_columns_for_* files to the remote directory.

Text

Uncheck bills by default in the patron billing interface

Uncheck bills by default in the patron billing interface, and focus on the Uncheck All button instead of the Payment Received field.

True/False

Unified Volume/Item Creator/Editor

If True, combines the Volume/Copy Creator and Item Attribute Editor in some instances.

True/False

Work Log: maximum actions logged

Maximum entries for "Most Recent Staff Actions" section of the Work Log interface.

Number

Work Log: maximum patrons logged

Maximum entries for "Most Recently Affected Patrons…" section of the Work Log interface.

Number

Table 71.7. Global

Setting
Description
Data type
Notes

Allow multiple username changes

If enabled (and Lock Usernames is not set) patrons will be allowed to change their username when it does not look like a barcode. Otherwise username changing in the OPAC will only be allowed when the patron’s username looks like a barcode.

True/False

Default TRUE.

Global default locale

Number

Lock Usernames

If enabled username changing via the OPAC will be disabled.

Default FALSE

Password format

Defines acceptable format for OPAC account passwords

Regular expression

Default requires that passwords "be at least 7 characters in length,contain at least one letter (a-z/A-Z), and contain at least one number.

Patron barcode format

Defines acceptable format for patron barcodes

Regular expression

Patron username format

Regular expression defining the patron username format, used for patron registration and self-service username changing only

Regular expression

Table 71.8. Holds

Setting
Description
Data type
Notes

Behind desk pickup supported

If a branch supports both a public holds shelf and behind-the-desk pickups, set this value to true. This gives the patron the option to enable behind-the-desk pickups for their holds by selecting Hold is behind Circ Desk flag in patron record.

True/False

Best-hold selection sort order

Defines the sort order of holds when selecting a hold to fill using a given copy at capture time

Selection list

Block renewal of items needed for holds

When an item could fulfill a hold, do not allow the current patron to renew

True/False

Cancelled holds display age

Show all cancelled holds that were cancelled within this amount of time

Duration

Cancelled holds display count

How many cancelled holds to show in patron holds interfaces

Number

Clear shelf copy status

Any copies that have not been put into reshelving, in-transit, or on-holds-shelf (for a new hold) during the clear shelf process will be put into this status. This is basically a purgatory status for copies waiting to be pulled from the shelf and processed by hand

Selection list

Default estimated wait

When predicting the amount of time a patron will be waiting for a hold to be fulfilled, this is the default estimated length of time to assume an item will be checked out.

Duration

Default hold shelf expire interval

Hold Shelf Expiry Time is calculated and inserted into hold record based on this interval when capturing a hold.

Duration

Expire alert interval

Time before a hold expires at which to send an email notifying the patron

Duration

Expire interval

Amount of time until an unfulfilled hold expires

Duration

FIFO

Force holds to a more strict First-In, First-Out capture. Default is SAVE-GAS, which gives priority to holds with pickup location the same as checkin library.

True/False

Applies only to multi-branch libraries. Default is SAVE-GAS.

Hard boundary

Number

Hard stalling interval

Duration

Has local copy alert

If there is an available copy at the requesting library that could fulfill a hold during hold placement time, alert the patron.

True/False

Has local copy block

If there is an available copy at the requesting library that could fulfill a hold during hold placement time, do not allow the hold to be placed.

True/False

Max foreign-circulation time

Time a copy can spend circulating away from its circ lib before returning there to fill a hold

Duration

For multi-branch libraries.

Maximum library target attempts

When this value is set and greater than 0, the system will only attempt to find a copy at each possible branch the configured number of times

Number

For multi-branch libraries.

Minimum estimated wait

When predicting the amount of time a patron will be waiting for a hold to be fulfilled, this is the minimum estimated length of time to assume an item will be checked out.

Duration

Org unit target weight

Org Units can be organized into hold target groups based on a weight. Potential copies from org units with the same weight are chosen at random.

Number

Reset request time on un-cancel

When a hold is uncancelled, reset the request time to push it to the end of the queue

True/False

Skip for hold targeting

When true, don’t target any copies at this org unit for holds

True/False

Soft boundary

Holds will not be filled by copies outside this boundary if there are holdable copies within it.

Number

Soft stalling interval

For this amount of time, holds will not be opportunistically captured at non-pickup branches.

Duration

For multiple branch libraries

Use Active Date for age protection

When calculating age protection rules use the Active date instead of the Creation Date.

True/False

Default TRUE

Use weight-based hold targeting

Use library weight based hold targeting

True/False

Table 71.9. Library

Setting
Description
Data type
Notes

Change reshelving status interval

Amount of time to wait before changing an item from “Reshelving” status to “available”

Duration

The default is at midnight each night for items with "Reshelving" status for over 24 hours.

Claim never checked out: mark copy as missing

When a circ is marked as claims-never-checked-out, mark the copy as missing

True/False

Claim return copy status

Claims returned copies are put into this status. Default is to leave the copy in the Checked Out status

Selection list

Courier code

Courier Code for the library. Available in transit slip templates as the %courier_code% macro.

Text

Juvenile age threshold

Upper cut-off age for patrons to be considered juvenile, calculated from date of birth in patron accounts

Duration (years)

Library information URL (such as "http://example.com/about.html")

URL for information on this library, such as contact information, hours of operation, and directions. Use a complete URL, such as "http://example.com/hours.html".

Text

Mark item damaged voids overdues

When an item is marked damaged, overdue fines on the most recent circulation are voided.

True/False

Pre-cat item circ lib

Override the default circ lib of "here" with a pre-configured circ lib for pre-cat items. The value should be the "shortname" (aka policy name) of the org unit

Text

Telephony: Arbitrary line(s) to include in each notice callfile

This overrides lines from opensrf.xml. Line(s) must be valid for your target server and platform (e.g. Asterisk 1.4).

Text

Table 71.10. OPAC

Setting
Description
Data type
Notes

Allow Patron Self-Registration

Allow patrons to self-register, creating pending user accounts

True/False

Allow pending addresses

If true patrons can edit their addresses in the OPAC. Changes must be approved by staff

True/False

Auto-Override Permitted Hold Blocks (Patrons)

This will allow patrons with the permission "HOLD_ITEM_CHECKED_OUT.override" to automatically override permitted holds.

True/False

When a patron places a hold in the OPAC that fails, and the patron has the permission to override the failed hold, this automatically overrides the failed hold rather than requiring the patron to manually override the hold. Default is False.

Jump to details on 1 hit (OPAC)

When a search yields only 1 result, jump directly to the record details page. This setting only affects the public OPAC

True/False

Jump to details on 1 hit (staff client)

When a search yields only 1 result, jump directly to the record details page. This setting only affects the PAC within the staff client

True/False

OPAC: Number of staff client saved searches to display on left side of results and record details pages

If unset, the OPAC (only when wrapped in the staff client!) will default to showing you your ten most recent searches on the left side of the results and record details pages. If you actually don’t want to see this feature at all, set this value to zero at the top of your organizational tree.

Number

OPAC: Org Unit is not a hold pickup library

If set, this org unit will not be offered to the patron as an option for a hold pickup location. This setting has no affect on searching or hold targeting.

True/False

Org unit hiding depth

This will hide certain org units in the public OPAC if the Original Location (url param "ol") for the OPAC inherits this setting. This setting specifies an org unit depth, that together with the OPAC Original Location determines which section of the Org Hierarchy should be visible in the OPAC. For example, a stock Evergreen installation will have a 3-tier hierarchy (Consortium/System/Branch), where System has a depth of 1 and Branch has a depth of 2. If this setting contains a depth of 1 in such an installation, then every library in the System in which the Original Location belongs will be visible, and everything else will be hidden. A depth of 0 will effectively make every org visible. The embedded OPAC in the staff client ignores this setting.

Number

Paging shortcut links for OPAC Browse

The characters in this string, in order, will be used as shortcut links for quick paging in the OPAC browse interface. Any sequence surrounded by asterisks will be taken as a whole label, not split into individual labels at the character level, but only the first character will serve as the basis of the search.

Text

Patron Self-Reg. Display Timeout

Number of seconds to wait before reloading the patron self-registration interface to clear sensitive data

Duration

Patron Self-Reg. Expire Interval

If set, this is the amount of time a pending user account will be allowed to sit in the database. After this time, the pending user information will be purged

Duration

Payment history age limit

The OPAC should not display payments by patrons that are older than any interval defined here.

Duration

Tag Circulated Items in Results

When a user is both logged in and has opted in to circulation history tracking, turning on this setting will cause previous (or currently) circulated items to be highlighted in search results

True/False

Tag Circulated Items in Results

When a user is both logged in and has opted in to circulation history tracking, turning on this setting will cause previous (or currently) circulated items to be highlighted in search results.

True/False

Default TRUE

Use fully compressed serial holdings

Show fully compressed serial holdings for all libraries at and below the current context unit

True/False

Warn patrons when adding to a temporary book list

Present a warning dialogue when a patron adds a book to the temporary book list.

True/False

Table 71.11. Offline and Program

Setting
Description
Data type
Notes

Skip offline checkin if newer item Status Changed Time.

Skip offline checkin transaction (raise exception when processing) if item Status Changed Time is newer than the recorded transaction time. WARNING: The Reshelving to Available status rollover will trigger this.

True/False

Skip offline checkout if newer item Status Changed Time.

Skip offline checkout transaction (raise exception when processing) if item Status Changed Time is newer than the recorded transaction time. WARNING: The Reshelving to Available status rollover will trigger this.

True/False

Skip offline renewal if newer item Status Changed Time.

Skip offline renewal transaction (raise exception when processing) if item Status Changed Time is newer than the recorded transaction time. WARNING: The Reshelving to Available status rollover will trigger this.

True/False

Disable automatic print attempt type list

Disable automatic print attempts from staff client interfaces for the receipt types in this list. Possible values: "Checkout", "Bill Pay", "Hold Slip", "Transit Slip", and "Hold/Transit Slip". This is different from the Auto-Print checkbox in the pertinent interfaces in that it disables automatic print attempts altogether, rather than encouraging silent printing by suppressing the print dialogue. The Auto-Print checkbox in these interfaces have no effect on the behavior for this setting. In the case of the Hold, Transit, and Hold/Transit slips, this also suppresses the alert dialogues that precede the print dialogue (the ones that offer Print and Do Not Print as options).

Text

Retain empty bib records

Retain a bib record even when all attached copies are deleted

True/False

Sending email address for patron notices

This email address is for automatically generated patron notices (e.g. email overdues, email holds notification). It is good practice to set up a generic account, like info@nameofyourlibrary.org, so that one person’s individual email inbox doesn’t get cluttered with emails that were not delivered.

Text

Table 71.12. Receipt Templates and SMS Text Message

Setting
Description
Data type
Notes

Content of alert_text include

Text/HTML/Macros to be inserted into receipt templates in place of %INCLUDE(alert_text)%

Text

Content of event_text include

Text/HTML/Macros to be inserted into receipt templates in place of %INCLUDE(event_text)%

Text

Content of footer_text include

Text/HTML/Macros to be inserted into receipt templates in place of %INCLUDE(footer_text)%

Text

Content of header_text include

Text/HTML/Macros to be inserted into receipt templates in place of %INCLUDE(header_text)%

Text

Content of notice_text include

Text/HTML/Macros to be inserted into receipt templates in place of %INCLUDE(notice_text)%

Text

Disable auth requirement for texting call numbers.

Disable authentication requirement for sending call number information via SMS from the OPAC.

True/False

Enable features that send SMS text messages.

Current features that use SMS include hold-ready-for-pickup notifications and a "Send Text" action for call numbers in the OPAC. If this setting is not enabled, the SMS options will not be offered to the user. Unless you are carefully silo-ing patrons and their use of the OPAC, the context org for this setting should be the top org in the org hierarchy, otherwise patrons can trample their user settings when jumping between orgs.

True/False

Table 71.13. Security

Setting
Description
Data type
Notes

Default level of patrons' internet access

Enter numbers 1 (Filtered), 2 (Unfiltered), or 3 (No Access)

Number

Maximum concurrently active self-serve password reset requests

Prevent the creation of new self-serve password reset requests until the number of active requests drops back below this number.

Number

Maximum concurrently active self-serve password reset requests per user

When a user has more than this number of concurrently active self-serve password reset requests for their account, prevent the user from creating any new self-serve password reset requests until the number of active requests for the user drops back below this number.

Number

OPAC Inactivity Timeout (in seconds)

Number of seconds of inactivity before OPAC accounts are automatically logged out.

Number

Obscure the Date of Birth field

When true, the Date of Birth column in patron lists will default to Not Visible, and in the Patron Summary sidebar the value will display as unless the field label is clicked.

True/False

Offline: Patron usernames allowed

During offline circulations, allow patrons to identify themselves with usernames in addition to barcode. For this setting to work, a barcode format must also be defined

True/False

Patron opt-in boundary

This determines at which depth above which patrons must be opted in, and below which patrons will be assumed to be opted in.

Text

Patron opt-in default

This is the default depth at which a patron is opted in; it is calculated as an org unit relative to the current workstation.

Text

Patron: password from phone #

If true the last 4 digits of the patron’s phone number is the password for new accounts (password must still be changed at first OPAC login)

True/false

Persistent login duration

How long a persistent login lasts, e.g. 2 weeks

Duration

Self-serve password reset request time-to-live

Length of time (in seconds) a self-serve password reset request should remain active.

Duration

Staff login inactivity timeout (in seconds)

Number of seconds of inactivity before staff client prompts for login and password.

Number

Table 71.14. Self Check and Others

Setting
Description
Data type
Notes

Audio Alerts

Use audio alerts for selfcheck events.

True/false

Block copy checkout status

List of copy status IDs that will block checkout even if the generic COPY_NOT_AVAILABLE event is overridden.

Number

Look up copy status ID from Server Admin.

Patron login timeout (in seconds)

Number of seconds of inactivity before the patron is logged out of the selfcheck interface.

Duration

Pop-up alert for errors

If true, checkout/renewal errors will cause a pop-up window in addition to the on-screen message.

True/False

Require Patron Password

If true, patrons will be required to enter their password in addition to their username/barcode to log into the selfcheck interface.

True/False

This replaced "Require patron password"

Require patron password

True/False

This was replaced by "Require Patron Password" and is currently invalid.

Selfcheck override events list

List of checkout/renewal events that the selfcheck interface should automatically override instead instead of alerting and stopping the transaction.

Text

Workstation Required

All selfcheck stations must use a workstation.

True/False

Default display grouping for serials distributions presented in the OPAC.

Default display grouping for serials distributions presented in the OPAC. This can be "enum" or "chron".

Text

Previous issuance copy location

When a serial issuance is received, copies (units) of the previous issuance will be automatically moved into the configured shelving location.

Selection List

Maximum redirect lookups

For URLs returning 3XX redirects, this is the maximum number of redirects we will follow before giving up.

Number

Maximum wait time (in seconds) for a URL to lookup

If we exceed the wait time, the URL is marked as a "timeout" and the system moves on to the next URL

Duration

Number of URLs to test in parallel

URLs are tested in batches. This number defines the size of each batch and it directly relates to the number of back-end processes performing URL verification.

Number

Number of seconds to wait between URL test attempts

Throttling mechanism for batch URL verification runs. Each running process will wait this number of seconds after a URL test before performing the next.

Duration

Table 71.15. Vandelay

Setting
Description
Data type
Notes

Default Record Match Set

Sets the Default Record Match set

Selection List

Populated by the Vandelay Record Match Sets

Vandelay Default Barcode Prefix

Apply this prefix to any auto-generated item barcode

Text

Vandelay Default Call Number Prefix

Apply this prefix to any auto-generated item call numbers.

Text

Vandelay Default Circulation Modifier

Default circulation modifier value for imported items

Selection List

Populated by your Circulation Modifiers.

Vandelay Default Copy Location

Default copy location value for imported items

Selection List

Populated from Shelving Locations

Vandelay Generate Default Barcodes

Auto-generate default item barcodes when no item barcode is present

True/False

Vandelay Generate Default Call Numbers

Auto-generate default item call numbers when no item call number is present

True/False

These are pulled from the MARC Record.

71.3.1. Data Types

Acceptable formats for each setting type are listed below. Quotation marks are never required when updating settings in the staff client.

Table 71.16. Data Types in the Library Settings Editor

Data type
Formatting

True/False

Boolean True/False drop down

Number

Enter a numerical value (decimals allowed in price settings)

Duration

Enter a number followed by a space and any of the following units: minutes, hours, days, months (30 minutes, 2 days, etc)

Selection list

Choose from a drop-down list of options (e.g. copy status, copy location)

Text

Free text

Chapter 72. Address Alert

The Address Alert module gives administrators the ability to notify staff with a custom message when addresses with certain patterns are entered in patron records.

This feature only serves to provide pertinent information to your library system’s circulation staff during the registration process. An alert will not prevent the new patron account from being registered and the information will not be permanently associated with the patron account.

To access the Address Alert module, select Admin → Local Administration → Address Alerts.

You must have Local Administrator permissions or ADMIN_ADDRESS_ALERT permission to access the Address Alert module.

72.1. General Usage Examples

Alert staff when an address for a large apartment is entered to prompt them to ask for unit number.

Alert staff when the address of a hotel or other temporary housing is entered.

Alert staff when an address for a different country is entered.

Alert staff when a specific city or zip code is entered if that city or zip code needs to be handled in a special way. If you have a neighboring city that you don’t have a reciprocal relationship with, you could notify staff that a fee card is required for this customer.

72.2. Access Control and Scoping

Each address alert is tied to an Org Unit and will only be matched against staff client instances of that Org Unit and its children.

When viewing the address alerts you will only see the alerts associated with the specific org unit selected in the "Context Org Unit" selection box. You won’t see alerts associated with parent org units, so the list of alerts isn’t a list of all alerts that may effect your org unit, only of the ones that you can edit.

The specific permission that controls access to configuring this feature is ADMIN_ADDRESS_ALERT. Local Administrator level users will already have this permission. It is possible for the Local Administrator to grant this permission to other staff.

72.3. Adding a new Address Alert

How to add an address to the alert list:

Log into the Evergreen Staff Client using a Local Administrator account or another account that has been granted the proper permission.

Click on Admin → Local Administration → Address Alerts.

Click "New Address Alert."

A form will open with the following fields to fill out:

Table 72.1. New Address Alert Fields

Field

Description

Owner

Which Org Unit owns this alert. Set this to your system or branch.

Active

Check-box that controls if the alert is active or not. Inactive alerts are not processed.

Match All Fields

Check-box that controls if all the fields need to match to trigger the alert(checked), or only at least one field needs to match(unchecked).

Alert Message

Message that will be displayed to staff when this alert is triggered.

Street (1)

Street 1 field regular expression.

Street (2)

Street 2 field regular expression.

City

City regular expression.

County

County regular expression.

State

State regular expression.

Country

County regular expression.

Postal Code

Postal Code regular expression.

Address Alert ID

Displays the internal database id for alert after the alert has been saved.

Billing Address

Check-box that specifies that the alert will only match a billing address if checked.

Mailing Address

Check-box that specifies that the alert will only match a mailing address if checked.

Click save once you have finished.

72.4. Editing an Address Alert

To make changes to an existing alert, double click on the alert in the list. The editing form will appear, make your changes and click save or cancel when you are done.

If you don’t see your alerts, make sure the "Context Org Unit" selection box has the correct Org Unit selected.

72.5. Deleting an Address Alert

To delete an alert or many alerts, click the selection check-box for all alerts you would like to delete. Then click the "Delete Selected" button at the top of the screen.

72.6. Staff View of Address Alerts

When an Address Alert is triggered by a matching address the staff will see the address block highlighted with a red dashed line, along with an "Address Alert" block which contains the alert message.

Here is an example of what staff would see.

72.7. Regular Expressions / Wildcards

All of the patterns entered to match the various address fields are evaluated as case-insensitive regular expressions by default.

Address Alerts use POSIX Regular Expressions included in the PostgreSQL database engine. See the PostgreSQL documentation for full details.

If you want to do a case-sensitive match you need to prepend the pattern with "(?c)"

The simplest regular expression that acts as a wildcard is ".*", that matches any type of character zero or more times.

72.8. Examples

Apartment address. Match an apartment address to prompt for unit number.

Choose Owner Org Unit.

Active = Checked

Match All Fields = Checked

Alert Message = "This is a large apartment building, Please ask customer for unit number."

Street (1) = "1212 Evergreen Lane.*"

City = "mytown"

All addresses on street. Match all addresses on a certain street. Matches ave and avenue because of ending wildcard.

Choose Owner Org Unit.

Active = Checked

Match All Fields = Checked

Alert Message = "This street is in a different county, please setup reciprocal card."

Street (1) = ".* Evergreen Ave.*"

City = "mytown"

Match list of cities. Match several different cities with one alert. Could be used if certain cities don’t have reciprocal agreements. Note the use of parentheses and the | character to separate the different options.

Choose Owner Org Unit.

Active = Checked

Match All Fields = Checked

Alert Message = "Customer must purchase a Fee card."

City = "(Emeryville|San Jose|San Francisco)"

72.9. Development

Links to resources with more information on how and why this feature was developed and where the various source files are located.

Launchpad ticket for the feature request and development of address alerts - https://bugs.launchpad.net/evergreen/+bug/898248

Chapter 73. Barcode Completion

The Barcode Completion feature gives users the ability to only enter the unique part of patron and item barcodes. This can significantly reduce the amount of typing required for manual barcode input. This feature was also known as Lazy Circ at one point.

This feature can also be used if there is a difference between what the barcode scanner outputs and what is stored in the database, as long as the barcode that is stored has more characters then what the scanner is outputting. Barcode Completion is additive only, you cannot use it match a stored barcode that has less characters than what is entered. For example, if your barcode scanners previously output a123123b and now exclude the prefix and suffix, you could match both formats using Barcode Completion rules.

Because this feature adds an extra database search for each enabled rule to the process of looking up a barcode, it can add extra delays to the check-out process. Please test in your environment before using in production.

Released: 2.2 - June 2012

73.1. Scoping and Permissions

Local Administrator permission is needed to access the admin interface of the Barcode Completion feature.

Each rule requires an owner org unit, which is how scoping of the rules is handled. Rules are applied for staff users with the same org unit or descendants of that org unit.

73.2. Access Points

The admin interface for Barcode Completion is located under Admin → Local Administration → Barcode Completion.

The barcode completion functionality is available at the following interfaces.

For Actors (Users) Barcodes

Lookup Patron by Barcode/Check Out.

Optionally during check out if library setting "Load patron from Checkout" is set. (Automatically detects if an actor/user barcode is scanned during check out, and starts a new check out session using that user.)

OPAC’s Staff Client Place Hold.

For Assets (Copy) Barcodes

Check Out.

Check In.

Item Status / Search for copies by Barcode / Show Item Status by Barcode.

Barcode Completion does not work in the Search for Patron [by Name] interface.

73.3. Multiple Matches

If multiple barcodes are matched, say if you have both "123" and "00000123" as valid barcodes, you will receive a list of all the barcodes that match all the rules that you have configured. It doesn’t stop after the first rule that matches, or after the first valid barcode is found.

73.4. Barcode Completion Data Fields

The following data fields can be set for each Barcode Completion rule.

Table 73.1. Barcode Completion Fields

Active

Check to indicate entry is active. Required

Owner

Setting applies to this Org Unit and to all children. Required

Prefix

Sequence that appears at the beginning of barcode.

Suffix

Sequence that appears at the end of barcode.

Length

Total length of barcode.

Padding

Character that pads out non-unique characters in the barcode.

Padding At End

Check if the padding starts at the end of the barcode.

Applies to Items

Check if entry applies to item barcodes.

Applies to Users

Check if entry applies to user barcodes.

Length and Padding. Length and Padding are related, you cannot use one without the other. If a barcode has to be a certain length, then it needs to be able to be padded out to that length. If a barcode has padding, then we need to know the max length that we need to pad out to. If length is set to blank or zero, or padding is left blank then they are both ignored.

Applies to Items/Users. One or both of these options must be checked for the rule to have any effect.

73.5. Create, Update, Filter, Delete/Disable Rules

In the Barcode Completion admin interface at Admin → Local Administration → Barcode Completion you can create, update and disable rules.

73.5.1. Create Rules

To create a new rule click on the New button in the upper right corner. When you are are done with editing the new rule click the Save button. If you want to cancel the new rule creation click the Cancel button.

73.5.2. Update Rules

To edit a rule double click on the rule in the main list.

73.5.3. Filter Rules

It may be useful to filter the rules list if there are a large number of rules. Click on the filter link to bring up the Filter Results dialog box. You can filter on any of the data fields and you can setup multiple filter rules. Click Apply to enable the filter rules, only the rows that match will now be displayed.

To clear out the filter rules, delete all of the filter rules by clicking the X next to each rule, and then click Apply.

73.5.4. Delete/Disable Rules

It isn’t possible to delete a rule from the database from the admin interface. If a rule is no longer needed set Active to "False" to disable it. To keep the number of rules down, reuse inactive rules when creating new rules.

73.6. Examples

In all these examples, the unique part of the barcode is 123. So that is all that users will need to type to match the full barcode.

73.6.1. Barcode With Prefix and Padding

Barcode: 4545000123

To match this 10 character barcode by only typing in 123 we need the following settings.

Active - Checked

Owner - Set to your org unit.

Prefix - 4545 - This is the prefix that the barcode starts with.

Length - 10 - Total length of the barcode.

Padding - 0 - Zeros will be used to pad out non significant parts of the barcode.

Applies to Items and/or Applies to Users - Checked

The system takes the 123 that you entered and adds the prefix to the beginning of it. Then adds zeros between the prefix and your number to pad it out to 10 characters. Then it searches the database for that barcode.

73.6.2. Barcode With Suffix

Barcode: 123000book

To match this 10 character barcode by only typing in 123 we need the following settings.

Active - Checked

Owner - Set to your org unit.

Suffix - book - This is the suffix that the barcode ends with.

Length - 10 - Total length of the barcode.

Padding - 0 - Zeros will be used to pad out non significant parts of the barcode.

Padding at End - Checked

Applies to Items and/or Applies to Users - Checked

The system takes the 123 that you entered and adds the suffix to the end of it. Then adds zeros between your number and the suffix to pad it out to 10 characters. Then it searches the database for that barcode.

73.6.3. Barcode With Left Padding

Barcode: 0000000123

To match this 10 character barcode by only typing in 123 we need the following settings.

Active - Checked

Owner - Set to your org unit.

Length - 10 - Total length of the barcode.

Padding - 0 - Zeros will be used to pad out non significant parts of the barcode.

Applies to Items and/or Applies to Users - Checked

The system takes the 123 that you entered, then adds zeros between your number and the left to pad it out to 10 characters. Then it searches the database for that barcode.

73.6.4. Barcode With Right Padding

Barcode: 1230000000

To match this 10 character barcode by only typing in 123 we need the following settings.

Active - Checked

Owner - Set to your org unit.

Length - 10 - Total length of the barcode.

Padding - 0 - Zeros will be used to pad out non significant parts of the barcode.

Padding at End - Checked

Applies to Items and/or Applies to Users - Checked

The system takes the 123 that you entered, then adds zeros between your number and the right to pad it out to 10 characters. Then it searches the database for that barcode.

73.6.5. Barcode of any Length with Prefix and Suffix

Barcode: a123b

To match this 5 character barcode by only typing in 123 we need the following settings. This use of Barcode Completion doesn’t save many keystrokes, but it does allow you to handle the case where your barcode scanners at one point were set to output a prefix and suffix which was stored in the database. Now your barcode scanners no longer include the prefix and suffix. These settings will simply add the prefix and suffix to any barcode entered and search for that.

Active - Checked

Owner - Set to your org unit.

Length/Padding - 0/null - Set the length to 0 and/or leave the padding blank.

Prefix - a - This is the prefix that the barcode starts with.

Suffix - b - This is the suffix that the barcode starts with.

Applies to Items and/or Applies to Users - Checked

The system takes the 123 that you entered, then adds the prefix and suffix specified. Then it searches the database for that barcode. Because no length or padding was entered, this rule will add the prefix and suffix to any barcode that is entered and then search for that valid barcode.

73.7. Testing

To test this feature, setup the rules that you want, then setup items/users with barcodes that should match. Then try scanning the short version of those barcodes in the various supported access points.

Chapter 74. Hold-driven recalls

Added in Evergreen 2.1

In academic libraries, it is common for groups like faculty and graduate students to have extended loan periods (for example, 120 days), while others have more common loan periods such as 3 weeks. In these environments, it is desirable to have a hold placed on an item that has been loaned out for an extended period to trigger a recall, which:

Truncates the loan period

Sets the remaining available renewals to 0

Optionally: Changes the fines associated with overdues for the new due date

Optionally: Notifies the current patron of the recall, including the new due date and fine level

74.1. Enabling hold-driven recalls

By default, holds do not trigger recalls. To enable hold-driven recalls of circulating items, library settings must be changed as follows:

Click Admin → Local Administration → Library Settings Editor.

Set the Recalls: Circulation duration that triggers a recall (recall threshold) setting. The recall threshold is specified as an interval (for example, "21 days"); any items with a loan duration of less that this interval are not considered for a recall.

Set the Recalls: Truncated loan period (return interval) setting. The return interval is specified as an interval (for example, "7 days"). The due date on the recalled item is changed to be the greater of either the recall threshold or the return interval.

Optionally: Set the Recalls: An array of fine amount, fine interval, and maximum fine setting. If set, this applies the specified fine rules to the current circulation period for the recalled item.

When a hold is placed and no available copies are found by the hold targeter, the recall logic checks to see if the recall threshold and return interval settings are set; if so, then the hold targeter checks the currently checked-out copies to determine if any of the currently circulating items at the designated pickup library have a loan duration longer than the recall threshold. If so, then the eligible item with the due date nearest to the current date is recalled.

74.2. Editing the item recall notification email template

The template for the item recall notification email is contained in the Item Recall Email Notice template, found under Admin → Local Administration → Notifications / Action Triggers.

Chapter 75. Notifications / Action Triggers

Action Triggers give administrators the ability to set up actions for specific events. They are useful for notification events such as hold notifications.

To access the Action Triggers module, select Admin → Local Administration → Notifications / Action triggers.

You must have Local Administrator permissions to access the Action Triggers module.

You will notice four tabs on this page: Event Definitions, Hooks, Reactors and Validators.

75.1. Event Definitions

Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:

75.1.1. Table 1: Action Trigger Event Definitions

Field

Description

Owning Library

The shortname of the library for which the action / trigger / hook is defined.

Name

The name of the trigger event, that links to a trigger event environment containing a set of fields that will be returned to the Validators and/or Reactors for processing.

Hook

The name of the trigger for the trigger event. The underlying action_trigger.hook table defines the Fieldmapper class in the core_type column off of which the rest of the field definitions “hang”.

Enabled

Sets the given trigger as enabled or disabled. This must be set to enabled for the Action trigger to run.

Processing Delay

Defines how long after a given trigger / hook event has occurred before the associated action (“Reactor”) will be taken.

Processing Delay Context Field

Defines the field associated with the event on which the processing delay is calculated. For example, the processing delay context field on the hold.capture hook (which has a core_type of ahr) is capture_time.

Processing Group Context Field

Used to batch actions based on its associated group.

Reactor

Links the action trigger to the Reactor.

Validator

The subroutines receive the trigger environment as an argument (see the linked Name for the environment definition) and returns either 1 if the validator is true or 0 if the validator returns false.

Event Repeatability Delay

Allows events to be repeated after this delay interval.

Failure Cleanup

After an event is reacted to and if there is a failure a cleanup module can be run to clean up after the event.

Granularity

Used to group events by how often they should be run. Options are Hourly, Daily, Weekly, Monthly, Yearly, but you may also create new values.

Max Event Validity Delay

Allows events to have a range of time that they are valid. This value works with the Processing Delay to define a time range.

Opt-In Settings Type

Choose which User Setting Type will decide if this event will be valid for a certain user. Use this to allow users to Opt-In or Opt-Out of certain events.

Opt-In User Field

Set to the name of the field in the selected hook’s core type that will link the core type to the actor.usr table.

Success Cleanup

After an event is reacted to successfully a cleanup module can be run to clean up after the event.

Template

A Template Toolkit template that can be used to generate output. The output may or may not be used by the reactor or another external process.

75.2. Creating Action Triggers

From the top menu, select Admin → Local Administration → Notifications / Action triggers.

Click on the New button.

Select an Owning Library.

Create a unique Name for your new action trigger.

Select the Hook.

Check the Enabled check box.

Set the Processing Delay in the appropriate format. E.g. 7 days to run 7 days from the trigger event or 00:01:00 to run 1 hour after the Processing Delay Context Field.

Set the Processing Delay Context Field and Processing Group Context Field.

Select the Reactor, Validator, Failure Cleanup.

Select the Granularity.

Set the Max Event Validity Delay.

Select the Opt-In Setting Type.

Set the Opt-In User Field.

Select the Success Cleanup.

Enter text in the Template text box if required. These are for email messages. Here is a sample template for sending 90 day overdue notices:

[%- USE date -%]
[%- user = target.0.usr -%]
To: [%- params.recipient_email || user.email %]
From: [%- helpers.get_org_setting(target.home_ou.id, 'org.bounced_emails') || lib.email || params.sender_email || default_sender %]
Subject: Overdue Items Marked Lost
Auto-Submitted: auto-generated

Dear [% user.family_name %], [% user.first_given_name %]
The following items are 90 days overdue and have been marked LOST.
[%- params.recipient_email || user.email %][%- params.sender_email || default_sender %]
[% FOR circ IN target %]
  Title: [% circ.target_copy.call_number.record.simple_record.title %]
  Barcode: [% circ.target_copy.barcode %]
  Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
  Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
  Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
  Library: [% circ.circ_lib.name %]
[% END %]

[% FOR circ IN target %]
  Title: [% circ.target_copy.call_number.record.simple_record.title %]
  Barcode: [% circ.target_copy.barcode %]
  Due: [% date.format(helpers.format_date(circ.due_date), '%Y-%m-%d') %]
  Item Cost: [% helpers.get_copy_price(circ.target_copy) %]
  Total Owed For Transaction: [% circ.billable_transaction.summary.total_owed %]
  Library: [% circ.circ_lib.name %]
[% END %]

Once you are satisfied with your new event trigger, click the Save button located at the bottom of the form.

A quick and easy way to create new action triggers is to clone an existing action trigger.

75.2.1. Cloning Existing Action Triggers

Check the check box next to the action trigger you wish to clone.

Click Clone Selected on the top left of the page.

An editing window will open. Notice that the fields will be populated with content from the cloned action trigger. Edit as necessary and give the new action trigger a unique Name.

Click Save.

75.2.2. Editing Action Triggers

Double-click on the action trigger you wish to edit.

The edit screen will appear. When you are finished editing, click Save at the bottom of the form. Or click Cancel to exit the screen without saving.

Before deleting an action trigger, you should consider disabling it through the editing form. This way you can keep it for future use or cloning.

75.2.3. Deleting Action Triggers

Check the check box next to the action trigger you wish to delete

Click Delete Selected on the top-right of the page.

75.2.4. Hooks

Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions “hang”.

75.2.4.1. Table 2. Hooks

Field

Description

Hook Key

A unique name given to the hook.

Core Type

Used to link the action trigger to the IDL class in fm_IDL.xml

Description

Text to describe the purpose of the hook.

Passive

Indicates whether or not an event is created by direct user action or is circumstantial.

You may also create, edit and delete Hooks but the Core Type must refer to an IDL class in the fm_IDL.xml file.

75.2.5. Reactors

Reactors link the trigger definition to the action to be carried out.

75.2.5.1. Table 3. Action Trigger Reactors

Field

Description

Module Name

The name of the Module to run if the action trigger is validated. It must be defined as a subroutine in /openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm or as a module in /openils/lib/perl5/OpenILS/Application/Trigger/Reactor/*.pm.

Description

Description of the Action to be carried out.

You may also create, edit and delete Reactors. Just remember that there must be an associated subroutine or module in the Reactor Perl module.

75.2.6. Validators

Validators set the validation test to be preformed to determine whether the action trigger is executed.

75.2.6.1. Table 4. Action Trigger Validators

Field

Description

Module Name

The name of the subroutine in /openils/lib/perl5/OpenILS/Application/Trigger/Reactor.pm to validate the action trigger.

Description

Description of validation test to run.

You may also create, edit and delete Validators. Just remember that their must be an associated subroutine in the Reactor.pm Perl module.

75.3. Processing Action Triggers

To run the action triggers, an Evergreen administrator will need to run the trigger processing script. This should be set up as a cron job to run periodically. To run the script, use this command:

/openils/bin/action_trigger_runner.pl --process-hooks --run-pending

You have several options when running the script:

--run-pending: Run pending events to send emails or take other actions as specified by the reactor in the event definition.

--process-hooks: Create hook events

--osrf-config=[config_file]: OpenSRF core config file. Defaults to: /openils/conf/opensrf_core.xml

--custom-filters=[filter_file]: File containing a JSON Object which describes any hooks that should use a user-defined filter to find their target objects. Defaults to: /openils/conf/action_trigger_filters.json

--max-sleep=[seconds]: When in process-hooks mode, wait up to [seconds] for the lock file to go away. Defaults to 3600 (1 hour).

--hooks=hook1[,hook2,hook3,…]: Define which hooks to create events for. If none are defined, it defaults to the list of hooks defined in the --custom-filters option. Requires --process-hooks.

--granularity=[label]: Limit creating events and running pending events to those only with [label] granularity setting.

--debug-stdout: Print server responses to STDOUT (as JSON) for debugging.

--lock-file=[file_name]: Sets the lock file for the process.

--verbose: Show details of script processing.

--help: Show help information.

Examples:

Run all pending events that have no granularity set. This is what you tell CRON to run at regular intervals.

perl action_trigger_runner.pl --run-pending

Batch create all "checkout.due" events

perl action_trigger_runner.pl --hooks=checkout.due --process-hooks

Batch create all events for a specific granularity and to send notices for all pending events with that same granularity.

perl action_trigger_runner.pl --run-pending --granularity=Hourly --process-hooks

Chapter 76. Recent Staff Searches

This feature enables you to view your recent searches as you perform them in the staff client. The number of searches that you can view is configurable. This feature is only available through the staff client; it is not available to patrons in the OPAC.

Administrative Settings

By default, ten searches will be saved as you search the staff client. If you want to change the number of saved searches, then you can configure the number of searches that you wish to save through the Library Settings Editor in the Admin module.

To configure the number of recent staff searches:

Click Admin → Local Administration → Library Settings Editor.

Scroll to OPAC: Number of staff client saved searches to display on left side of results and record details pages

Click Edit.

Select a Context from the drop down menu.

Enter the number of searches that you wish to save in the Value field.

Click Update Setting

To retain this setting, the system administrator must restart the web server.

If you do not want to save any searches, then you can turn off this feature.

To deactivate this feature:

Follow steps 1-4 (one through four) as listed in the previous section.

In the value field, enter 0 (zero).

Click Update Setting. This will prevent you from viewing any saved searches.

Recent Staff Searches

Evergreen will save staff searches that are entered through either the basic or advanced search fields. To view recent staff searches:

Enter a search term in either the basic or advanced search fields.

Your search results for the current search will appear in the middle of the screen. The most recent searches will appear on the left side of the screen.

Chapter 77. Standing Penalties

In versions of Evergreen prior to 2.3, the following penalty types were available by default. When applied to user accounts, these penalties prevented users from completing the following actions:

CIRC - Users cannot check out items

HOLD - Users cannot place holds on items

RENEW - Users cannot renew items

In version 2.3, two new penalty types are available in Evergreen:

CAPTURE - This penalty prevents a user’s holds from being captured. If the HOLD penalty has not been applied to a user’s account, then the patron can place a hold, but the targeted item will not appear on a pull list and will not be captured for a hold if it is checked in.

FULFILL - This penalty prevents a user from checking out an item that is on hold. If the HOLD and CAPTURE penalties have not been applied to a user’s account, then the user can place a hold on an item, and the item can be captured for a hold. However, when he tries to check out the item, the circulator will see a pop up box with the name of the penalty type, FULFILL. The circulator must correct the problem with the account or must override the penalty to check out the item.

Chapter 78. Statistical Categories Editor

This is where you configure your statistical categories (stat cats). Stat cats are a way to save and report on additional information that doesn’t fit elsewhere in Evergreen’s default records. It is possible to have stat cats for copies or patrons.

Click Admin → Local Administration → Statistical Categories Editor.

To create a new stat cat, enter the name of the category and select either patron or copy from the Type dropdown menu. Each category type has a number of options you may set.

Copy Statistical Categories

Copy stat cats appear in the Copy Editor, also known as the Edit Item Attributes screen. You might use copy stat cats to track books you have bought from a specific vendor, or donations.

An example of the Create a new statistical category controls for copies:

OPAC Visibility: Should the category be displayed in the OPAC?

Required: Must the category be assigned a value when editing the item attributes?

Archive with Circs: Should the category and its values for the copy be archived with aged circulation data?

SIP Field: Select the SIP field identifier that will contain the category and its value

SIP Format: Specify the SIP format string

Some sample copy stat cats:

To add an entry, select Add. To edit an entry, select the entry you wish to edit from the drop-down list for the category.

This is how the copy stat cats appear in the Copy Editor:

Patron Statistical Categories

Patron stat cats can be used to keep track of information such as the high school a patron attends, or the home library for a consortium patron, e.g. Interlink, or patron preferences. They appear in the fifth section of the Patron Registration or Edit Patron screen.

An example of the Create a new statistical category controls for patrons:

OPAC Visibility: Should the category be displayed in the OPAC?

Required: Must the category be assigned a value when registering a new patron or editing an existing one?

Archive with Circs: Should the category and its values for the patron be archived with aged circulation data?

Allow Free Text: May the person registering/editing the patron information supply their own value for the category?

Show in Summary: Display the category and its value in the patron summary view?

SIP Field: Select the SIP field identifier that will contain the category and its value

SIP Format: Specify the SIP format string

[Warning]
WARNING

If you make a category required and also disallow free text, make sure that you populate an entry list for the category so that the user may select a value. Failure to do so will result in an unsubmittable patron registration/edit form!

Some sample patron stat cats:

To add an entry, click on Add in the category row under the Add Entry column:

To edit an entry, select the entry you wish to edit from the drop-down list for the category:

An organizational unit (consortium, library system branch library, sub library, etc.) may create their own categories and entries, or supplement categories defined by a higher-level org unit with their own entries.

An entry can be set as the default entry for a category and for an org unit. If an entry is set as the default, it will be automatically selected in the patron edit screen, provided no other value has been previously set for the patron. Only one default may be set per category for any given org unit.

Lower-level org unit defaults override defaults set for higher-level org units; but in the absence of a default set for a given org unit, the nearest parent org unit default will be selected.

Default entries for the focus location org unit are marked with an asterisk in the entry dropdowns.

This is how patron stat cats appear in the patron registration/edit screen:

Chapter 79. Statistical Popularity Badges

Statistical Popularity Badges allow libraries to set popularity parameters that define popularity badges, which bibliographic records can earn if they meet the set criteria. Popularity badges can be based on factors such as circulation and hold activity, bibliographic record age, or material type. The popularity badges that a record earns are used to adjust catalog search results to display more popular titles (as defined by the badges) first. Within the OPAC there are two new sort options called "Most Popular" and "Popularity Adjusted Relevance" which will allow users to sort records based on the popularity assigned by the popularity badges.

79.1. Popularity Rating and Calculation

Popularity badge parameters define the criteria a bibliographic record must meet to earn the badge, as well as which bibliographic records are eligible to earn the badge. For example, the popularity parameter "Circulations Over Time" can be configured to create a badge that is applied to bibliographic records for DVDs. The badge can be configured to look at circulations within the last 2 years, but assign more weight or popularity to circulations from the last 6 months.

Multiple popularity badges may be applied to a bibliographic record. For each applicable popularity badge, the record will be rated on a scale of 1-5, where a 5 indicates the most popular. Evergreen will then assign an overall popularity rating to each bibliographic record by averaging all of the popularity badge points earned by the record. The popularity rating is stored with the record and will be used to rank the record within search results when the popularity badge is within the scope of the search. The popularity badges are recalculated on a regular and configurable basis by a cron job. Popularity badges can also be recalculated by an administrator directly on the server.

79.2. Creating Popularity Badges

There are two main types of popularity badges: point-in-time popularity (PIT), which looks at the popularity of a record at a specific point in time—such as the number of current circulations or the number of open hold requests; and temporal popularity (TP), which looks at the popularity of a record over a period of time—such as the number of circulations in the past year or the number of hold requests placed in the last six months.

The following popularity badge parameters are available for configuration:

Holds Filled Over Time (TP)

Holds Requested Over Time (TP)

Current Hold Count (PIT)

Circulations Over Time (TP)

Current Circulation Count (PIT)

Out/Total Ratio (PIT)

Holds/Total Ratio (PIT)

Holds/Holdable Ratio (PIT)

Percent of Time Circulating (Takes into account all circulations, not specific period of time)

Bibliographic Record Age (days, newer is better) (TP)

Publication Age (days, newer is better) (TP)

On-line Bib has attributes (PIT)

Bib has attributes and copies (PIT)

Bib has attributes and copies or URIs (PIT)

Bib has attributes (PIT)

To create a new Statistical Popularity Badge:

Go to Administration→Local Administration→Statistical Popularity Badges.

Click on Actions→Add badge.

Fill out the following fields as needed to create the badge:

only Name, Scope, Weight, Recalculation Interval, Importance Interval, and Discard Value Count are required

Name: Library assigned name for badge. Each name must be unique. The name will show up in the OPAC record display. For example: Most Requested Holds for Books-Last 6 Months. Required field.

Description: Further information to provide context to staff about the badge.

Scope: Defines the owning organization unit of the badge. Badges will be applied to search result sorting when the Scope is equal to, or an ancestor, of the search location. For example, a branch specific search will include badges where the Scope is the branch, the system, and the consortium. A consortium level search, will include only badges where the Scope is set to the consortium. Item specific badges will apply only to records that have items owned at or below the Scope. Required field.

Weight: Can be used to indicate that a particular badge is more important than the other badges that the record might earn. The weight value serves as a multiplier of the badge rating. Required field with a default value of 1.

Age Horizon: Indicates the time frame during which events should be included for calculating the badge. For example, a popularity badge for Most Circulated Items in the Past Two Years would have an Age Horizon of 2 years. The Age Horizon should be entered as a number followed by day(s), month(s), year(s), such as 6 months or 2 years. Use with temporal popularity (TP) badges only.

Importance Horizon: Used in conjunction with Age Horizon, this allows more recent events to be considered more important than older events. A value of zero means that all events included by the Age Horizon will be considered of equal importance. With an Age Horizon of 2 years, an Importance Horizon of 6 months means that events, such as checkouts, that occurred within the past 6 months will be considered more important than the circulations that occurred earlier within the Age Horizon.

Importance Interval: Can be used to further divide up the timeframe defined by the Importance Horizon. For example, if the Importance Interval is 1 month, Evergreen will combine all of the events within that month for adjustment by the Importance Scale (see below). The Importance Interval should be entered as a number followed by 'day(s), week(s), month(s), year(s), such as 6 months or 2 years. Required field.

Importance Scale: The Importance Scale can be used to assign additional importance to events that occurred within the most recent Importance Interval. For example, if the Importance Horizon is 6 months and the Importance Interval is 1 month, the Importance Scale can be set to 6 to indicate that events that happened within the last month will count 6 times, events that happened 2 months ago will count 5 times, etc. The Importance Scale should be entered as a number followed by day(s), week(s), month(s), year(s), such as 6 months or 2 years.

Percentile: Can be used to assign a badge to only the records that score above a certain percentile. For example, it can be used indicate that you only want to assign the badge to records in the top 5% of results by setting the field to 95. To optimize the popularity badges, percentile should be set between 95-99 to assign a badge to the top 5%-1% of records.

Attribute Filter: Can be used to assign a badge to records that contain a specific Record Attribute. Currently this field can be configured by running a report (see note below) to obtain the JSON data that identifies the Record Attribute. The JSON data from the report output can be copied and pasted into this field. A new interface for creating Composite Record Attributes will be implemented with future development of the web client.

To run a report to obtain JSON data for the Attribute Filter, use SVF Record Attribute Coded Value Map as the template Source. For Displayed Fields, add Code, ID, and/or Description from the Source; also display the Definition field from the Composite Definition linked table. This field will display the JSON data in the report output. Filter on the Definition from the Composite Definition liked table and set the Operator to Is not NULL.

Circ Mod Filter: Apply the badge only to items with a specific circulation modifier. Applies only to item related badges as opposed to "bib record age" badges, for example.

Bib Source Filter: Apply the badge only to bibliographic records with a specific source.

Location Group Filter: Apply the badge only to items that are part of the specified Copy Location Group. Applies only to item related badges.

Recalculation Interval: Indicates how often the popularity value of the badge should be recalculated for bibliographic records that have earned the badge. Recalculation is controlled by a cron job. Required field with a default value of 1 month.

Fixed Rating: Can be used to set a fixed popularity value for all records that earn the badge. For example, the Fixed Rating can be set to 5 to indicate that records earning the badge should always be considered extremely popular.

Discard Value Count: Can be used to prevent certain records from earning the badge to make Percentile more accurate by discarding titles that are below the value indicated. For example, if the badge looks at the circulation count over the past 6 months, Discard Value Count can be used to eliminate records that had too few circulations to be considered "popular". If you want to discard records that only had 1-3 circulations over the past 6 months, the Discard Value Count can be set to 3. Required field with a default value of 0.

Last Refresh Time: Displays the last time the badge was recalculated based on the Recalculation Interval.

Popularity Parameter: Types of TP and PIT factors described above that can be used to create badges to assign popularity to bibliographic records.

Click OK to save the badge.

79.3. New Global Flags

OPAC Default Sort: can be used to set a default sort option for the catalog. Users can always override the default by manually selecting a different sort option while searching.

Maximum Popularity Importance Multiplier: used with the Popularity Adjusted Relevance sort option in the OPAC. Provides a scaled adjustment to relevance score based on the popularity rating earned by bibliographic records. See below for more information on how this flag is used.

79.4. Sorting by Popularity in the OPAC

Within the stock OPAC template there is a new option for sorting search results called "Most Popular". Selecting "Most Popular" will first sort the search results based on the popularity rating determined by the popularity badges and will then apply the default "Sort by Relevance". This option will maximize the popularity badges and ensure that the most popular titles appear higher up in the search results.

There is a second new sort option called "Popularity Adjusted Relevance", which can be used to find a balance between popularity and relevance in search results. For example, it can help ensure that records that are popular, but not necessarily relevant to the search, do not supersede records that are both popular and relevant in the search results. It does this by sorting search results using an adjusted version of Relevance sorting. When sorting by relevance, each bibliographic record is assigned a baseline relevance score between 0 and 1, with 0 being not relevant to the search query and 1 being a perfect match. With "Popularity Adjusted Relevance" the baseline relevance is adjusted by a scaled version of the popularity rating assigned to the bibliographic record. The scaled adjustment is controlled by a Global Flag called "Maximum Popularity Importance Multiplier" (MPIM). The MPIM takes the average popularity rating of a bibliographic record (1-5) and creates a scaled adjustment that is applied to the baseline relevance for the record. The adjustment can be between 1.0 and the value set for the MPIM. For example, if the MPIM is set to 1.2, a record with an average popularity badge score of 5 (maximum popularity) would have its relevance multiplied by 1.2—in effect giving it the maximum increase of 20% in relevance. If a record has an average popularity badge score of 2.5, the baseline relevance of the record would be multiplied by 1.1 (due to the popularity score scaling the adjustment to half way between 1.0 and the MPIM of 1.2) and the record would receive a 10% increase in relevance. A record with a popularity badge score of 0 would be multiplied by 1.0 (due to the popularity score being 0) and would not receive a boost in relevance.

79.5. Popularity Badge Example

A popularity badge called "Long Term Holds Requested" has been created which has the following parameters:

Popularity Parameter: Holds Requested Over Time Scope: CONS Weight: 1 (default) Age Horizon: 5 years Percentile: 99 Recalculation Interval: 1 month (default) Discard Value Count: 0 (default)

This popularity badge will rate bibliographic records based on the number of holds that have been placed on it over the past 5 years and will only apply the badge to the top 1% of records (99th percentile).

If a keyword search for harry potter is conducted and the sort option "Most Popular" is selected, Evergreen will apply the popularity rankings earned from badges to the search results.

Title search: harry potter. Sort by: Most Popular.

The popularity badge also appears in the bibliographic record display in the catalog. The name of the badge earned by the record and the popularity rating are displayed in the Record Details.

A popularity badge of 5.0/5.0 has been applied to the most popular bibliographic records where the search term "harry potter" is found in the title. In the image above, the popularity badge has identified records from the Harry Potter series by J.K. Rowling as the most popular titles matching the search and has listed them first in the search results.

Chapter 80. Work Log

80.1. Expanding the Work Log

In versions of Evergreen prior to 2.3, the work log recorded check ins, checkouts, patron registration, patron editing, and renewals. In version 2.3, the work log also records holds that have been placed and payments that have been received.

In this example, a staff member has collected a fine from a patron. To view this action in the work log, click Admin → Local Administration → Work Log. By default, the work log will record the staff member’s username, the amount that was received, the payment type, the patron’s barcode, and the patron’s last name.

In this example, a staff member has placed a hold for a patron. To view this action in the work log, click Admin → Local Administration → Work Log. By default, the work log will record the staff member’s username, the hold type, the patron’s barcode, and the patron’s last name.

Part VIII. Acquisitions

Chapter 81. Acquisitions

This section is intended for those who are responsible for managing and processing acquisitions.

Before beginning to use Acquisitions, the following must be configured by an administrator:

Cancel/Suspend Reasons (optional)

Claiming (optional)

Currency Types (defaults exist)

Distribution Formulas (optional)

EDI Accounts (optional) (see Setting Up EDI Acquisitions under Software Installation)

Exchange Rates (defaults exist)

Funds and Fund Sources

Invoice Types (defaults exist) and Invoice Payment Methods

Line Item Features (optional)

Merge Overlay Profiles and Record Match Sets (see Batch Importing MARC Records in Cataloging)

Providers

81.1. Acquisitions Workflow

The following diagram shows how the workflow functions in Evergreen. One of the differences in this process you should notice is that when creating a selection list on the vendor site, libraries will be downloading and importing the vendor bibs and item records.

Chapter 82. Selection Lists and Purchase Orders

82.1. Selection Lists

Selection lists allow you to create, manage, and save lists of items that you may want to purchase. To view your selection list, click Acquisitions → My Selection Lists. Use the general search to view selection lists created by other users.

82.1.1. Create a selection list

Selection lists can be created in four areas within the module. Selection lists can be created when you Add Brief Records, Upload MARC Order Records, or find records through the MARC Federated Search. In each of these interfaces, you will find the Add to Selection List field. Enter the name of the selection list that you want to create in that field.

Selection lists can also be created through the My Selection Lists interface:

Click Acquisitions → My Selection Lists.

Click the New Selection List drop down arrow.

Enter the name of the selection list in the box that appears.

Click Create.

82.1.2. Add items to a selection list

You can add items to a selection list in one of three ways: add a brief record; upload MARC order records; add records through a federated search; or use the View/Place Orders menu item in the catalog.

82.1.3. Clone selection lists

Cloning selection lists enables you to copy one selection list into a new selection list. You can maintain both copies of the list, or you can delete the previous list.

Click Acquisitions → My Selection Lists.

Check the box adjacent to the list that you want to clone.

Click Clone Selected.

Enter a name into the box that appears, and click Clone.

82.1.4. Merge selection lists

You can merge two or more selection lists into one selection list.

Click Acquisitions → My Selection Lists.

Check the boxes adjacent to the selection lists that you want to merge, and click Merge Selected.

Choose the Lead Selection List from the drop down menu. This is the list to which the items on the other list(s) will be transferred.

Click Merge.

82.1.5. Delete selection lists

You can delete selection lists that you do not want to save. You will not be able to retrieve these items through the General Search after you have deleted the list. You must delete all line items from a selection list before you can delete the list.

Click Acquisitions → My Selection Lists.

Check the box adjacent to the selection list(s) that you want to delete.

Click Delete Selected.

82.1.6. Mark Ready for Selector

After an item has been added to a selection list or purchase order, you can mark it ready for selector. This step is optional but may be useful to individual workflows.

If you want to mark part of a selection list ready for selector, then you can check the box(es) of the line item(s) that you wish to mark ready for selector. If you want to mark the entire list ready for selector, then skip to step 2.

Click Actions → Mark Ready for Selector.

A pop up box will appear. Choose to mark the selected line items or all line items.

Click Go.

The screen will refresh. The marked line item(s) will be highlighted pink, and the status changes to selector~ready.

82.1.7. Convert selection list to purchase order

Use the Actions menu to convert a selection list to a purchase order.

From a selection list, click Actions ~> Create Purchase Order.

A pop up box will appear.

Select the ordering agency from the drop down menu.

Enter the provider.

Check the box adjacent to prepayment required if prepayment is required.

Choose if you will add All Lineitems or Selected Lineitems to your purchase order.

Check the box if you want to Import Bibs and Create Copies in the catalog.

Click Submit.

82.2. Purchase Orders

82.2.1. Duplicate Purchase Order Name Warning Dialog

When creating a purchase order or editing an existing purchase order, the purchase order name must be unique for the ordering agency. Evergreen will display a warning dialog to users, if they attempt to create or edit purchase order names that match the names of already existing purchase orders at the same ordering agency. The Duplicate Purchase Order Name Warning Dialog includes a link that will open the matching purchase order in a new tab.

Purchase Order Names are case sensitive.

Duplicate PO Name Detection When Creating a New Purchase Order

When a duplicate purchase order name is detected during the creation of a new purchase order, the user may:

Click View PO to view the purchase order with the matching name. The purchase order will open in a new tab.

Click Cancel to cancel the creation of the new purchase order.

Within the Name (optional) field, enter a different, unique name for the new purchase order.

If the purchase order name is unique for the ordering agency, the user will continue filling in the remaining fields and click Save.

If the purchase order name is not unique for the ordering agency, the Save button will remain grayed out to the user until the purchase order is given a unique name.

Duplicate PO Name Detection When Editing the Name of an Existing Purchase Order

To change the name of an existing purchase order:

Within the purchase order, the Name of the purchase order is a link (located at the top left-hand side of the purchase order). Click the PO Name.

A new window will open, where users can rename the purchase order.

Enter the new purchase order name.

Click OK.

If the new purchase order name is unique for the ordering agency, the purchase order will be updated to reflect the new name. If the purchase order name is not unique for the ordering agency, the purchase order will not be updated with the new name. Instead, the user will see the Duplicate Purchase Order Name Warning Dialog within the purchase order.

When a duplicate purchase order name is detected during the renaming of an existing purchase order, the user may:

Click View PO to view the purchase order with the matching name. The purchase order will open in a new tab.

Repeat the steps to change the name of an existing purchase order and make the name unique.

82.2.2. Purchase Order Activation Progress Bar

After you click Activate Order, you will be presented with the record import interface for records that are not already in the catalog. Once you complete entering in the parameters for the record import interface, the progress screen will appear. As of Evergreen 2.9, this progress screen consists of a progress bar in the foreground, and a tally of the following in the background of the bottom-left corner:

Lineitems processed

Vandelay Records processed

Bib Records Merged/Imported

ACQ Copies Processed

Debits Encumbered

Real Copies Processed

82.2.3. Activate Purchase Order with Zero Copies

In previous versions, by default, a purchase order could be activated with or without copies attached to line items.

In versions 2.3 and above, by default, a purchase order cannot be activated if a line item on the purchase order has zero copies. A new feature enables you to activate a purchase order that lacks copies.

To activate a purchase order with line items that have zero copies, check the box Allow activation with zero-copy lineitems.

82.2.4. Enhancements to Canceled and Delayed Items

Cancel/Delay reasons have been modified so that you can easily differentiate between canceled and delayed items. Each label now begins with Canceled or Delayed. To view the list, click Admin → Server Administration → Acquisitions → Cancel Reasons.

The cancel/delay reason label is displayed as the line item status in the list of line items or as the copy status in the list of copies.

A delayed line item can now be canceled. You can mark a line item as delayed, and if later, the order cannot be filled, you can change the line item’s status to canceled. When delayed line items are canceled, the encumbrances are deleted.

Cancel/delay reasons now appear on the worksheet and the printable purchase order.

82.2.5. Paid PO Line Items

Purchase Order line items are marked as "Paid" in red text when all non-cancelled copies on the line item have been invoiced.

82.3. Brief Records

Brief records are short bibliographic records with minimal information that are often used as placeholder records until items are received. Brief records can be added to selection lists or purchase orders and can be imported into the catalog. You can add brief records to new or existing selection lists. You can add brief records to new, pending or on~order purchase orders.

82.3.1. Add brief records to a selection list

Click Acquisitions → New Brief Record. You can also add brief records to an existing selection list by clicking the Actions menu on the selection list and choosing Add Brief Record.

Choose a selection list from the drop down menu, or enter the name of a new selection list.

Enter bibliographic information in the desired fields.

Click Save Record.

82.3.2. Add brief records to purchase orders

You can add brief records to new or existing purchase orders.

Open or create a purchase order. See the section on purchase orders for more information.

Click Add Brief Record.

Enter bibliographic information in the desired fields. Notice that the record is added to the purchase order that you just created.

Click Save Record.

82.4. MARC Federated Search

The MARC Federated Search enables you to import bibliographic records into a selection list or purchase order from a Z39.50 source.

Click Acquisitions → MARC Federated Search.

Check the boxes of Z39.50 services that you want to search. Your local Evergreen Catalog is checked by default. Click Submit.

A list of results will appear. Click the "Copies" link to add copy information to the line item. See the section on Line Items for more information.

Click the Notes link to add notes or line item alerts to the line item. See the section on Line Items for more information.

Enter a price in the "Estimated Price" field.

You can save the line item(s) to a selection list by checking the box on the line item and clicking Actions → Save Items to Selection List. You can also create a purchase order from the line item(s) by checking the box on the line item and clicking Actions ~> Create Purchase Order.

82.5. Line Items

82.5.1. Return to Line Item

This feature enables you to return to a specific line item on a selection list, purchase order, or invoice after you have navigated away from the page that contained the line item. This feature is especially useful when you must identify a line item in a long list. After working with a line item, you can return to your place in the search results or the list of line items.

To use this feature, select a line item, and then, depending on the location of the line item, click Return or Return to search. Evergreen will take you back to the specific line item in your search and highlight the line item with a colored box.

For example, you retrieve a selection list, find a line item to examine, and click the Copies link. After editing the copies, you click Return. Evergreen takes you back to your selection list and highlights the line item that you viewed.

This feature is available in General Search Results, Purchase Orders, and Selection Lists, whenever any of the following links are available:

Selection List

Purchase Order

Copies

Notes

Worksheet

This feature is available in Invoices whenever any of the following links are available:

Title

Selection List

Purchase Order

82.5.2. Display a Count of Existing Copies on Selection List and Purchase Order Lineitems

When displaying Acquisitions lineitems within the Selection List and Purchase Order interfaces, Evergreen displays a count of existing catalog copies on the lineitem. The count of existing catalog copies refers to the number of copies owned at the ordering agency and / or the ordering agency’s child organization units.

The counts display for lineitems that have a direct link to a catalog record. Generally, this includes lineitems created as "on order" based on an existing catalog record and lineitems where "Load Bibs and Items" has been applied.

The count of existing copies does not include copies that are in either a Lost or a Missing status.

The existing copy count displays in the link "bar" located below the Order Identifier within the lineitem.

If no existing copies are found, a "0" (zero) will display in plain text.

If the existing copy count is greater than zero, then the count will display in bold and red on the lineitem.

The user may also hover over the existing copy count to view the accompanying tooltip.

Chapter 83. Invoices

You can create invoices for purchase orders, individual line items, and blanket purchases. You can also link existing invoices to purchase order.

You can invoice items before you receive the items if desired. You can also reopen closed invoices, and you can print all invoices.

83.1. Creating invoices and adding line items

You can add specific line items to an invoice from the PO or acquisitions search results screen. You can also search for relevant line items from within the invoice interface. In addition, you can add all line items from an entire Purchase order to an invoice or you can create a blanket invoice for items that are not attached to a purchase order.

83.1.1. Creating a blanket invoice

You can create a blanket invoice for purchases that are not attached to a purchase order.

Click Acquisitions → Create invoice.

Enter the invoice information in the top half of the screen.

To add charges for materials not attached to a purchase order, click Add Charge… This functionality may also be used to add shipping, tax, and other fees.

Select a charge type from the drop-down menu.

New charge types can be added via Admin → Server Administration → Acquisitions → Invoice Item Type.

Select a fund from the drop-down menu.

Enter a Title/Description of the resource.

Enter the amount that you were billed.

Enter the amount that you paid.

Save the invoice.

83.1.2. Adding line items from a Purchase Order or search results screen to an invoice

You can create an invoice or add line items to an invoice directly from a Purchase Order or an acquisitions search results screen.

Place a checkmark in the box for selected line items from the Purchase Order' or acquisitions search results page.

If you are creating a new invoice, click Actions → Create Invoice From Selected Line Items. Enter the invoice information in the top half of the screen.

If you are adding the line items to an existing invoice, click Actions → Link Selected Line Items to Invoice. Enter the Invoice # and Provider and then click the Link button.

Evergreen automatically enters the number of items that was ordered in the # Invoiced and # Paid fields. Adjust these quantities as needed.

Enter the amount that the organization was billed. This entry will automatically propagate to the Paid field.

You have the option to add charge types if applicable. Charge types are additional charges that can be selected from the drop-down menu. Common charge types include taxes and handling fees.

You have four options for saving an invoice.

Click Save to save the changes you have made while staying in the current invoice.

Click Save & Clear to save the changes you have made and to replace the current invoice with a new invoice so that you can continue invoicing items.

Click Prorate to save the invoice and prorate any additional charges, such as taxes, across funds, if multiple funds have been used to pay the invoice.

Prorating will only be applied to charge types that have the Prorate? flag set to true. This setting can be adjusted via Admin → Server Administration → Acquisitions → Invoice Item Type.

Click Close. Choose this option when you have completed the invoice. This option will also save any changes that have been made. Funds will be disencumbered when the invoice is closed.

You can re-open a closed invoice by clicking the link, Re-open invoice. This link appears at the bottom of a closed invoice.

83.1.3. Search for line items from an invoice

You can open an invoice, search for line items from the invoice, and add your search results to a new or existing invoice. This feature is especially useful when you want to populate an invoice with line items from multiple purchase orders.

In this example, we’ll add line items to a new invoice:

Click Acquisitions → Create Invoice.

An invoice summary appears at the top of the invoice and includes the number of line items on the invoice and the expected cost of the items. This number will change as we add line items to the invoice.

Enter the invoice details (optional). If you do not enter the invoice details, then Evergreen will populate the Provider and Receiver fields with information from the line items.

If you do not want to display the details, click Hide Details.

Click the Search tab to add line items to an invoice.

Select your search criteria from the drop-down menu.

On the right side of the screen, Limit to Invoiceable Items is checked by default. Invoiceable items are those that are on order, have not been cancelled, and have not yet been invoiced. Evergreen also filters out items that have already been added to an invoice. Finally, if this box is checked, and if your entered the invoice details at the top of the screen, then Evergreen will filter your search for items that have the same provider as the one that you entered. If you have not entered the invoice details, then Evergreen removes this limit.

Sort by title (optional). By default, results are listed by line item number. Check this box to sort by ascending title.

Building the results list progressively (optional). By default, new search results will replace previous results on the screen. Check this box for the search results list to build with each subsequent search. This option is useful for libraries that might search for line items by scanning an ISBN. Several ISBNs can be scanned and then the entire result set can be selected and moved to the invoice in a batch.

Click Search.

Use the Next button to page through results, or select a line item(s), and click Add Selected Items to Invoice. .The rows that you selected are highlighted, and the invoice summary at the top of the screen updates.

Click the Invoice tab to see the updated invoice.

Evergreen automatically enters the number of items that was ordered in the # Invoiced and # Paid fields. Adjust these quantities as needed.

Enter the amount that the organization was billed. This entry will automatically propagate to the Paid field. The Per Copy field calculates the cost of each copy by dividing the amount that was billed by the number of copies for which the library paid.

83.1.4. Create an invoice for a purchase order

You can create an invoice for all of the line items on a purchase order. With the exception of fields with drop-down menus, no limitations on the data that you enter exist.

Open a purchase order.

Click Create Invoice.

Enter a Vendor Invoice ID. This number may be listed on the paper invoice sent from your vendor.

Choose a Receive Method from the drop-down menu. The system will default to Paper.

The Provider is generated from the purchase order and is entered by default.

Enter a note (optional).

Select a payment method from the drop-down menu (optional).

The Invoice Date is entered by default as the date that you create the invoice. You can change the date by clicking in the field. A calendar drops down.

Enter an Invoice Type (optional).

The Shipper defaults to the provider that was entered in the purchase order.

Enter a Payment Authorization (optional).

The Receiver defaults to the branch at which your workstation is registered. You can change the receiver by selecting an org unit from the drop-down menu.

The bibliographic line items are listed in the next section of the invoice. Along with the title and author of the line items is a summary of copies ordered, received, invoiced, claimed, and cancelled. You can also view the amounts estimated, encumbered, and paid for each line item. Finally, each line item has a line item ID and links to the selection list (if used) and the purchase order.

Evergreen automatically enters the number of items that was ordered in the # Invoiced and # Paid fields. Adjust these quantities as needed.

Enter the amount that the organization was billed. This entry will automatically propagate to the Paid field. The Per Copy field calculates the cost of each copy by dividing the amount that was billed by the number of copies for which the library paid.

You have the option to add charge types if applicable. Charge types are additional charges that can be selected from the drop-down menu. Common charge types include taxes and handling fees.

You have four options for saving an invoice.

Click Save to save the changes you have made while staying in the current invoice.

Click Save & Clear to save the changes you have made and to replace the current invoice with a new invoice so that you can continue invoicing items.

Click Prorate to save the invoice and prorate any additional charges, such as taxes, across funds, if multiple funds have been used to pay the invoice.

Prorating will only be applied to charge types that have the Prorate? flag set to true. This setting can be adjusted via Admin → Server Administration → Acquisitions → Invoice Item Type.

Click Close. Choose this option when you have completed the invoice. This option will also save any changes that have been made. Funds will be disencumbered when the invoice is closed.

You can re-open a closed invoice by clicking the link, Re-open invoice. This link appears at the bottom of a closed invoice.

83.1.5. Link an existing invoice to a purchase order

You can use the link invoice feature to link an existing invoice to a purchase order. For example, an invoice is received for a shipment with items on purchase order #1 and purchase order #2. When the invoice arrives, purchase order #1 is retrieved, and the invoice is created. To receive the items on purchase order #2, simply link the invoice to the purchase order. You do not need to recreate it.

Open a purchase order.

Click Link Invoice.

Enter the Invoice # and the Provider of the invoice to which you wish to link.

Click Link.

83.2. Electronic Invoicing

Evergreen can receive electronic invoices from providers. To access an electronic invoice, you must:

Configure EDI for your provider.

Evergreen will receive invoices electronically from the provider.

Click Acquisitions → Open Invoices to view a list of open invoices, or use the General Search to retrieve invoices. Click a hyperlinked invoice number to view the invoice.

83.3. View an invoice

You can view an invoice in one of four ways: view open invoices; view invoices on a purchase order; view invoices by searching specific invoice fields; view invoices attached to a line item.

To view open invoices, click Acquisitions → Open invoices. This opens the Acquisitions Search screen. The default fields search for open invoices. Click Search.

To view invoices on a purchase order, open a purchase order and click the View Invoices link. The number in parentheses indicates the number of invoices that are attached to the purchase order.

To view invoices by searching specific invoice fields, see the section on searching the acquisitions module.

To view invoices for a line item, see the section on line item invoices.

83.4. Receive Items From an Invoice

This feature enables users to receive items from an invoice. Staff can receive individual copies, or they can receive items in batch.

83.4.1. Receive Items in Batch (List Mode)

In this example, we have created a purchase order, added line items and copies, and activated the purchase order. We will create an invoice from the purchase order, receive items, and invoice them. We will receive the items in batch from the invoice.

1) Retrieve a purchase order.

2) Click Create Invoice.

3) The blank invoice appears. In the top half of the invoice, enter descriptive information about the invoice. In the bottom half of the invoice, enter the number of items for which you were invoiced, the amount that you were billed, and the amount that you paid.

4) Click Save. You must choose a save option before you can receive items.

5) The screen refreshes. In the top right corner of the screen, click Receive Items.

6) The Acquisitions Invoice Receiving screen opens. By default, this screen enables users to receive items in batch, or Numeric Mode. You can select the number of copies that you want to receive; you are not receiving specific copies in this mode.

7) Select the number of copies that you want to receive. By default, the number that you invoiced will appear. In this example, we will receive one copy of each title.

You cannot receive fewer items than 0 (zero) or more items than the number that you ordered.

8) Click Receive Selected Copies.

9) When you are finished receiving items, close the screen. You can repeat this process as you receive more copies.

83.4.2. Receive Specific Copies (Numeric Mode)

In this example, we have created a purchase order, added line items and copies, and activated the purchase order. We will create an invoice from the purchase order, receive items, and invoice them. We will receive specific copies from the invoice. This function may be useful to libraries who purchase items that have been barcoded by their vendor.

1) Complete steps 1-5 in the previous section.

2) The Acquisitions Invoice Receiving screen by default enables user to receive items in batch, or Numeric Mode. Click Use List Mode to receive specific copies.

3) Select the check boxes adjacent to the copies that you want to receive. Leave unchecked the copies that you do not want to receive.

4) Click Receive Selected Copies.

The screen will refresh. Copies that have not yet been received remain on the screen so that you can receive them when they arrive.

5) When all copies on an invoice have been received, a message confirms that no copies remain to be received.

6) The purchase order records that all items have been received.

Chapter 84. Load MARC Order Records

The Acquisitions Load MARC Order Record interface enables you to add MARC records to selection lists and purchase orders and upload the records into the catalog. You can both create and activate purchase orders in one step from this interface. You can also load bibs and items into the catalog.

Leveraging the match sets available in the cataloging MARC batch Import interface, you can also utilize record matching mechanisms to prevent the creation of duplicate records.

For detailed instructions on record matching and importing, see Batch Importing MARC Records.

84.1. Basic Upload Options

Click Acquisitions → Load MARC Order Records.

If you want to upload the MARC records to a new purchase order, then check Create Purchase Order.

If you want to activate the purchase order at the time of creation, then check Activate Purchase Order.

Enter the name of the Provider. The text will auto-complete.

Select an org unit from the drop down menu. The context org unit is the org unit responsible for placing and managing the order. It defines what org unit settings (eg copy locations) are in scope, what fiscal year to use, who is allowed to view/modify the PO, where the items should be delivered and the EDI SAN. In the case of a multi-branch system uploading records for multiple branches, choosing the system is probably best. Single branch libraries or branches responsible for their own orders should probably select the branch.

If you want to upload the records to a selection list, you can select a list from the drop down menu, or type in the name of the selection list that you want to create.

Select a Fiscal Year from the dropdown menu that matches the fiscal year of the funds that will be used for the order. If no fiscal year is selected, the system will use the organizational unit’s default fiscal year stored in the database. If not fiscal year is set, the system will default to the current calendar year.

84.2. Record Matching Options

Use the options below the horizontal rule for the system to check for matching records before importing an order record.

Create a queue to which you can upload your records, or add you records to an existing queue

Select a Record Match Set from the drop-down menu.

Select a Merge Profile. Merge profiles enable you to specify which tags should be removed or preserved in incoming records.

Select a Record Source from the drop-down menu.

If you want to automatically import records on upload, select one or more of the following options.

Import Non-Matching Records - import any records that don’t have a match in the system.

Merge on Exact Match (901c) - use only for records that will match on the 901c field.

Merge on Single Match - import records that only have one match in the system.

Merge on Best Match - If more than one match is found in the catalog for a given record, Evergreen will attempt to perform the best match as defined by the match score.

To only import records that have a quality equal to or greater than the existing record, enter a Best/Single Match Minimum Quality Ratio. Divide the incoming record quality score, as determined by the match set’s quality metrics, by the record quality score of the best match that exists in the catalog. If you want to ensure that the inbound record is only imported when it has a higher quality than the best match, then you must enter a ratio that is higher than 1, such as 1.1. If you want to bypass all quality restraints, enter a 0 (zero) in this field.

Select an Insufficient Quality Fall-Through Profile if desired. This field enables you to indicate that if the inbound record does not meet the configured quality standards, then you may still import the record using an alternate merge profile. This field is typically used for selecting a merge profile that allows the user to import holdings attached to a lower quality record without replacing the existing (target) record with the incoming record. This field is optional.

If your order records contain holdings information, by default, Evergreen will load them as acquisitions copies. (Note: These can be overlayed with real copies during the MARC batch importing process.) Or you can select Load Items for Imported Records to load them as live copies that display in the catalog.

84.3. Default Upload Settings

You can set default upload values by modifying the following settings in Admin → Local Administration → Library Settings Editor:

Upload Activate PO

Upload Create PO

Upload Default Insufficient Quality Fall-Thru Profile

Upload Default Match Set

Upload Default Merge Profile

Upload Upload Default Min. Quality Ratio

Upload Default Provider

Upload Import Non Matching by Default

Upload Load Items for Imported Records by Default

Upload Merge on Best Match by Default

Upload Merge on Exact Match by Default

Upload Merge on Single Match by Default

84.4. Sticky Settings

If the above default settings are not implemented, the selections/values used in the following fields will be sticky and will automatically populate the fields the next time the Load MARC Order Records screen is pulled up:

Create Purchase Order

Activate Purchase Order

Context Org Unit

Record Match Set

Merge Profile

Import Non-Matching Records

Merge on Exact Match (901c)

Merge on Single Match

Merge on Best Match

Best/Single Match Minimum Quality Ratio

Insufficient Quality Fall-Through Profile

Load Items for Imported Records

84.5. Use Cases for MARC Order Upload form

You can add items to a selection list or purchase order and ignore the record matching options, or you can use both acquisitions and cataloging functions. In these examples, you will use both functions.

Example 1 Using the Acquisitions MARC Batch Load interface, upload MARC records to a selection list and import queue, and match queued records with existing catalog records.

In this example, an acquisitions librarian has received a batch of MARC records from a vendor. She will add the records to a selection list and a Vandelay record queue.

A cataloger will later view the queue, edit the records, and import them into the catalog.

Click Acquisitions → Load MARC Order Records

Add MARC order records to a Selection list and/or a Purchase Order. Check the box to create a purchase order if desired.

Select a Provider from the drop-down menu, or begin typing the code for the provider, and the field will auto-fill.

Select a Context Org Unit from the drop down-menu, or begin typing the code for the context org unit, and the field will auto-fill.

Select a Selection List from the drop down menu, or begin typing the name of the selection list. You can create a new list, or the field will auto-fill.

Create a new record import queue, or upload the records to an existing queue.

Select a Record Match Set.

Browse your computer to find the MARC file, and click Upload.

The processed items appear at the bottom of the screen.

You can click the link(s) to access the selection list or the import queue. Click the link to View Selection List.

Look at the first line item. The line item has not yet been linked to the catalog, but it is linked to a record import queue. Click the link to the queue to examine the MARC record.

The batch import interface opens in a new tab. The bibliographic records appear in the queue. Records that have matches are identified in the queue. You can edit these records and/or import them into the catalog, completing the process.

Example 2: Using the Acquisitions MARC Batch Load interface, upload MARC records to a selection list, and use the Vandelay options to import the records directly into the catalog. The Vandelay options will enable you to match incoming records with existing catalog records.

In this example, a librarian will add MARC records to a selection list, create criteria for matching incoming and existing records, and import the matching and non-matching records into the catalog.

Click Acquisitions → Load MARC Order Records

Add MARC order records to a Selection list and/or a Purchase Order. Check the box to create a purchase order if desired.

Select a Provider from the drop down menu, or begin typing the code for the provider, and the field will auto-fill.

Select a Context Org Unit from the drop down menu, or begin typing the code for the context org unit, and the field will auto-fill.

Select a Selection List from the drop down menu, or begin typing the name of the selection list. You can create a new list, or the field will auto-fill.

Create a new record import queue, or upload the records to an existing queue.

Select a Record Match Set.

Select Merge Profile → Match-Only Merge.

Check the boxes adjacent to Import Non-Matching Records and Merge on Best Match.

Browse your computer to find the MARC file, and click Upload.

Click the link to View Selection List Line items that do not match existing catalog records on title and ISBN contain the link, link to catalog. This link indicates that you could link the line item to a catalog record, but currently, no match exists between the line item and catalog records. Line items that do have matching records in the catalog contain the link, catalog.

Click the catalog link to view the line item in the catalog.

Permissions to use this Feature

IMPORT_MARC - Using batch importer to create new bib records requires the IMPORT_MARC permission (same as open-ils.cat.biblio.record.xml.import). If the permission fails, the queued record will fail import and be stamped with a new "import.record.perm_failure" import error

IMPORT_ACQ_LINEITEM_BIB_RECORD_UPLOAD - This allows interfaces leveraging the batch importer, such as Acquisitions, to create a higher barrier to entry. This permission prevents users from creating new bib records directly from the ACQ vendor MARC file upload interface.

Chapter 85. Placing purchase requests from a patron record

Patrons may wish to suggest titles for your Library to purchase. You can track these requests within Evergreen, whether or not you are using the acquisitions module for other purposes. This section describes how you can record these requests within a patron’s record.

Retrieve the patron’s record.

Select Other -→ Acquisition Requests. This takes you to the Requests Screen.

The Requests Screen will show any other requests that this patron has made. You may sort the requests by clicking on the column headers.

To add the request, click the Create Request button.

You will need the CREATE_PURCHASE_REQUEST permission to add a request.

The request type field is required. Every other field is optional, although it is recommended that you enter as much information about the request as possible.

The Pickup Library, User, and Request Date/Time field will be filled in automatically.

You have the option to automatically place a hold for the patron if your library decides to purchase the item. If you’d like Evergreen to generate this hold, check the Place Hold box.

When you have finished entering information about the request, click the Save button.

Chapter 86. Managing patron purchase requests

Patrons may wish to suggest titles for your Library to purchase. You can track these requests within Evergreen, whether or not you are using the acquisitions module for other purposes. This section describes how you can manage these requests.

Go to Acquisitions → Patron Requests.

The Requests Screen will show any other requests that patrons have made. You may sort the requests by clicking on the column headers.

You can filter this screen by organizational unit or patron’s barcode. There are additional filter options available if you click on Filter.

To remove a user filter, click on User and leave the barcode field blank.

86.1. Adding a request

You may add a patron purchase request using this screen.

To add the request, click the Create Request button.

You will need the CREATE_PURCHASE_REQUEST permission to add a request.

If you have not already filtered the search using a patron’s barcode, you will be prompted to enter it before starting the request.

The request type field is required. Every other field is optional, although it is recommended that you enter as much information about the request as possible.

The Pickup Library, User, and Request Date/Time field will be filled in automatically.

You have the option to automatically place a hold for the patron if your library decides to purchase the item. If you’d like Evergreen to generate this hold, check the Place Hold box.

When you have finished entering information about the request, click the Save button.

86.2. Adding requests to selection lists

If you’d like to purchase a patron’s request, follow these steps:

Click on the blue hyperlinked title of the patron’s request.

Click the Add to Selection List button.

Fill out the requested information. You can either add it to an existing selection list or a new one.

After you save the record, the request’s Add to Selection List button will change to a View Selection List button that allows you to view the status of this patron request at a later time.

You can then use your Library’s typical ordering process to purchase the item your patron has requested.

Chapter 87. "Blanket" Orders

"Blanket" orders allow staff to invoice an encumbered amount multiple times, paying off the charge over a period of time. The work flow supported by this development assumes staff does not need to track the individual contents of the order, only the amounts encumbered and invoiced in bulk.

87.1. Example

Staff creates PO with a Direct Charge of "Popular Fiction 2015" and a charge type of "Blanket Order".

The amount entered for the charge equals the total amount expected to be charged over the duration of the order.

When a shipment of "Popular Fiction" items arrive, staff creates an invoice from the "Popular Fiction 2015" PO page and enters the amount billed/paid for the received shipment under the "Popular Fiction 2015" charge in the invoice.

When the final shipment arrives, staff select the Final invoice for Blanket Order option on the invoice screen to mark the PO as received and drop any remaining encumbrances to $0.

Alternatively, if the PO needs to be finalized without creating a final invoice, staff can use the new Finalize Blanket Order option on the PO page.

87.2. More details about blanket orders

Any direct charge using a blanket item type will create a long-lived charge that can be invoiced multiple times.

Such a charge is considered open until its purchase order is "finalized" (received).

"Finalizing" a PO changes the PO’s state to received (assuming there are no pending lineitems on the PO) and fully dis-encumbers all blanket charges on the PO by setting the fund_debit amount to $0 on the original fund_debit for the charge.

Invoicing a blanket charge does the following under the covers:

Create an invoice_item to track the payment

Create a new fund_debit to implement the payment whose amount matches the invoiced amount.

Subtract the invoiced amount from the fund_debit linked to the original blanket po_item, thus reducing the amount encumbered on the charge as a whole by the invoiced amount.

A PO can have multiple blanket charges. E.g. you could have a blanket order for "Popular Fiction 2015" and a second charge for "Pop Fiction 2015 Taxes" to track / pay taxes over time on a blanket charge.

A PO can have a mix of lineitems, non-blanket charges, and blanket charges.

A blanket Invoice Item Type cannot also be a prorate type, since it’s nonsensical. Blanket items are encumbered, whereas prorated items are only paid at invoice time and never encumbered.

Part IX. Cataloging

Chapter 88. Cataloging in the Web Client

Cataloguers should use this part for understanding the cataloguing procedures used in Evergreen.

88.1. MARC Tag-table Service

The tag tables for the web staff client MARC editor are now stored in the database rather than a separate XML tooltips file as used by the XUL MARC editor. The tag-table service, which is part of the web staff client sprint 2 preview in this release, has the following features:

specifies whether (sub)fields are optional or mandatory

specifies whether (sub)fields are repeatable or not

a coded value map can be associated with a subfield to establish a controlled vocabulary for that subfield

MARC field and subfield definitions can be overridden by institutions further down in the organizational unit hierarchy. This allows, for example, a library to specify definitions for local MARC tags.

values supplied by the tag-table service are used to populate values in context menus in the web staff client MARC editor.

The initial seed data for the in-database tag table is derived from the current tooltips XML file.

Chapter 89. Copy Buckets

Copy buckets are containers copy records can be put into to easily perform batch actions on. Copies stay in buckets until they are removed.

The Copy Bucket interface is accessed by going to Cataloguing → Copy Buckets.

The words copy and item are used interchangeably in Evergreen.

89.1. Managing Copy Buckets

89.1.1. Creating Copy Buckets

Copy buckets can be created in the Copy Bucket interface as well as on the fly when adding copies to a bucket from a catalogue search or from within the Item Status interface. For information on creating buckets on the fly see Adding Copies to a Bucket (needs section ID).

In the Copy Bucket interface on the click Buckets in either the Pending Copies or Bucket View tab.

From the drop down menu select New Bucket.

Enter a Name and a Description (optional) for your bucket and click Create Bucket.

The bucket can also be set as Publicly Visible at this time.

The functionality for making buckets publicly visible does not appear to be in place at this time.

89.1.2. Editing Copy Buckets

In the Copy Bucket interface click Buckets in either the Pending Copies or Bucket View tab.

From the drop down menu select the bucket you would like to edit. The bucket will load in the interface.

Click on Buckets.

From the drop down menu select Edit Bucket.

Update the desired information and click Apply Changes.

The functionality for making buckets publicly visible does not appear to be in place at this time.

89.1.3. Sharing Copy Buckets

89.1.3.1. Finding the Bucket ID

With the bucket open, look at the URL for the bucket ID. Share this ID with the staff member who needs access to this bucket.

89.1.3.2. Opening a Shared Bucket

In the Copy Bucket interface click Buckets in either the Pending Copies or Bucket View tab.

From the drop down menu select Shared Bucket.

Enter the bucket ID and click Load Bucket.

The shared bucket will display and can be worked with the same as any bucket you own.

89.1.4. Deleting Copy Buckets

In the Copy Bucket interface click Buckets in either the Pending Copies or Bucket View tab.

From the drop down menu select the bucket you would like to delete. The bucket will load in the interface.

Click on Buckets.

From the drop down menu select Delete Bucket.

On the confirmation pop up click Delete Bucket.

Refresh your screen.

89.2. Adding Copies to a Bucket

89.2.1. From the Copy Bucket Interface

In the Copy Bucket interface click on the Pending Copies tab.

Scan in all of the items you wish to add to the bucket.

Click on Buckets.

From the drop down menu select the bucket you wish to add the items to. Alternatively you can create a New Bucket (link back to Copy Bucket Interface section of Creating Copy Buckets).

Use the check boxes to select the item(s) you wish to add to the bucket.

Click Actions.

From the drop down menu select Add To Bucket.

The number of items in the bucket, displayed beside the bucket name, will update as will the number on the Bucket View tab.

Once you have added your selected items to a bucket you can deselect them, select other items on your pending list, and add those items to a different bucket.

89.2.2. From a Catalogue Search

Retrieve the title through a catalogue search.

If it is not your default view click on the Holdings View tab.

Use the check boxes to select the item(s) you would like to add to the bucket.

Click Actions.

From the drop down menu select Add Items to Bucket

Enter a name for your bucket or select an existing from the drop down menu.

Click Add To New Bucket or Add To Selected Bucket.

Repeat steps 1 through 7 to add additional copies.

89.2.3. From the Item Status Interface

Functionality currently missing.

89.3. Removing Copies from a Bucket

Open the Copy Bucket interface. By default you are on the Bucket View tab.

Click on Buckets.

From the drop down menu select the bucket containing the item(s) you would like to remove.

Use the check boxes to select the item(s) you wish to remove from the bucket.

Click Actions.

From the drop down menu select Remove Selected Copies from Bucket.

Your bucket will reload and the selected item(s) will no longer be in the bucket.

89.4. Editing Copies in a Bucket

Open the Copy Bucket interface. By default you are on the Bucket View tab.

Click on Buckets.

From the drop down menu select the bucket containing the item(s) you would like to edit.

Use the check boxes to select the item(s) you wish to edit.

Click Actions.

From the drop down menu select Edit Selected Copies.

The Copy Editor will open in a new tab. Make your edits and then click Save and Exit.

Your items have been updated.

89.5. Deleting Copies from the Catalogue

Open the Copy Bucket interface. By default you are on the Bucket View tab.

Click on Buckets.

From the drop down menu select the bucket containing the item(s) you would like to delete from the catalogue.

Use the check boxes to select the item(s) you wish to delete.

Click Actions.

From the drop down menu select Delete Selected Copies from Catalog.

On the confirmation pop up click OK/Continue.

The items have been deleted from the catalogue.

89.6. Placing Holds on Copies in a Bucket

Open the Copy Bucket interface. By default you are on the Bucket View tab.

Click on Buckets.

From the drop down menu select the bucket containing the item(s) you would like to place a hold on.

Use the check boxes to select the item(s) you wish to delete.

Click Actions.

From the drop down menu select Request Seleted Copies.

Enter the barcode for the patron who the hold is for. By default the system enters the barcode of the account logged into the client.

Select the correct Pickup Library.

Select the correct Hold Type. (More explanation of the hold types needed here.)

Click OK.

The hold has been placed.

89.7. Transferring Copies to Volumes

Retrieve the title through a catalogue search.

If it is not your default view click on the Holdings View tab.

Use the check boxes to select the volume you would like to transfer the item(s) to.

Click Actions.

From the drop down menu select Volume as Item Transfer Destination

Open the Copy Bucket interface. By default you are on the Bucket View tab.

Click on Buckets.

From the drop down menu select the bucket containing the item(s) you would like to transfer to the volume.

Use the check boxes to select the item(s) you wish to transfer.

Click Actions.

From the drop down menu select Transfer Selected Copies to Marked Volume.

The item(s) is transferred.

Chapter 90. Working with the MARC Editor

You can use the MARC Editor to edit MARC fields, sub-fields, and indicators.

90.1. Editing MARC Records

Retrieve the record.

MARC Edit.

The MARC record will display.

Select viewing and editing options, if desired.

Stack subfields to display each subfield on its own line.

Flat-Text Editor switches to a plain-text (menmonic) MARC format. This format can be useful when copying and pasting multiple lines. It also allows the use of tools like MarcEdit (http://marcedit.reeset.net/ ). Unclick the box to switch back.

Note that you can use a backslash character as a placeholder in the flat text editor’s indicators and fixed-length fields.

Add Item allows attaching items quickly with call number and barcode. When Save is clicked, the copy editor will open. NOTE: Browser pop-up blockers will prevent this, please allow pop-ups.

Make changes as desired.

Right click into a tag field to add/remove rows or replace tags.

To work with the data in a tag or indicator, click or Tab into the required field. Right click to view valid tags or indicators.

You can navigate the MARC Editor using keyboard shortcuts. Click Help to see the shortcut menu from within the MARC Editor.

When finished, click Save. The record will remain open in the editor. You can close the browser window or browser tab. Or you can switch to another view from the navigation near the top (for example to view it as it appears in the OPAC choose OPAC View).

90.1.1. MARC Record Leader and MARC fixed field 008

You can edit parts of the leader and the 008 field in the MARC Editor via the fixed field editor box displayed above the MARC record.

90.1.1.1. To edit the MARC record leader

Retrieve and display the appropriate record in MARC Edit view.

Click into any box displayed in the fixed field editor.

Press Tab or use the mouse to move between fields.

Click Save.

The OPAC icon for the appropriate material type will display.

OPAC icons for text, moving pictures and sound rely on correct MARC coding in the leader, 007, and 008, as do OPAC search filters such as publication date, item type, or target audience.

90.1.1.2. MARC Fixed Field Editor Right-Click Context Menu Options

The MARC Fixed Field Editor provides suggested values for select fixed fields based on the record type being edited. Users can right-click on the value control for a fixed field and choose the appropriate value from the menu options. The Evergreen database contains information from the Library of Congress’s MARC 21 format standards that includes possible values for select fixed fields. The right-click context menu options are available for fixed fields whose values are already stored in the database. Fixed fields that do not contain possible values in the database, the user will recieve the default web browser menu (such as cut, copy, paste, etc.).

To Access the MARC Fixed Field Editor Right-Click Context Menu Options:

Within the bibliographic record that needs to be edited, select MARC Edit.

Make sure that the Flat-Text Editor checkbox is not selected and that you are not using the Flat-Text Editor interface.

Right-click on the value control for the fixed field that needs to be edited.

Select the appropriate value for the fixed field from the menu options.

Continue editing the MARC record, as needed. Once you are finished editing the record, click Save.

Changing the values in the fixed fields will also update the appropriate position in the Leader or 008 Field and other applicable fields (such as the 006 Field).

MARC Editor users retain the option of leaving the fixed field value blank or entering special values (such as # or | ).

It may be necessary for MARC Editor users to first correctly pad the fixed fields to their appropriate lengths before making further modifications to the fixed field values.

Administration The Evergreen database already contains information from the Library of Congress’s MARC 21 format standards that includes possible values for select fixed fields. Users may also add values to these and other fixed fields through the MARC Coded Value Maps interface. Once new values are added, the right-click context menu for the selected fixed field will display those values in the MARC Editor for any Record Type that utilizes that fixed field. There are three relevant tables that contain the values that display in the fixed field context menu options:

config.marc21_ff_pos_map describes, for the given record type, where a fixed field is located, its start position, and its length.

config.coded_value_map defines the set of valid values for many of the fixed fields and the translatable, human-friendly labels for them.

config.record_attr_definition links together the information from the config.marc21_ff_pos_map and config.coded_value_map tables.

90.1.2. MARC 007 Field Physical Characteristics Wizard

The MARC 007 Field Physical Characteristics Wizard enables catalogers to interact with a database wizard that leads the user step-by-step through the MARC 007 field positions. The wizard displays the significance of the current position and provides dropdown lists of possible values for the various components of the MARC 007 field in a more user-friendly way.

To Access the MARC 007 Field Physical Characteristics Wizard for a Record that Does Not Already Contain the 007 Field (i.e. Creating the 007 Field from Scratch):

Within the bibliographic record that needs to be edited, select MARC Edit.

Make sure that the Flat-Text Editor checkbox is not selected and that you are not using the Flat-Text Editor interface.

Right-click in the MARC field column.

Click Add/Replace 007. The 007 row will appear in the record.

Click the chain link icon to the right of the field.

Click Physical Characteristics Wizard.

The MARC 007 Field Physical Characteristics Wizard will open.

Using the Physical Characteristics Wizard:

As the user navigates through the wizard, each position will display its corresponding label that describes the significance of that position. Each position contains a selection of dropdown choices that list the possible values for that particular position. When the user makes a selection from the dropdown options, the value for that position will also change.

The first value defines the Category of Material. Users select the Category of Material for the given record by choosing an option from the Category of Material? dropdown menu. The choices within the remaining character positions will be appropriate for the Category of Material selected.

Once the Category of Material is selected, click Next.

Evergreen will display the result of each selection in the preview above. The affected character will be in red.

By clicking either the Previous or Next buttons, the user may step forward and backward, as needed, through the various positions in the 007 field.

Once the user enters all of the applicable values for the 007 field and is ready to exit the wizard, click Save.

All of the values selected will be stored and displayed within the 007 field of the bibliographic record.

Continue editing the MARC record, as needed. Once the user is finished editing the record, click Save.

Administration

The information driving the MARC 007 Field Physical Characteristics Wizard is already a part of the Evergreen database. This data can be customized by individual sites and / or updated when the Library of Congress dictates new values or positions in the 007 field. There are three relevant tables where the information that drives the wizard is stored:

config.marc21_physical_characteristic_type_map contains the list of materials, or values, for the positions of the 007 field.

config.marc21_physical_characteristic_subfield_map contains rows that list the meaning of the various positions in the 007 field for each Category of Material.

config.marc21_physical_characteristic_value_map lists all of the values possible for all of the positions in the config.marc21_physical_characteristic_subfield_map table.

Chapter 91. Batch Importing MARC Records

The cataloging module includes an enhanced MARC Batch Import interface for loading MARC (and MARCXML) records. In general, it can handle batches up to 5,000 records without a problem. This interface allows you to specify match points between incoming and existing records, to specify MARC fields that should be overlaid or preserved, and to only overlay records if the incoming record is of higher quality than the existing record. Records are added to a queue where you can apply filters that enable you to generate any errors that may have occurred during import. You can print, email or export your queue as a CSV file.

91.1. Permissions

To use match sets to import records, you will need the following permission:

ADMIN_IMPORT_MATCH_SET

91.2. Record Display Attributes

This feature enables you to specify the tags and subfields that will display in records that appear in the import queue.

91.3. Record Match Sets

This feature enables you to create custom match points that you can use to accurately match incoming records with existing catalog records.

91.3.1. Creating a Match Set

In this example, to demonstrate matching on record attributes and MARC tags and subfields, we will create a record match set that defines a match based on the title of the record, in either the 240 or 245, and the fixed field, Lang. You can add multiple record attributes and MARC tags to customize a record match set.

Click Cataloging → MARC Batch Import/Export.

Create a new record match set. Click Record Match Sets → New Match Set.

Enter a name for the record match set.

Select an Owning Library from the drop down menu. Staff with permissions at this location will be able to use this record match set.

Select a Match Set Type from the drop down menu. You can create a match set for authority records or bibliographic records.

Click Save.

The screen will refresh to list the record match set that you created. Click the link to the record match set.

Create an expression that will define the match points for the incoming record. You can choose from two areas to create a match: Record Attribute or MARC Tag and Subfield. You can use the Boolean operators AND and OR to combine these elements to create a match set.

Select a Record Attribute from the drop-down menu.

Enter a Match Score. The Match Score indicates the relative importance of that match point as Evergreen evaluates an incoming record against an existing record. You can enter any integer into this field. The number that you enter is only important as it relates to other match points. Recommended practice is that you create a match score of one (1) for the least important match point and assign increasing match points to the power of 2 to working points in increasing importance.

Check the Negate? box if you want to negate the match point. Checking this box would be the equivalent of applying a Boolean operator of NOT to the match point.

Click Ok.

Drag the completed match point under the folder with the appropriately-named Boolean folder under the Expression tree.

The match point will nest underneath the folder in the Expression tree.

Enter another Boolean Operator to further refine your match set.

Click Boolean Operator.

Select the OR operator from the drop down menu.

Click Ok.

Drag the operator to the expression tree.

Click MARC Tag and Subfield.

Enter a MARC tag on which you want the records to match.

Enter a subfield on which you want the records to match.

Enter a Match Score. The Match Score indicates the relative importance of that match point as Evergreen evaluates an incoming record against an existing record. You can enter any integer into this field. The number that you enter is only important as it relates to other match points. Recommended practice is that you create a match score of one (1) for the least important match point and assign increasing match points to the power of 2 to working points in increasing importance.

Check the Negate? box if you want to negate the match point. Checking this box would be the equivalent of applying a Boolean operator of NOT to the match point.

Click Ok.

Drag the completed match point under the folder with the appropriately-named Boolean folder under the Expression tree. The Expression will build across the top of the screen.

Add additional MARC tags or record attributes to build the expression tree.

Click Save Changes to Expression.

91.3.2. Replace Mode

Replace Mode enables you to replace an existing part of the expression tree with a new record attribute, MARC tag, or Boolean operator. For example, if the top of the tree is AND, in replace mode, you could change that to an OR.

Create a working match point.

Click Enter replace mode.

Highlight the piece of the tree that you want to replace.

Drag the replacement piece over the highlighted piece.

Click Exit Replace Mode.

91.3.3. Quality Metrics

Set the Quality Metrics for this Match Set. Quality metrics are used to determine the overall quality of a record. Each metric is given a weight and the total quality value for a record is equal to the sum of all metrics that apply to that record. For example, a record that has been cataloged thoroughly and contains accurate data would be more valuable than one of poor quality. You may want to ensure that the incoming record is of the same or better quality than the record that currently exists in your catalog; otherwise, you may want the match to fail. The quality metric is optional.

You can create quality metrics based on the record attribute or the MARC Tag and Subfield.

Click Record Attribute.

Select an attribute from the drop down menu.

Enter a value for the attribute.

Enter a match score. You can enter any integer into this field. The number that you enter is only important as it relates to other quality values for the current configuration. Higher scores would indicate increasing quality of incoming records. You can, as in the expression match score, increase the quality points by increasing subsequent records by a power of 2 (two).

Click Ok.

91.4. Merge/Overlay Profiles

If Evergreen finds a match for an incoming record in the database, you need to identify which fields should be replaced, which should be preserved, and which should be added to the record. Click the Merge/Overlay Profiles button to create a profile that contains this information.

You can use these profiles when importing records through the MARC Batch Importer or Acquisitions Load MARC Order Records interface.

You can create a new profile by clicking the New Merge Profile button. Available options for handling the fields include:

Preserve specification - fields in the existing record that should be preserved.

Replace specification - fields in existing record that should be replaced by those in the incoming record.

Add specification - fields from incoming record that should be added to existing record (in addition to any already there.)

Remove specification - fields that should be removed from incoming record.

Update bib source - If this value is false, just the bibliographic data will be updated when you overlay a new MARC record. If it is true, then Evergreen will also update the record’s bib source to the one you select on import; the last edit date to the date the new record is imported, and the last editor to the person who imported the new record.

You can add multiple tags to the specification options, separating each tag with a comma.

91.5. Import Item Attributes

If you are importing copies with your records, you will need to map the data in your holdings tag to fields in the copy record. Click the Holdings Import Profile button to map this information.

Click the New Definition button to create a new mapping for the holdings tag.

Add a Name for the definition.

Use the Tag field to identify the MARC tag that contains your holdings information.

Add the subfields that contain specific copy information to the appropriate copy field.

At a minimum, you should add the subfields that identify the Circulating Library, the Owning Library, the Call Number and the Barcode.

All fields (except for Name and Tag) can contain static values, a MARC subfield code (such as "a"), or an XPATH query.

Table 91.1. Holdings Import Profile Fields

Field
Recommended
Description

Name

Yes

Name you will choose from the MARC Batch Import screen

Tag

Yes

MARC Holdings Tag/Field (e.g. 949). Use the Tag field to identify the MARC tag that contains your holdings information. tag in the record after it is imported. Otherwise, Evergreen will remove this holdings tag.

Barcode

Yes

Call Number

Yes

Circulating Library

Yes

Owning Library

Yes

Alert Message

Circulate

Circulate As MARC Type

Circulation Modifier

Copy Number

Deposit

Deposit Amount

Holdable

OPAC Visible

Overlay Match ID

The copy ID of an existing copy to overlay

Price

Private Note

Public Note

Reference

Shelving Location

Stat Cat Data

Of the format CATEGORY 1|VALUE 1||CATEGORY 2|VALUE 2. If you are overlaying existing copies which already have stat cats attached to them, the overlay process will keep those values unless the incoming copies contain updated values for matching categories.

Status

91.6. Import Records

The Import Records interface incorporates record match sets, quality metrics, more merging options, and improved ways to manage your queue. In this example, we will import a batch of records. One of the records in the queue will contain a matching record in the catalog that is of lower quality than the incoming record. We will import the record according to the guidelines set by our record match set, quality metrics, and merge/overlay choices that we will select.

Select a Record Type from the drop down menu.

Create a queue to which you can upload your records, or add you records to an existing queue. Queues are linked to match sets and a holdings import profile. You cannot change a holdings import or record match set for a queue.

Select a Record Match Set from the drop down menu.

Select a Holdings Import Profile if you want to import holdings that are attached to your records.

Select a Record Source from the drop down menu.

Select a Merge Profile. Merge profiles enable you to specify which tags should be removed or preserved in incoming records.

Choose one of the following import options if you want to auto-import records:

Merge on Single Match - Using the Record Match Set, Evergreen will only attempt to perform the merge/overlay action if only one match was found in the catalog.

Merge on Best Match - If more than one match is found in the catalog for a given record, Evergreen will attempt to perform the merge/overlay action with the best match as defined by the match score and quality metric.

Quality ratio affects only the Merge on Single Match and Merge on Best Match options.

Enter a Best/Single Match Minimum Quality Ratio. Divide the incoming record quality score by the record quality score of the best match that might exist in the catalog. By default, Evergreen will assign any record a quality score of 1 (one). If you want to ensure that the inbound record is only imported when it has a higher quality than the best match, then you must enter a ratio that is higher than 1. For example, if you want the incoming record to have twice the quality of an existing record, then you should enter a 2 (two) in this field. If you want to bypass all quality restraints, enter a 0 (zero) in this field.

Select an Insufficient Quality Fall-Through Profile if desired. This field enables you to indicate that if the inbound record does not meet the configured quality standards, then you may still import the record using an alternate merge profile. This field is typically used for selecting a merge profile that allows the user to import holdings attached to a lower quality record without replacing the existing (target) record with the incoming record. This field is optional.

Under Copy Import Actions, choose Auto-overlay In-process Acquisitions Copies if you want to overlay temporary copies that were created by the Acquisitions module. The system will attempt to overlay copies that:

have associated lineitem details (that is, they were created by the acquisitions process),

that lineitem detail has the same owning_lib as the incoming copy’s owning_lib, and

the current copy associated with that lineitem detail is In process.

Browse to find the appropriate file, and click Upload. The file will be uploaded to a queue. The file can be in either MARC or MARCXML format.

The screen will display records that have been uploaded to your queue. Above the table there are three sections:

Queue Actions lists common actions for this queue. Export Non-Imported Records will export a MARC file of records that failed to import, allowing those records to be edited as needed and imported separately. (Those records can be viewed by clicking the Limit to Non-Imported Records filter.)

Queue Summary shows a brief summary of the records included in the queue.

Queue Filters provides options for limiting which records display in the table.

If Evergreen indicates that matching records exist, then click the Matches link to view the matching records. Check the box adjacent to the existing record that you want to merge with the incoming record.

Click Back to Import Queue.

Check the boxes of the records that you want to import, and click Import Selected Records, or click Import All Records.

A pop up window will offer you the same import choices that were present on the Import Records screen. You can choose one of the import options, or click Import.

The screen will refresh. The Queue Summary indicates that the record was imported. The Import Time column records the date that the record was imported. Also, the Imported As column should now display the database ID (also known as the bib record number) for the imported record.

You can confirm that the record was imported by using the value of the Imported As column by selecting the menu Cataloging → Retrieve title by database ID and using the supplied Imported As number. Alternatively, you can search the catalog to confirm that the record was imported.

91.7. Default Values for Item Import

Evergreen now supports additional functionality for importing items through Cataloging → MARC Batch Import/Export. When items are imported via a Holdings Import Profile in Cataloging → MARC Batch Import/Export, Evergreen will create an item-level record for each copy. If an item barcode, call number, copy location, or circulation modifier is not set in the embedded holdings, Evergreen will apply a default value based on the configured Library Settings. A default prefix can be applied to the auto-generated call numbers and item barcodes.

The following Library Settings can be configured to apply these default values to imported items:

Vandelay: Generate Default Barcodes —Auto-generate default item barcodes when no item barcode is present

Vandelay: Default Barcode Prefix —Apply this prefix to any auto-generated item barcodes

Vandelay: Generate Default Call Numbers —Auto-generate default item call numbers when no item call number is present

Vandelay: Default Call Number Prefix —Apply this prefix to any auto-generated item call numbers

Vandelay: Default Copy Location —Default copy location value for imported items

Vandelay: Default Circulation Modifier —Default circulation modifier value for imported items

Chapter 92. Overlay Existing Catalog Record via Z39.50 Import

This feature enables you to replace a catalog record with a record obtained through a Z39.50 search. No new permissions or administrative settings are needed to use this feature.

To Overlay an Existing Record via Z39.50 Import:

1) Click Cataloging → Import Record from Z39.50

2) Select at least one Service in addition to the Local Catalog in the Service and Credentials window in the top right panel.

3) Enter search terms in the Query window in the top left panel.

4) Click Search.

5) The results will appear in the lower window.

6) Select the record in the local catalog that you wish to overlay.

7) Click Mark Local Result as Overlay Target

8) A confirmation message appears. Click OK.

9) Select the record that you want to replace the existing catalog record.

10) Click Overlay.

11) The record that you selected will open in the MARC Editor. Make any desired changes to the record, and click Overlay Record.

12) The catalog record that you want to overlay will appear in a new window. Review the MARC record to verify that you are overlaying the correct catalog record.

13) If the correct record appears, click Overlay.

14) A confirmation message will appear to confirm that you have overlaid the record. Click Ok.

15) The screen will refresh in the OPAC View to show that the record has been overlaid.

Chapter 93. Z39.50 Search Enhancements

Abstract

In Evergreen version 2.5, you will be able to search multiple Z39.50 sources simultaneously from record buckets. Using this feature, you can match records from Z39.50 sources to catalog records in your bucket and import the Z39.50 records via Vandelay.

Administration

The following administrative interfaces will enable you to configure Z39.50 search parameters.

Z39.50 Index Field Maps

Click Admin → Server Administration → Z39.50 Index Field Maps to map bib record indexes (metabib fields and record attributes) in your catalog records to Z39.50 search attributes. Metabib fields are typically free form fields found in the body of a catalog record while record attributes typically have only one value and are often found in the leader.

You can map a metabib field or a record attribute to a Z39.50 attribute or a Z39.50 attribute type. To map a specific field in your catalog record to a specific field in a chosen Z39.50 source, you should map to a Z39.50 attribute. For example, if you want the Personal Author in your catalog record to map to the Author field when searching the Library of Congress, then you should do the following:

Click New or double-click to edit an existing map.

Select the Metabib Field from the drop down menu.

Select the appropriate source and field from the Z39.50 Attribute drop down menu.

Click Save.

Alternatively, if you want the Personal Author in your catalog record to map to the generic author field of any Z39.50 source, then you should do the following:

Click New or double-click to edit an existing map.

Select the Metabib Field from the drop down menu.

Select the appropriate heading from the Z39.50 Attribute Type drop down menu.

Click Save.

Z39.50 servers

Click Admin → Server Admin → Z39.50 Servers to input your Z39.50 server. Click the hyperlinked name of any server to view the Z39.50 search attribute types and settings. These settings describe how the search values (from a metabib field or record attribute) are translated into Z39.50 searches.

Apply Quality Sets to Z30.50 Sources

From this interface, you can rank the quality of incoming search results according to the match set that you have established and their Z39.50 point of origin. By applying a quality score, you tell Evergreen to merge the highest quality records into the catalog.

Click Cataloging → MARC Batch Import/Export.

Click Record Match Sets. Match Sets specify the MARC attributes, tags, and subfields that you want Evergreen to use to identify matches between catalog and incoming records.

Rank the quality of the records from Z39.50 sources by adding quality metrics for the match set. Click MARC Tag and Subfield, and enter the 901z tag and subfield, specify the Z39.50 source, and enter a quality metric. Source quality increases as the numeric quality increases.

Org Unit Settings

Org Unit settings can be set for your local branch, your system, or your consortium. To access these settings, click Admin → Local Administration → Library Settings Editor → Maximum Parallel Z39.50 Batch Searches.

Two new settings control the Z39.50 search enhancements.

Maximum Parallel Z39.50 Batch Searches - This setting enables you to set the maximum number of Z39.50 searches that can be in-flight at any given time when performing batch Z39.50 searches. The default value is five (5), which means that Evergreen will perform 5 searches at a given time regardless of the number of sources selected. The searches will be divided between the sources selected. Thus, if you maintain this default and perform a search using two Z39.50 sources, Evergreen will conduct five searches, shared between the two sources.

Maximum Z39.50 Batch Search Results - This setting enables you to set the maximum number of search results to retrieve and queue for each record + Z39 source during batch Z39.50 searches. The default value is five (5).

Matching Records in Buckets with Records from Z39.50 Sources

Add records to a bucket.

Click Bucket Actions → Locate Z39.50 Matches. A pop up window will appear.

Select a Z39.50 Server(s).

Select a Z39.50 Search Index(es). Note that selecting multiple checkboxes will AND the search indexes.

Select a Vandelay queue from the drop down menu to which you will add your results, or create a queue by typing its name in the empty field.

Select a Match Set. The Match Set is configured in Vandelay and, in this instance, will only be used to compare the Z39.50 results with the records in your bucket.

Click Perform Search.

Status information will appear, including the number of records in the bucket that were searched, the matches that were found, and the progress of the search. When the search is complete, click Open Queue.

The Vandelay Queue will display. Matching records are identified in the Matches column. From this interface, import records according to your normal procedure. It is suggested that to merge the incoming records with the catalog records, you should choose an option to import the records. Next, select either merge option from the drop down menu, click Merge on Best Match, and then click Import.

The records from the Z39.50 search will merge with the catalog records. NOTE: A new column has been added to this interface to identify the Z39.50 source. When records are imported to the Vandelay queue via a record bucket, Evergreen tags the Z39.50 source and enters the data into the $901z.

Chapter 94. Monograph Parts

Monograph Parts enables you to differentiate between parts of monographs or other multi-part items. This feature enables catalogers to describe items more precisely by labeling the parts of an item. For example, catalogers might identify the parts of a monograph or the discs of a DVD set. This feature also allows patrons more flexibility when placing holds on multi-part items. A patron could place a hold on a specific disc of a DVD set if they want to access a specific season or episode rather than an entire series.

Four new permissions are used by this functionality: CREATE_MONOGRAPH_PART, UPDATE_MONOGRAPH_PART, DELETE_MONOGRAPH_PART and MAP_MONOGRAPH_PART. These permissions should be assigned at the consortial level to those groups or users that will make use of the features described below.

94.1. Add a Monograph Part to an Existing Record

To add a monograph part to an existing record in the catalog:

Retrieve a record.

Click Actions for this Record → Manage Parts

Click New Monograph Part

Enter the label that you want to appear to the user in the catalog, and click Save. This will create a list of monograph parts from which you can choose when you create a volume and copy.

Add a volume and copy. To add a volume and copy to your workstation library, click the Add Volumes link in the Record Summary at the top of the bibliographic record, or click Actions for this Record → Add Volumes.

To add a volume and copy to your workstation library or other libraries, click Actions for this Record → Holdings Maintenance → Add Volumes.

The Unified Volume/Copy Creator opens. Enter the number of volumes that you want to add to the catalog and the volume description.

Enter the number of copies and barcode(s) of each item.

Select the part designation from the drop down menu adjacent to the barcode field.

Apply a template to the copies, or edit fields in the Copy Editor.

Click Create Volumes/Items.

The Holdings Maintenance screen will refresh to demonstrate the addition of the part information. These fields also appear in the OPAC View.

94.2. Monograph Part Merging

The monograph part list for a bibliographic record may, over time, diverge from the proscribed format, resulting in multiple labels for what are essentially the same item. For instance, Vol. 1 may have variants like V.1, Vol 1, or  Vol. 1 (leading space). Merging parts will allow cataloging staff to collapse the variants into one value.

In the Monograph Parts display:

Click the checkbox for all items you wish to merge including the one you wish to prevail when done.

Click on the “Merge Selected” button. A pop-up window will list the selected items in a monospaced font, with blanks represented by a middle-dot character for more visibility.

Click on the item you wish to prevail.

The undesired part labels will be deleted, and any copies that previously used those labels will now use the prevailing label

Chapter 95. Conjoined Items

Prior to Evergreen version 2.1, items could be attached to only one bibliographic record. The Conjoined Items feature in Evergreen 2.1 enables catalogers to link items to multiple bibliographic records. This feature will enable more precise cataloging. For example, catalogers will be able to indicate items that are printed back to back, are bilingual, are part of a bound volume, are part of a set, or are available as an e-reader pre-load. This feature will also help the user retrieve more relevant search results. For example, a librarian catalogs a multi-volume festschrift. She can create a bibliographic record for the festschrift and a record for each volume. She can link the items on each volume to the festschrift record so that a patron could search for a volume or the festschrift and retrieve information about both works.

In the example below, a librarian has created a bibliographic record for two bestselling items. These books are available as physical copies in the library, and they are available as e-reader downloads. The librarian will link the copy of the Kindle to the bibliographic records that are available on the e-reader.

95.1. Using the Conjoined Items Feature

The Conjoined Items feature was designed so that you can link items between bibliographic records when you have the item in hand, or when the item is not physically present. Both processes are described here. The steps are fewer if you have the item in hand, but both processes accomplish the same task. This document also demonstrates the process to edit or delete links between items and bibliographic records. Finally, the permission a cataloger needs to use this feature is listed.

Scenario 1: I want to link an item to another bibliographic record, but I do not have the item in hand

Retrieve the bibliographic record to which you would like to link an item.

Click Actions for this Record → Mark as Target for Conjoined Items.

A confirmation message will appear. Click OK.

In a new tab, retrieve the bibliographic record with the item that you want to link to the other record.

Click Actions for this Record → Holdings Maintenance.

Select the copy that you want to link to the other bibliographic record. Right-click, or click Actions for Selected Rows → Link as Conjoined Items to Previously Marked Bib Record.

The Manage Conjoined Items interface opens in a new tab. This interface enables you to confirm the success of the link, and to change the peer type if desired. The Result column indicates that you created a successful link between the item and the bib record.

The default peer type, Back-to-back, was set as the peer type for our item. To change a peer type after the link has been created, right-click or click Actions for Selected Items → Change Peer Type. A drop down menu will appear. Select the desired peer type, and click OK.

The Result column will indicate that the Peer Type [has been] Updated.

To confirm the link between the item and the desired bib record, reload the tab containing the bib record to which you linked the item. You should now see the copy linked in the copies table.

Scenario 2: I want to link an item to another bibliographic record, and I do have the item in hand

Retrieve the bibliographic record to which you would like to add the item.

Click Actions for this Record → Manage Conjoined Items.

A note in the bottom left corner of the screen will confirm that the record was targeted for linkage with conjoined items, and the Manage Conjoined Items screen will appear.

Select the peer type from the drop down menu, and scan in the barcode of the item that you want to link to this record.

Click Link to Bib (Submit).

The linked item will appear in the screen. The Result column indicates Success.

To confirm the linkage, click Actions for this Record → OPAC View.

When the bibliographic record appears, click Reload. Linked Titles will show the linked title and item.

Scenario 3: I want to edit or break the link between a copy and a bibliographic record

Retrieve the bibliographic record that has a copy linked to it.

Click Actions for this Record → Manage Conjoined Items.

Select the copy that you want to edit, and right-click or click Actions for Selected Items.

Make any changes, and click OK.

UPDATE_COPY - Link items to bibliographic records

Chapter 96. Cataloging Electronic Resources — Finding Them in Catalog Searches

There are two ways to make electronic resources visible in the catalog without adding copies to the record:

Adding a Located URI to the record

Attaching the record to a bib source that is transcendent

The Located URI approach is useful for Evergreen sites where libraries have access to different electronic resources. The transcendent bib source approach is useful if all libraries have access to the same electronic resources.

Another difference between the two approaches is that electronic resources with Located URI’s never appear in results where the search is limited to a specific copy location(s). In contrast, transcendent electronic resources will appear in results limited to any copy location.

96.1. Adding a Located URI to the Record

A Located URI allows you to add the short name for the owning library to the 856 field to indicate which organizational units should be able to find the resource. The owning organizational unit can be a branch, system, or consortium.

A global flag called When enabled, Located URIs will provide visibility behavior identical to copies will determine where these resources will appear in search results. This flag is available through Admin → Server Administration → Global Flags.

If the When enabled, Located URIs will provide visibility behavior identical to copies flag is set to False (default behavior):

When the user’s search scope is set at the owning organizational unit or to a child of the owning organizational unit, the record will appear in search results.

When a logged-in user’s preferred search library is set to the owning organizational unit or to a child of that owning organizational unit, the record will appear regardless of search scope.

If the When enabled, Located URIs will provide visibility behavior identical to copies flag is set to True:

When the user’s search scope is set at the owning organizational unit, at a child of the owning organizational unit, or at a parent of the owning organizational unit, the record will appear in search results.

When a logged-in user’s preferred search library is set to the owning organizational unit, to a child of the owning organizational unit, or to a parent (with the exception of the consortium) of the owning organizational unit, the record will appear regardless of search scope.

To add a located URI to the record:

Open the record in MARC Edit

Add a subfield 9 to the 856 field of the record and enter the short name of the organizational unit for the value. Make sure there is a 4 entered as the first indicator and a 0 entered as the second indicator. For example:

856 40 $u http://lwn.net $y Linux Weekly News $9 BR1

would make this item visible to people searching in a library scope of BR1 or to logged-in users who have set BR1 as their preferred search library.

If multiple organizational units own the resource, you can enter more than one subfield 9 to the 856 field or you can enter multiple 856 fields with a subfield 9 to the record

Save the record

96.1.1. Located URI Example 1

The When enabled, Located URIs will provide visibility behavior identical to copies flag is set to False (default behavior)

The Record has two 856 fields: one with SYS1 in subfield 9 and the other with BR4 in subfield 9

Any user searching SYS1 or any of its children (BR1, BR2, SL1) will find the record. These users will only see the URL belonging to SYS1.

Any user searching BR4 will find the record. These users will only see the URL belonging to BR4.

A user searching SYS2 will NOT find the record because SYS2 is a parent of an owning org unit, not a child. The same thing happens if the user is searching the consortium. In this case, the system assumes the user is unlikely to have access to this resource and therefore does not retrieve it.

A logged-in user with a preferred search library of BR4 will find the record at any search scope. This user will see the URL belonging to BR4. Because this user previously identified a preference for using this library, the system assumes the user is likely to have access to this resource.

A logged-in user with a preferred search library of BR4 who is searching SYS1 or any of its children will also retrieve the record. In this case, the user will see both URLs, the one belonging to SYS1 because the search library matches or is a child of the owning organizational unit and the one belonging to BR4 because it matches or is a child of the preferred search library. The URL belonging to the search library (if it is an exact match, not a child) will sort to the top.

96.1.2. Located URI Example 2

The When enabled, Located URIs will provide visibility behavior identical to copies flag is set to True

The Record has two 856 fields: one with SYS1 in subfield 9 and the other with BR4 in subfield 9

Any user searching SYS1 or any of its children (BR1, BR2, SL1) will find the record. These users will only see the URL belonging to SYS1.

Any user searching BR4 will find the record. These users will only see the URL belonging to BR4.

Any user searching the consortium will find the record. These users will see both URLs in the record. In this case, the system sees this user as a potential user of SYS2 or BR4 and therefore offers them the option of accessing the resource through either URL.

A user searching SYS2 will find the record because SYS2 is a parent of an owning org unit. The user will see the URL belonging to BR4. Once again, the system sees this user as a potential user of BR4 and therefore offers them the option of accessing this resource.

A user searching BR3 will NOT find the record because BR3 is neither a child nor a parent of an owning organizational unit.

A logged-in user with a preferred search library of BR4 who is searching BR3 will find the record. This user will see the URL belonging to BR4. Because this user previously identified a preference for using this library, the system assumes the user is likely to have access to this resource.

A logged-in user with a preferred search library of BR4 who is searching SYS1 or any of its children will also retrieve the record. In this case, the user will see both URLs, the one belonging to SYS1 because the search library matches or is a child of the owning organizational unit and the one belonging to BR4 because it matches or is a child of the preferred search library. The URL belonging to the search library (if it is an exact match, not a child) will sort to the top.

96.2. Using Transcendent Bib Sources for Electronic Resources

Connecting a bib record to a transcendent bib source will make the record visible in search results regardless of the user’s search scope.

To start, you need to create a transcendent bib source by adding it to config.bib_source in the Evergreen database and setting the transcendant field to true. For example:

# INSERT INTO config.bib_source(quality, source, transcendant, can_have_copies) VALUES (50, ‘ebooks’, TRUE, FALSE);

If you want to allow libraries to add copies to these records, set the can_have_copies field to TRUE. If you want to prevent libraries from adding copies to these records, set the can_have_copies field to FALSE.

When adding or uploading bib records for electronic resources, set the bibliographic source for the record to the newly-created transcendent bibliographic source. Using the staff client, the bibliographic source can be selected in the MARC Batch Import interface when importing new, non-matching records or in the MARC Edit interface when editing existing records.

Chapter 97. TPAC Copy Edit Links

The bibliographic record detail page displays library holdings, including the call number, shelving location, and copy barcode. Within the staff client, the holdings list now displays a new column next to the copy barcode(s). This new column contains two links, view and edit.

Clicking on the view link opens the Item Status screen for that specific copy.

Clicking on the edit link opens the Volume and Copy Creator screen for that specific copy.

The edit link will only be exposed next to copies when the user has the UPDATE_COPY permission at the copy owning or circulating library.

For libraries where the Library Setting: Unified Volume/Item Creator/Editor value is set to True, the unified Volume and Copy Creator screen will open.

For libraries where the Library Setting: Unified Volume/Item Creator/Editor value is set to False, the standard Volume and Copy Creator screen will open.

Chapter 98. MARC Batch Edit

This function is used to batch edit MARC records either adding a field, removing a field or changing the contents of a field.

Record Source

This includes options to batch edit identifying MARC records in a record bucket, CSV file or by record id.

Go! (button)

This button runs the action defined by the rule template(s).

98.1. Action (Rule Type)

Replace

Replaces the value in a MARC field for a batch of records.

Delete

Removes a MARC field and its contents from the batch of records.

Add

Use this to add a field and its contents to a batch of records.

98.2. Other Template Fields

MARC Tag

This is used to identify the field for adding, replacing, or deleting.

Subfield (optional)

Indicates which subfield is being edited.

MARC Data

Use this to indicate the data to add or used in replacing the existing data.

98.2.1. Advanced Matching Restrictions (Optional)

Subfield Regular Expression:: Using PERL syntax for a regular expression to identify the data to be removed or replaced.

Running a Template to Add, Delete, or Replace MARC data

Click Cataloging→MARC Batch Edit

Select Record source

Select the appropriate bucket, load the CSV file or enter record id depending on Record source selected

Select the Action Rule

Enter the MARC Tag with no indicators (eg. 245)

Enter the subfields with no spaces. Subfields are optional. Multiple subfield can be entered such as auz.

Enter the MARC Data which is the value in the fields

Enter optional Advanced Matching Restrictions

Subfield

Regular Expression (using PERL syntax)

Click Go!

Results page will display indicating the number of records successfully edited

Chapter 99. Managing Authorities

This section describes how you can create, import, view, modify, merge, and delete authority records in Evergreen.

99.1. Creating Authorities

Currently in Evergreen to create a new authority record, as opposed to importing an authority record, you need to have a bib record open in the bib MARC editor.

For example, if you want to create a new author authority you need to have a bib record that has a bib 1xx or 7xx tag with the main entry filled out.

Then you need to right click on that 1xx or 7xx tag. In the context menu that shows up, select Create New Authority from this field, then select either Create Immediately or Create and Edit….

If you choose Create and Edit…, after the authority MARC editor opens you need to click on the Save button to finally add the new authority record to your system.

99.2. Importing Authorities

Click Cataloging → MARC Batch Import/Export.

You may create a queue to better track this import project. If you do not create a new queue, it will automatically put your records into a default queue named -.

Don’t set a value for Holdings Import Profile, because this doesn’t apply to authority records.

Select a file of authority data and put it in the File to Upload field.

Make sure all the settings are correct, then press Upload.

The screen displays "Uploading… Processing…" to show that the records are being transferred to the server, then displays a progress bar to show the actual import progress. When the staff client displays the progress bar, you can disconnect your staff client safely. Very large batches of records might time out at this stage.

Evergreen will automatically assign a thesaurus based on the Subj fixed field, which is character 11 in the 008 field.

Evergreen will also try to determine who edited the record (based on the MARC 905u field or the user performing the import) and set the edit date, which you can view when you examine the record in the future.

Once the import is finished, the staff client displays the results of the import process. You can manually display the import progress by selecting the Inspect Queue tab of the MARC Batch Import/Export interface and selecting the queue name. By default, the staff client does not display records that were imported successfully; it only shows records that conflicted with existing entries in the database. The screen shows the overall status of the import process in the top right-hand corner, with the Total and Imported number of records for the queue.

If you are importing authorities from an external vendor and want to track this, you may wish to set a unique Record Source. This source will be visible in the MARC Editor and in the 901$s field of the imported authority records.

99.2.1. Setting up Authority Record Match Sets

Click Cataloging → MARC Batch Import/Export.

Click Record Match Sets.

If you have sufficient privileges, you will be able to click on the New Match Set. If you are unable to do so, check that you have the ADMIN_IMPORT_MATCH_SET permission.

Give your new set a descriptive name, an owning library, and a match set type of authority.

Click on the blue hyperlinked name of the match set you just created to add criteria.

You can match against MARC tag/subfield entries or against a record’s normalized heading.

Evergreen’s database stores normalized authority headings in a format that includes the thesaurus. This way, record match sets will not match terms from other thesauri, even if the term is very similar.

Evergreen’s internal identifier is in the 901c field. If you have previously exported authority record — perhaps for an external vendor to do authority cleanup work — and you want to import them back into your catalog, you may wish to include the 901c field in your match set.

99.3. Manage Authorities Interface

In Evergreen to view, edit, merge, and delete authority records you would use the Manage Authorities interface through the Cataloging menu.

99.3.1. Searching for authorities

To search for authorities in your system, first select the Cataloging menu and then select Manage Authorities. Then proceed to fill out the search form.

Type in your Search Term

Select an Authority type, types currently include: Author, Subject, Title, Topic

Click on the Submit button

The authority search results will include the following elements from left to right:

Actions menu, which can be used to select actions that affect the corresponding authority record. Actions include: Edit, Mark for Merge, Delete

Count of how many bibs are linked to the corresponding authority

Main entry of the authority, i.e the authority tag 1xx value

Control set value, with LoC being the default, but others can be added

Authority Subject heading system/thesaurus, for example a value of "a" means authority originated from the Library of Congress (http://www.loc.gov/marc/authority/ad008.html)

Library of Congress list of thesaurus values:

'' = Alternate no attempt to code

a = Library of Congress Subject Headings

b = LC subject headings for children’s literature

c = Medical Subject Headings

d = National Agricultural Library subject authority file

k = Canadian Subject Headings

n = Not applicable

r = Art and Architecture Thesaurus

s = Sears List of Subject Headings

v = Repertoire de vedettes-matiere

z = Other

| = No attempt to code

99.3.1.1. Editing authority records

Editing an authority record (or merging two authority records) can cause its linked bibliographic records to also update. For example, if you correct a spelling error in the 150 field of a subject authority record, the relevant 650 field in linked bibliographic records will also be updated to reflect the correct spelling.

When a bib record is automatically updated as a result of the modification of a linked authority record, the bib record’s "Last Edit Date/ Time" and "Last Editing User" fields will be updated to match the time of the update and the editory of the authority record. If you’d prefer that these fields not be automatically updated, you can set the ingest.disable_authority_auto_update_bib_meta setting to true in the Library Settings Editor.

Chapter 100. Link Checker

The Link Checker enables you to verify the validity of URLs stored in MARC records. The ability to verify URLs would benefit locations with large electronic resource collections.

100.1. Search for URLs

Search for MARC records that contain URLs that you want to verify.

Click Cataloging → Link Checker.

Click New Link Checker Session.

Create a session name. Note that each session must have a unique name.

Select a search scope from the drop down menu. Records that would be retrieved by searching Example Branch 1 (BR1) in an OPAC search would also be retrieved here. For example, a record that describes an electronic resource with a URL in the 856 $u and an org unit code, such as BR1, in the 856 $9, would be retrieved by a search of relevant keywords. Also, records that contain a URL without the $9 subfield, but also have physical copies at BR1, would be retrieved. Note that you can skip this step if you enter the org unit code of the location that you want to search in the Search field.

Enter search terms to retrieve records with URLs that you want to verify. You can also add a location filter, such as BR1.

You may further limit your search by selecting a saved search. Saved searches are filters made up of specific criteria, such as shelving location or audience. Adding a saved search to your keyword search will narrow your search for records with URLs. This step is optional.

Enter tags and subfields that contain URLs in the appropriate boxes. Click Add after you enter the data in the fields. You can add multiple tags and subfields by repeating this process. Evergreen will search for records that match your search terms, and then, from the set that it retrieves, it will extract any URLs from all of the tag/subfield locations you have specified for the session.

To view and manually verify the URLs that Evergreen retrieves, leave the Process Immediately button unchecked. If you want Evergreen to automatically verify the URLs that it retrieves, then check the box to Process Immediately.

Click Begin to process your search.

100.2. View Your Results

If you do not click Process Immediately, then you must select the links that you want to verify, and click Verify Selected URLs. If you click Process Immediately, then you skip this step, and Evergreen jumps directly to the results of the verification attempts as seen in the next step.

Evergreen displays the results of the verification attempts, including the tags that you searched, the URLs that Evergreen retrieved, the Bib Record ID, the request and result time, and the result code and text.

100.3. Manage Your Sessions

100.3.1. Edit Columns

You can use the Column Picker to add and remove columns on any of the Link Checker interfaces. To access the Column Picker, right click on any of the column headings. The columns are saved to your user account.

100.3.2. Clone Sessions

You can clone sessions that you run frequently or that have frequently-used parameters that need only minor adjustments to create new searches. To clone a session:

Click Cataloging → Link Checker.

In the Session ID column, click Clone. A copy of the parameters of that search will appear.

100.3.3. View Verification Attempts

To view the results of a verification attempt after you have closed the session, click Cataloging → Link Checker. Your link checker sessions appear in a list. To view the results of a session, click the Open link in the Session ID column.

Click Filter to refine the results on this page. To add a filter:

Select a column from the first drop down menu.

Select an operator from the second drop down menu.

A third field will appear. Enter the appropriate text.

Click Apply to apply the filter to your current results. Click Save Filters to save the filter to your user account for later use.

Part X. Serials

Chapter 101. Serials

This documentation is intended for users who will be ordering subscriptions, distributing issues, and receiving issues in Evergreen.

101.1. Serial Control View vs. Alternate Serial Control View

Serial Control View and Alternate Serial Control View offer you two views of Serials. Both views enable you to create subscriptions, add distributions, define captions, predict future issues, and receive items. Serial Control View was designed for users who work with a smaller number of issues and was designed to accommodate workflows in academic and special libraries. Alternate Serial Control View was designed for users who receive a larger number of issues and was designed for use in public libraries.

In version 2.4, the two interfaces have taken a big step toward unification. Now in the Serial Control View, within the Subscription editor, you will find an embedded version of the Alternate Serial Control View. This new unified interface tries to provide the best features of both views, giving full access to the Alternate view functions from within the tabbed Serial Control View. One exception is that you cannot predict new issues from within the embedded Alternate view; instead you should use the standard Serial Control View method of predicting issues, explained here. Also, some improvements were made to the embedded Alternate view to prevent losing features that were available in the old Serial Control View editors. These changes include: new "Edit Notes" buttons on the subscriptions and distributions editors; labeled dropdown for distribution summary options ("Add to record entry", "Use record entry only", etc.); new legacy record entry linkage (allows one to tie a distribution’s information to a particular serial record entry (i.e. a MFHD record)).

Outside of the Subscription Editor, the two views maintain their previous looks and usage. You are encouraged to use the new combination view and provide feedback to the Evergreen general discussion list.

The views are interoperable, but because they were designed for different purposes, some differences emerge. For example, Serial Control View enables you to create and edit serials in a single tabbed interface while Alternate Serial Control View leads you through a series of steps on multiple screens. In addition, receiving functions vary between views. Both receiving interfaces enable you to batch receive issues. However, the Serials Batch Receive interface, which is associated with Alternate Serial Control View, allows for more customization of each receiving unit while the Items tab in Serial Control View allows for greater flexibility in creating multi-issue units, such as in binding serials.

The new combination view tries to provide the best of both views in one place. Try it out and send your feedback to the Evergreen general discussion list.

Table 101.1. Serials Control View and Alternate Serials Control View Comparison

Function
Serials Control View
Alternate Serials Control View
Combination View

Menu Style

Menu driven

Wizard oriented

Both

Setting Up subscription

No calendar drop downs

Includes calendar drop down

Includes calendar drop down

Creating streams

No setup required

Requires streams

No setup required

Creating captions and patterns

Wizard available

Wizard available

Wizard available

Adding Starting Issue

Includes holdings code wizard

Includes holdings code wizard

Includes holdings code wizard

Generate Predictions

Make predictions

Generate predictions

Make predictions

Add items for special issue

No functionality

New items on issuances tab

New items on issuances tab

Receiving issues

Multiple modes in Items tab

Batch Receive

Both

101.2. MFHD Records

MARC Format for Holdings Display (MFHD) display in the OPAC in addition to holding statements generated by Evergreen from subscriptions created in the Serials Control View or the Alternate Serials Control View. The MFHDs are editable as MARC but the holdings statements generated from the control view are system generated. Multiple MFHDs can be created and are tied to Organizational Units.

Chapter 102. Copy Template for Serials

A copy template enables you to specify item attributes that should be applied by default to copies of serials. You can create one copy template and apply it to multiple serials. You can also create multiple copy templates. Templates will be used in the Alternate Serial Control View or the Serial Control View.

102.1. Create a copy template

To create a copy template, click Admin → Local Administration → Copy Template Editor.

Enter a Name for the template.

Select an owning library from the Owning Lib drop down menu. This organization owns the copy template. A staff member with permissions at that organization can modify the copy template. The menu is populated from the organizations that you created in Admin → Server Administration → Organizational Units.

Check Circulate? if you want the item to circulate.

Check Holdable? if patrons can place holds on the item.

Check OPAC Visible? if you want patrons to be able to see the item in the OPAC after you receive it.

Select a Loan Duration rule from the drop down menu. This field is required.

Select a Fine Level for the item from the drop down menu. This field is required.

Select a copy location from the Location drop down menu. The menu is populated from the copy locations that you created in Admin → Local Administration → Copy Locations.

Select a Circ Modifier from the drop down menu. The menu is populated from the modifiers that you created in Admin → Server Administration → Circulation Modifiers.

Select a Floating Group if the item is part of a floating collection. For more information, see the chapter on Floating Groups.

Check Deposit? if patrons must place a deposit on the copy before they can use it.

Check Reference? if the item is a reference item.

Check Mint Condition? if the item is in mint condition.

Enter age protection rules in the Age Protect field. Age protection allows you to control the extent to which an item can circulate after it has been received. For example, you may want to protect new copies of a serial so that only patrons who check out the item at your branch can use it.

Enter a message in the Alert Message field. This message will appear every time the item is checked out to a patron.

Enter a code from the MARC fixed fields into the Circ as Type field if you want to control the circulation based on the item type.

Enter a Deposit Amount if patrons must place a deposit on the copy before they can use it.

Enter the Price of the item.

Select a copy status from the Status drop down menu. The copy statuses can be managed in Admin → Server Administration → Copy Statuses.

Click Save.

102.2. Edit a copy template

You can make changes to an existing copy template. Changes that you make to a copy template will apply to any items that you receive after you edited the template.

Double-click the row you want to edit. The copy template will appear, and you can edit the fields.

After making changes, click Save.

From the copy template interface, you can delete copy templates that have never been used. First check the box for the template you wish to delete, then click Delete Selected.

Chapter 103. Serials Control View

As of Evergreen 2.4, the Serial Control View incorporates the Alternate Serial Control interface in the Subscription editor. Serial Control View enables you to manage serials in a single tabbed interface. This view also enables you to bind units. Serial Control View consists of five tabs: Items, Units, Distributions, Subscriptions, and Claims. Units and Claims are not functional in 2.4.

103.1. Create a Subscription

A subscription is designed to hold all information related to a single serial title. Therefore, each library is likely to have only one subscription per serial title.

Click the Subscriptions tab.

In the tree on the left, select the branch that will own the subscription.

Right-click to show the Actions menu, or click Actions for Selected Row, and click Add Subscription.

Enter the date that the subscription begins in the Start Date field.

Enter the date that the subscription ends in the End Date field. This field is optional.

Enter the difference between the nominal publishing date of an issue and the date that you expect to receive your copy in the Expected Date Offset field. For example, if an issue is published the first day of each month, but you receive the copy two days prior to the publication date, then enter -2 days into this field.

When finished, click Save. Or to exit the editor without saving, click Cancel.

You can add notes to the subscription by clicking View/Edit Notes. These notes can also be accessed from the Items tab by right-clicking on an item and choosing View Sub. Notes. Also, the Notes column in the Items tab displays the total notes of each kind (Item notes, then Distribution notes, then Subscription notes).

103.2. Create a Distribution

Distributions indicate the branches that should receive copies of a serial. Distributions work together with streams to indicate the number of copies that should be sent to each branch.

103.2.1. From the new combination Serial Control View

Choose a subscription from the list on the left

In the panel on the right, click the Distributions tab

Click the New Distribution button

Enter your desired label in the Label field. It may be useful to identify the branch to which you are distributing these issues in this field. This field is not publicly visible and only appears when an item is received. There are no limits on the number of characters that can be entered in this field.

Select a Holding Library from the drop down menu. The holding library is the branch that will receive the copies.

Select a Display Grouping

Choose a Legacy Record Entry to attach to this serial record. The Legacy Record Entry contains the MFHD records that are attached to the bib record if the owning library is identical to the distribution’s holding library. A distribution can thus be an extension of an MFHD record.

Select a copy template from the Receive Unit Template drop down menu. This menu is populated with the copy templates that you created in Copy Template Editor.

Select a Summary method. This determines how the Holdings Summary will treat the Legacy Record Entry (i.e. MFHD record) in relation to the Serial Control holdings data.

Add to record entry - Displays the MFHD holdings summary first, followed by the summary generated from the Serial Control received issues

Use record entry only - Displays only the MFHD holdings summary

Do not use record entry - Displays only the holdings summary generated from Serial Control received issues

Merge with record entry - Merges the two holdings summaries into a single statement

Enter a Unit label prefix. This information will display in Serial Control View when the items are received, but it does not print in the Spine Label printing interface.

Enter a Unit label suffix. This information will display in Serial Control View when the items are received, but it does not print in the Spine Label printing interface.

Click the Save button to finish.

Label, Holding Library, and Receive Unit Template are required fields when creating a distribution.

Streams are created automatically in the Serial Control View. For information on using Streams in the combination Serial Control View, see Creating a Stream.

103.2.2. From the original Serial Control View

Click Distributions beneath the subscription from the tree on the left. Right click to show the Actions menu, or click Actions for Selected Rows, and click Add distribution.

Apply a new label to the distribution. It may be useful to identify the branch to which you are distributing these issues in this field. This field is not publicly visible and only appears when an item is received. There are no limits on the number of characters that can be entered in this field.

Select a Summary method. This determines how the Holdings Summary will treat the Legacy Record Entry (i.e. MFHD record) in relation to the Serial Control holdings data.

Add to record entry - Displays the MFHD holdings summary first, followed by the summary generated from the Serial Control received issues

Use record entry only - Displays only the MFHD holdings summary

Do not use record entry - Displays only the holdings summary generated from Serial Control received issues

Merge with record entry - Merges the two holdings summaries into a single statement

Apply a prefix to the spine label if desired. This information will display in Serial Control View when the items are received, but it does not print in the Spine Label printing interface.

Apply a suffix to the spine label if desired. This information will display in Serial Control View when the items are received, but it does not print in the Spine Label printing interface.

The holding library is filled in by default and is the library to which you attached the subscription.

The Legacy Record Entry contains the MFHD records that are attached to the bib record if the owning library is identical to the distribution’s holding library. A distribution can thus be an extension of an MFHD record. Select the MFHD record from the drop down menu.

The Receive Call Number field is empty until you receive the first item. When you receive the first item, you are prompted to enter a call number. That call number will populate this drop down menu.

The Bind Call Number field is empty until you bind the first item. When you receive the first item, you are prompted to enter a call number. That call number will populate this drop down menu.

Receive Unit Template - The template that should be applied to copies when they are received. Select a template from the drop down menu.

Bind Unit Template - The template that should be applied to copies when they are bound. Select a template from the drop down menu.

When finished, click Create Distribution(s) in the bottom right corner of the screen.

A confirmation message appears. Click OK.

You can add notes to the distribution by clicking Distribution Notes. These notes can also be accessed from the Items tab by right-clicking on an item and choosing View Dist. Notes. Also, the Notes column in the Items tab displays the total notes of each kind (Item notes, then Distribution notes, then Subscription notes).

103.3. Create Captions and Patterns

103.3.1. From the new combination Serial Control View

The Captions and Patterns wizard allows you to enter caption and pattern data as it is described by the 853, 854, and 855 MARC tags. These tags allow you to define how issues will be captioned, and how often the library receives issues of the serial.

In the panel on the right, click the Captions and Patterns tab.

Click Add New.

In the Type drop down menu, select the MARC tag to which you would like to add data.

In the Pattern Code text box, you can enter a JSON representation of the 85X tag by hand, or you can click the Wizard to enter the information in a user-friendly format.

The Caption and Pattern is Active by default. You can deactivate it at any time by unchecking the box and clicking Save Changes. Only one active caption and pattern is allowed per type.

Click Save Changes to finish.

To delete a pattern, simply click the red X button.

103.3.2. From the original Serial Control View

Click Captions and patterns beneath the subscription from the tree on the left. Right click to the show the Actions menu, or click Actions for Selected Rows, and click Add Caption/Pattern.

Apply a type, which can be for basic subscription, supplements, or indices

Apply active. Only one active caption and pattern is allowed per type

In the Pattern Code box, you can enter a JSON representation of the 85X tag by hand, or you can click the Pattern Code Wizard to enter the information in a user-friendly format.

103.3.3. Use the Pattern Code Wizard

The Pattern Code Wizard enables you to create the caption of the item and add its publication information. The Wizard is composed of five pages of questions. You can use the Next and Previous navigation buttons in the top corners to flip between pages.

To add a pattern code, click Wizard.

103.3.3.1. Page 1: Enumerations

To add an enumeration, check the box adjacent to Use enumerations.. The enumerations conform to $a-$h of the 853,854, and 855 MARC tags.

A field for the First level will appear. Enter the enumeration for the first level. A common first level enumeration is volume, or "v."

Click Add Enumeration.

A field for the Second level will appear. Enter the enumeration for the second level. A common first level enumeration is number, or "no."

Enter the number of bibliographic units per next higher level. This conforms to $u in the 853, 854, and 855 MARC tags.

Choose the enumeration scheme from the drop down menu. This conforms to $v in the 853, 854, and 855 MARC tags.

You can add up to six levels of enumeration.

Add Alternate Enumeration if desired.

When you have completed the enumerations, click Next.

103.3.3.2. Page 2: Calendar

To use months, seasons, or dates in your caption, check the box adjacent to Use calendar changes.

Identify the point in the year at which the highest level enumeration caption changes.

In the Type drop down menu, select the points during the year at which you want the calendar to restart.

In the Point drop down menu, select the specific time at which you would like to change the calendar

To add another calendar change, click Add Calendar Change. There are no limits on the number of calendar changes that you can add.

When you have finished the calendar changes, click Next.

103.3.3.3. Page 3: Chronology

To add chronological units to the captions, check the box adjacent to Use chronology captions.

Choose a chronology for the first level. If you want to display the terms such as "year" and "month" next to the chronology caption in the catalog, then check the box beneath Display in holding field.

To include additional levels of chronology, click Add Chronology Caption. Each level that you add must be smaller than the previous level.

After you have completed the chronology caption, click Next.

103.3.3.4. Page 4: Compress and Expand Captions

Select the appropriate option for compressing or expanding your captions in the catalog from the compressibility and expandability drop down menu. The entries in the drop down menu correspond to the indicator codes and the subfield $w in the 853 tag. Compressibility and expandability correspond to the first indicator in the 853 tag.

Choose the appropriate caption evaluation from the drop down menu.

Choose the frequency of your publication from the drop down menu. For irregular frequencies, you may wish to select use number of issues per year, and enter the total number of issues that you receive each year. However, recommended practice is that you use only regular frequencies. Planned development will create an additional step to aid in the creation of irregular frequencies.

Click Next.

103.3.3.5. Page 5: Regularity Information

If needed, check box for Use specific regularity information

Choose the appropriate information for combined, omitted or published issues

Choose the appropriate frequency and issue

Add additional rows as required

103.3.3.6. Page 5: Finish Captions and Patterns

To complete the wizard, click Create Pattern Code.

Return to Subscription Details.

Confirm that the box adjacent to Active is checked. Click Save Changes. The row is now highlighted gray instead of orange.

103.4. Creating an Issuance

The Issuances function enables you to manually create an issue. Evergreen will use the initial issue that you manually create to predict future issues.

103.4.1. From the new combination Serial Control View

In the panel on the right, click the Issuances tab.

Click New Issuance.

The Subscription, Creator, and Editor fields contain subscription and user IDs, respectively. These fields are disabled because Evergreen automatically fills in these fields.

Enter a name for this issuance in the Label field. There are no limits on the number of characters that can be entered in this field. You may want to enter the month and year of the publication in hand.

Enter the Date Published of the issuance. If you are creating one manual issue before automatically predicting more issues, then this date should be the date of the most current issue before the prediction starts.

Select a Caption/Pattern from the drop down menu. The numbers in the drop down menu correspond to the IDs of the caption/patterns that you created.

The Holding Type appears by default and corresponds to the Type that you selected when you created the Caption/Pattern.

In the holding code area of the New Issuance dialog, click Wizard. The Wizard enables you to add holdings information.

Enter the volume of the item in hand in the v. field.

Enter the number of the item in hand in the no. field.

Enter the year of publication in the Year field.

Enter the month of publication in the Month field if applicable. You must enter the calendar number of the month rather than the name of the month. For example, enter 12 if the item in hand was published in December.

Enter the day of publication in the day field if applicable.

Click Compile to generate the holdings code.

Click Save to finish.

103.4.2. From the original Serial Control View

Click Issuances beneath the subscription from the tree on the left. Right click to show the Actions menu, or click Actions for Selected Rows, and click Add Issuance.

As of Evergreen 2.2, the Issuance editor is the same as mentioned above in the new combination view.

103.5. Generate Prediction

Select the Subscription in the tree on the left.

Right-click to show the Actions menu, or click Actions for Selected Row, then click Make predictions.

A pop up box will ask you how many items you want to predict. Enter the number, and click OK.

A confirmation message will appear. Click OK.

To view the predicted issues, select a Subscription from the tree on the left, then click the Issuances tab in the panel on the right.

Chapter 104. Alternate Serial Control View

Using the Alternate Serial Control View, you can create a subscription, a distribution, a stream, and a caption and pattern, and you can generate predictions and receive issues. To access Alternate Serial Control View, open a serials record, and click Actions for this Record → Alternate Serial Control. This opens the Subscriptions interface

Create a subscription

Create a distribution

Create a a stream (within the distribution)

Create a caption and pattern (or import from bibliographic or legacy serial records)

Create at least the first issuance and generate predictions

104.1. Creating a Subscription

A subscription is designed to hold all information related to a single serial title. Therefore, each library is likely to have only one subscription per serial title.

Add new subscriptions to a serials record that exists in the catalog.

Create a subscription

Click New Subscription.

Select an owning library. The owning library indicates the organizational unit(s) whose staff can use this subscription. This menu is populated with the shortnames that you created for your libraries in the organizational units tree in Admin → Server Administration → Organizational Units. The rule of parental inheritance applies to this list. For example, if a system is made the owner of a subscription, then users, with appropriate permissions, at the branches within the system could also use this subscription.

Enter the date that the subscription begins in the start date. Recommended practice is that you select the date from the drop down calendar although you can manually enter a date. Owning library and start date are required fields in the new subscription pop up box.

Enter the date that the subscription ends in the end date. Recommended practice is to select a date from the drop down calendar, but you can manually enter a date, also.

Enter the difference between the nominal publishing date of an issue and the date that you expect to receive your copy in the Expected Date Offset. For example, if an issue is published the first day of each month, but you receive the copy two days prior to the publication date, then enter -2 days into this field.

Click Save.

After you save the subscription, it will appear in a list with a hyperlinked ID number. Use the drop down menu at the top of the screen to view subscriptions at other organizations.

104.2. Creating a Distribution

Distributions indicate the branches that should receive copies of a serial. Distributions work together with streams to indicate the number of copies that should be sent to each branch.

Click the Distributions tab.

Click New Distribution.

Enter a name for the distribution in the Label field. It may be useful to identify the branch to which you are distributing these issues in this field. This field is not publicly visible and only appears when an item is received. There are no limits on the number of characters that can be entered in this field.

Select a holding library from the drop down menu. The holding library is the branch that will receive the copies.

Select a copy template from the Receive Unit Template drop down menu. This menu is populated with the copy templates that you created in Copy Template Editor.

Label, Holding Library, and Receive Unit Template are required fields in the new distribution pop up box.

Ignore the fields, Unit Label Prefix and Unit Label Suffix. These fields are not functional in Alternate Serial Control View.

Click Save. The distribution will appear in a list in the Distributions tab in the Subscription Details.

104.3. Creating a Stream

Distributions work together with streams to indicate the number of copies that should be sent to each branch. Distributions identify the branches that should receive copies of a serial. Streams identify how many copies should be sent to each branch. Streams are intended for copies that are received on a recurring, even if irregular, basis.

Click the hyperlinked title of the distribution. The number of streams that have already been created for this distribution displays adjacent to the title. You can choose one of two ways to create a stream: New Stream or Create Many Streams. The New Stream button allows you to create one new stream and assign it a routing label.

Click New Stream

Enter a routing label so that the copy could be read by specific users or departments before the copy is shelved. The routing label appears during receiving and could be added to routing lists; it is not viewable by the public. Routing lists do not print from in 2.0. This field is optional.

Click Save.

The "Create Many Streams button" allows you to create multiple streams at once, but it does not allow you to add a routing label when you create the stream.

Click Create Many Streams.

Enter the number of streams that you want to create in the How many. Field.

Click Create.

104.3.1. Creating a Routing List

Within Alternate Serial Control View, you have the option to create routing lists for selected streams. Routing lists enable you to designate specific users and/or departments that serial items need to be routed to upon receiving. These routing lists can now display user addresses when you receive the items. This feature is particularly useful for working with homebound patrons.

Create a Routing List in Alternate Serial Control View that will display the User’s Address:

Select the checkbox for the stream that needs a routing list

Click Routing List for Selected Stream

Click the Reader (barcode): radio button and enter the user’s barcode into the field

Click Add

Click Save Changes

When you receive the item in Serials Batch Receive or from within Alternate Serial Control’s Batch Item Receive, the routing list will print the user’s address. For more information, see the chapter on Batch Receiving.

The default template can be configured to not include the user’s mailing or billing address on the routing list. Libraries already using customized templates will not be affected.

104.4. Creating a Caption and Pattern

The Captions and Patterns wizard allows you to enter caption and pattern data as it is described by the 853, 854, and 855 MARC tags. These tags allow you to define how issues will be captioned, and how often the library receives issues of the serial.

Open the Subscription Details.

Click the Captions and Patterns tab.

Click Add Caption and Pattern.

In the Type drop down box, select the MARC tag to which you would like to add data.

In the Pattern Code drop down box, you can enter a JSON representation of the 85X tag by hand, or you can click the Wizard to enter the information in a user-friendly format.

The Caption and Pattern that you create is Active by default, but you can deactivate a caption and pattern at a later time by unchecking the box.

A subscription may have multiple captions and patterns listed in the subscription details, but only one Caption and Pattern can be active at any time. If you want to add multiple patterns, e.g. for Basic and Supplement, Click Add Caption and Pattern.

104.4.1. Use the Pattern Code Wizard

The Pattern Code Wizard enables you to create the caption of the item and add its publication information. The Wizard is composed of five pages of questions. You can use the Next and Previous navigation buttons in the top corners to flip between pages.

To add a pattern code, click Wizard.

104.4.1.1. Page 1: Enumerations

To add an enumeration, check the box adjacent to Use enumerations. The enumerations conform to $a-$h of the 853,854, and 855 MARC tags.

A field for the First level will appear. Enter the enumeration for the first level. A common first level enumeration is volume, or "v."

Click Add Enumeration.

A field for the Second level will appear. Enter the enumeration for the second level. A common first level enumeration is number, or "no."

Enter the number of bibliographic units per next higher level. This conforms to $u in the 853, 854, and 855 MARC tags.

Choose the enumeration scheme from the drop down menu. This conforms to $v in the 853, 854, and 855 MARC tags.

You can add up to six levels of enumeration.

Add Alternate Enumeration if desired.

When you have completed the enumerations, click Next.

104.4.1.2. Page 2: Calendar

To use months, seasons, or dates in your caption, check the box adjacent to Use calendar changes.

Identify the point in the year at which the highest level enumeration caption changes.

In the Type drop down menu, select the points during the year at which you want the calendar to restart.

In the Point drop down menu, select the specific time at which you would like to change the calendar

To add another calendar change, click Add Calendar Change. There are no limits on the number of calendar changes that you can add.

When you have finished the calendar changes, click Next.

104.4.1.3. Page 3: Chronology

To add chronological units to the captions, check the box adjacent to Use chronology captions.

Choose a chronology for the first level. If you want to display the terms, "year" and "month" next to the chronology caption in the catalog, then check the box beneath Display in holding field.

To include additional levels of chronology, click Add Chronology Caption. Each level that you add must be smaller than the previous level.

After you have completed the chronology caption, click Next.

104.4.1.4. Page 4: Compress and Expand Captions

Select the appropriate option for compressing or expanding your captions in the catalog from the compressibility and expandability drop down menu. The entries in the drop down menu correspond to the indicator codes and the subfield $w in the 853 tag. Compressibility and expandability correspond to the first indicator in the 853 tag.

Choose the appropriate caption evaluation from the drop down menu.

Choose the frequency of your publication from the drop down menu. For irregular frequencies, you may wish to select use number of issues per year, and enter the total number of issues that you receive each year. However, recommended practice is that you use only regular frequencies. Planned development will create an additional step to aid in the creation of irregular frequencies.

Click Next.

104.4.1.5. Page 5: Regularity Information

If needed, check box for Use specific regularity information

Choose the appropriate information for combined, omitted or published issues

Choose the appropriate frequency and issue

Add additional rows as required

104.4.1.6. Page 5: Finish Captions and Patterns

To complete the wizard, click Create Pattern Code.

Return to Subscription Details.

Confirm that the box adjacent to Active is checked. Click Save Changes. The row is now highlighted gray instead of orange.

104.5. Creating an Issuance

The Issuances tab enables you to manually create an issue. Evergreen will use the initial issue that you manually create to predict future issues.

Click the Issuances tab in the Subscription Details.

Click New Issuance.

The Subscription, Creator, and Editor fields contain subscription and user IDs, respectively. These fields are disabled because Evergreen automatically fills in these fields.

Enter a name for this issuance in the Label field. There are no limits on the number of characters that can be entered in this field. You may want to enter the month and year of the publication in hand.

Enter the Date Published of the issuance that you are editing. Recommended practice is that you select the date from the drop down calendar although you can manually enter a date. If you are creating one manual issue before automatically predicting more issues, then this date should be the date of the most current issue before the prediction starts.

Select a Caption/Pattern from the drop down menu. The numbers in the drop down menu correspond to the IDs of the caption/patterns that you created.

The Holding Type appears by default and corresponds to the Type that you selected when you created the Caption/Pattern.

In the holding code area of the New Issuance dialog, click Wizard. The Wizard enables you to add holdings information.

Enter the volume of the item in hand in the v. field.

Enter the number of the item in hand in the no. field.

Enter the year of publication in the Year field.

Enter the month of publication in the Month field if applicable. You must enter the calendar number of the month rather than the name of the month. For example, enter 12 if the item in hand was published in December.

Enter the day of publication in the day field if applicable.

Click Compile to generate the holdings code.

104.6. Generate Item Predictions

After you manually create the first issue, Evergreen will predict future issuances. Use the Generate Predictions functionality to predict future issues.

Click Subscription Details → Issuances → Generate Predictions.

Choose the length of time for which you want to predict issues. If you select the radio button to predict until end of subscription, then Evergreen will predict issues until the end date that you created when you created the subscription. See creating a subscription for more information. If you do not have an end date, select the radio button to predict a certain number of issuances, and enter a number in the field.

Click Generate.

Evergreen will predict a run of issuances and copies. The prediction will appear in a list.

You can delete the first, manual issuance by clicking the check box adjacent to the issuance and clicking Delete Selected.

Chapter 105. Edit Subscriptions

Subscriptions can be edited to change the caption and pattern and other information.

105.1. Serials Control View

To access Serial Control View, open a serials record, and click Actions for this Record → Serial Control. This opens the Subscriptions interface

Click the subscriptions tab

Click on the appropriate link to edit

105.2. Alternate Serials Control View

To access Alternate Serial Control View, open a serials record, and click Actions for this Record → Alternate Serial Control. This opens the Subscriptions interface

Click the hyperlinked ID number to edit the subscription.

Click on the appropriate tab to edit the information

Chapter 106. Receiving

You can receive either through the Serials Control View or in Batch Receive with the simple or advanced interface.

106.1. Serials Control View Receiving

To receive items, click the Receive radio button. In the top pane, the items that have yet to be received are displayed. In the bottom pane, recently received items are displayed with the most recent at the top.

Select the branch that will receive the items from the drop down box.

Select the item that you want to receive.

Select the current working unit. Click Set Current Unit, located in the lower right corner of the screen. A drop down menu will appear.

If you want to barcode each item individually, select Auto per item. This setting is recommended for most receiving processes.

If you want each item within a unit to share the same barcode, then select New Unit. This setting is advised for most binding processes.

If you want the item to be received or bound into an existing item, select Recent and select the desired item from the menu. To make a change in bound items, receive or bind the items into an already existing unit.

Click Receive/Move Selected.

Enter a barcode and call number if prompted to do so.

A message confirming receipt of the item appears. Click OK.

The screen refreshes. Now the item has moved from the top pane to the bottom pane. (If you have checked "Show all", the item also remains in the top pane, with a received date added to it.) In the bottom pane, the item that you have just received is now at the top of the list of the received items.

After receiving items, you can view the updated holdings in the OPAC.

106.1.1. Notes in the Receiving Interface

The total number of notes for each item is displayed in the "Notes" column in the Items tab. The column header says "Notes (Item/Dist/Sub)" to explain how the numbers are organized in the column: First is the total number of Item Notes on that item, second is the number of Distribution Notes for that item’s distribution, and last is the number of Subscription Notes on that item’s subscription. To view and modify any of these notes, right-click on an item and click View Sub. Notes, View Dist. Notes or View Item Notes.

106.1.2. Serial Alerts At Receive Time

In the Serial Control View, you can now flag a note as an "alert" to make it more visible on the receiving interface. This flag is available as a checkbox on subscription, distribution and item notes. The new Alerts button on the Items tab displays the number of alert notes that are available for the selected items, and clicking this button opens a window which displays all applicable alert notes, sorted by type. Notes can also be edited or deleted from this window.

106.1.3. 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 offers 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. The claimed status changes the display but does not yet connect with the Acquisitions module in any way. Also note that, once you set an item to not held or not published, that item will be hidden from the list unless you check the Show All checkbox.

106.2. Batch Receiving

You can batch receive items through a simple or an advanced interface. The simple interface does not allow you to add barcodes or use the copy template. These items are also not visible in the OPAC. The advanced interface enables you to use the copy templates that you created, add barcodes, and make items OPAC visible and holdable.

You can access both Batch Receive interfaces from two locations in the ILS. From the Subscription Details screen, you can click Batch Item Receive. You can also access these interfaces by opening the catalog record for the serial, and clicking Actions for this Record → Serials Batch Receive.

106.2.1. Simple Batch Receiving

Follow these steps to receive items in batch in a simple interface.

The Batch Receive interface displays issues that have not yet been received. The earliest expected issue appears at the top of the list.

In the right lower corner, you see a check box to Create Units for Received Items. If you do not check this box, then you will receive items in simple mode.

Click Next.

In simple mode, the distributions that you created are displayed. They are marked received by default. If you hover over the branch name, you can view the name of the distribution and its stream.

You can receive and add a note to each item individually, or you can perform these actions on all of the distributions and streams at once. To do so, look above the line, and enter the note that you want to apply to all copies and confirm that the box to Receive is checked.

Click Apply. The note should appear in the note field in each distribution.

Then click Receive Selected Items.

The received items are cleared from the screen.

106.2.2. Advanced Batch Receiving

Follow these steps to receive items in batch in a simple interface.

The Batch Receive interface displays issues that have not yet been received. The earliest expected issue appears at the top of the list.

If you want to barcode each copy, display it in the catalog, and make it holdable, then check the box adjacent to Create Units for Received Items in the lower right side of the screen.

This will allow you to utilize the copy templates and input additional information about the copy:

Barcode - You can scan printed barcodes into the barcode field for each copy, or you can allow the system to auto-generate barcodes. To auto-generate barcodes, check the box adjacent to Auto-generate, and enter the first barcode into the barcode field in the first row of the table. Then press the Tab key. The remaining barcode fields will automatically populate with the next barcodes in sequence, including check digits.

Circ Modifiers - The circ modifiers drop down menu is populated with the circulation modifiers that you created in Admin → Server Administration → Circulation Modifiers. If you entered a circ modifier in the copy template that you created for this subscription, then it will appear by default in the distributions.

Call Number - Enter a call number. Any item with a barcode must also have a call number.

Note - Add a note. There are no limits on the number of characters that can be entered in this field. The note only displays in this screen.

Copy Location - The copy location drop down menu is populated with the copy locations that you created in Admin → Local Administration → Copy Location Editor. If you entered a copy location in the copy template that you created for this subscription, then it will appear by default in the distributions.

Price - If you entered a price in the copy template that you created for this subscription, then it will appear by default in the distributions. You can also manually enter a price if you did not include one in the copy template.

Receive - The boxes in the Receive column are checked by default. Uncheck the box if you do not want to receive the item. Evergreen will retain the unreceived copies and will allow you to receive them at a later time.

When you are ready to receive the items, click Receive Selected Items.

The items that have been received are cleared from the Batch Receive interface. The remaining disabled item is an unreceived item.

If the items that you received have a barcode, a copy template that was set to OPAC Visible, and are assigned a shelving location that is OPAC Visible, then you can view the received items in the catalog. Notice that the Holdings Summary has been updated to reflect the most recent addition to the holdings.

106.2.3. Duplicate Barcode Alert

Evergreen will now display an alert if a duplicate barcode is entered in the Serials Batch Receive interface. If a staff member enters a barcode that already exists in the database while receiving new serials items in the Serials Batch Receive interface, an alert message will pop up letting the staff member know that the barcode is a duplicate. After the staff member clicks OK to clear the alert, he or she can enter a new barcode.

Chapter 107. Special Issues

Currently, creating a special issue can only be done through the Alternate Serials Control View.

Create an issuance in the Serials Control View or the Alternate Serials Control View

In the Alternate Serials Control View, click on the name of your special issue in the list of issuances.

Click the New Items button

Enter the appropriate information

The item is now ready to receive. If you complete the Date Received field and change the status to received then it will receive the issue but it won’t create the associated copy record whereas if you leave it blank and receive the item through the Serials Control View or Batch Receive function you can create the Copy Record at that time.

Chapter 108. Holdings

108.1. System Generated Holdings Statement

As issues are received, Evergreen creates a holding statement in the OPAC based on what is set up in the Caption and Patterns of the subscription. The systems generated holdings can only be edited by changing caption and pattern information and there is no ability to edit the statement as free text.

108.2. MARC Format for Holdings Display (MFHD)

Evergreen users can create, edit and delete their own MFHD.

108.2.1. Create an MFHD record

Open a serial record, and in the bottom right corner above the copy information, click Add MFHD Record. You can also add the MFHD statement by clicking Actions for this Record → MFHD Holdings → Add MFHD Record.

A message will confirm that you have created the MFHD Record. Click OK.

Click Reload in the top left corner of the record.

The Holdings Summary will appear. Click Edit Holdings in the right corner.

Click Edit Record.

The MFHD window will pop up. Enter holdings information. Click Save MFHD.

Close the MFHD window.

Click Reload in the top left corner of the record. The Holdings Summary will reflect the changes to the MFHD statement.

108.2.2. Edit a MFHD record

Open a serial record, click Actions for this Record → MFHD Record → Edit MFHD Record and select the appropriate MFHD.

Edit the MFHD

Click Save MFHD

108.2.3. Delete a MFHD Record

Open a serial record, click Actions for this Record → MFHD Record → Delete MFHD Record and select the appropriate MFHD.

Click to confirm the deletion of the MFHD

Chapter 109. Group Serials Issues in the Template Toolkit OPAC

In previous versions of Evergreen, issues of serials displayed in a list ordered by publication date. The list could be lengthy if the library had extensive holdings of a serial. Using the Template Toolkit OPAC that is available in version 2.2, you can group issues of serials in the OPAC by chronology or enumeration. For example, you might group issues by date published or by volume. Users can expand these hyperlinked groups to view holdings of specific issues. The result is a clean, easy-to-navigate interface for viewing holdings of serials with a large quantity of issues.

This feature is only available in the Template Toolkit OPAC.

109.1. Administration

Enable the following organizational unit settings to use this feature:

Click Admin → Local Administration → Library Settings Editor.

Search or scroll to find Serials: Default display grouping for serials distributions presented in the OPAC.

Click Edit.

Enter enum to display issues by enumeration, or enter chron to display issues in chronological order. This value will become your default setting for display issues in the OPAC.

Click Update Setting.

Search or scroll to find OPAC: Use fully compressed serials holdings.

Select the value, True, to view a compressed holdings statement.

Click Update Setting.

109.2. Displaying Issues in the OPAC

Your library system has a subscription to the periodical, Bon Appetit. The serials librarian has determined that the issues at the Forest Falls branch should display in the OPAC by month and year. The issues at the McKinley branch should display by volume and number. The serials librarian will create two distributions for the serial that will include these groupings.

Retrieve the bibliographic record for the serial, and click Actions for this Record → Alternate Serial Control.

Create a New Subscription or click on the hyperlinked ID of an existing subscription.

Click New Distribution.

Create a label to identify the distribution.

Select the holding library from the drop down menu that will own physical copies of the issues.

Select a display grouping. Select chronology from the drop down menu.

Select a template from the drop down menu to receive copies.

Click Save.

Click New Distribution and repeat the process to send issues to the McKinley Branch. Choose enumeration in the Display Grouping field to display issues by volume and number.

Complete the creation of your subscription.

Retrieve the record from the catalog.

Scroll down to and click the Issues Held link. The issues label for each branch appears.

Click the hyperlinked issues label.

The issues owned by the Forest Falls branch are grouped by chronology:

The issues owned by the McKinley branch are grouped by enumeration:

Part XI. Circulation

Chapter 110. Introduction

Use this section for understanding the circulation procedures in the Evergreen system.

Chapter 111. Circulating Items

111.1. Check Out

111.1.1. Regular Items

1) To check out an item click Check Out Items from the Circulation and Patrons toolbar, or select Circulation → Check Out.

2) Scan or enter patron’s barcode and click Submit if entering barcode manually. If scanning, number is submitted automatically.

3) Scan or enter item barcode manually, clicking Submit if manual.

4) Due date is now displayed.

5) When all items are scanned, click the Done button to generate slip receipt or to exit patron record if not printing slip receipts.

111.1.2. Pre-cataloged Items

1) Go to patron’s Check Out screen by clicking Circulation → Check Out Items.

2) Scan the item barcode.

3) At prompt, enter the required information click Precat Checkout.

On check-in, Evergreen will prompt staff to re-route the item to cataloging.

111.1.3. Due Dates

Circulation periods are pre-set. When items are checked out, due dates are automatically calculated and inserted into circulation records if the Specific Due Date checkbox is not selected on the Check Out screen. The Specific Due Date checkbox allows you to set a different due date to override the pre-set loan period.

Before you scan the item, select the Specific Due Date checkbox. Enter the date in yyyy-mm-dd format. This date applies to all items until you change the date, de-select the Specific Due Date checkbox, or quit the patron record.

111.1.4. Email Checkout Receipts

This feature allows patrons to receive checkout receipts through email at the circulation desk and in the Evergreen self-checkout interface. Patrons need to opt in to receive email receipts by default and must have an email address associated with their account. Opt in can be staff mediated at the time of account creation or in existing accounts. Patrons can also opt in directly in their OPAC account or through patron self-registration. This feature does not affect the behavior of checkouts from SIP2 devices.

111.1.4.1. Staff Client Check Out

When a patron has opted to receive email checkout receipts by default, an envelope icon representing email will appear next to the receipt options in the Check Out screen. A printer icon representing a physical receipt appears if the patron has not opted in to the default email receipts.

Staff can click Quick Receipt and the default checkout receipt option will be triggered—an email will be sent or the receipt will print out. The Quick Receipt option allows staff to stay in the patron account after completing the transaction. Alternatively, staff can click Done to trigger the default checkout receipt and close out the patron account. By clicking on the arrow next to the Quick Receipt or Done buttons, staff can select which receipt option to use, regardless of the selected default. The email receipt option will be disabled if the patron account does not have an email address.

111.1.4.2. Self Checkout

In the Self Checkout interface, patrons will have the option to select a print or email checkout receipt, or no receipt. The radio button for the patron’s default receipt option will be selected automatically in the interface. Patrons can select a different receipt option if desired. The email receipt radio button will be disabled if there is no email address associated with the patron’s account.

111.1.4.3. Opt In

Staff Mediated Opt In At Registration

Patrons can be opted in to receive email checkout receipts by default by library staff upon the creation of their library account. Within the patron registration form, there is a new option below the Email Address field to select Email checkout receipts by default?. Select this option if the patron wants email checkout receipts to be their default. Save any changes.

Staff Mediated Opt In After Registration

Staff can also select email checkout receipts as the default option in a patron account after initial registration. Within the patron account go to Edit and select Email checkout receipts by default?. Make sure the patron also has an email address associated with their account. Save any changes.

Patron Opt In – Self-Registration Form

If your library offers patrons the ability to request a library card through the patron self-registration form, they can select email checkout receipts by default in the initial self-registration form:

Patron Opt In - OPAC Account

Patrons can also opt in to receive email checkout receipts by default directly in their OPAC account. After logging in, patrons can go to Account Preferences→Notification Preferences and enable Email checkout receipts by default? and click Save.

111.1.4.4. Email Checkout Receipt Configuration

Email checkout receipts will be sent out through a Notifications/Action Trigger called Email Checkout Receipt. The email template and action trigger can be customized by going to Administration→Local Administration→Notifications/Action Trigger→Email Checkout Receipt.

111.2. Check In

111.2.1. Regular check in

1) To check in an item click Check In Items from the Circulation and Patrons toolbar, or select Circulation → Check In.

2) Scan item barcode or enter manually and click Submit.

3) If there is an overdue fine associated with the checkin, an alert will appear at the top of the screen with a fine tally for the current checkin session. To immediately handle fine payment, click the alert to jump to the patron’s bill record.

111.2.2. Backdated check in

This is useful for clearing a book drop.

1) To change effective check-in date, select Circulation → Check In Items. In Effective Date field enter the date in yyyy-mm-dd format.

2) The new effective date is now displayed in the red bar above the Barcode field.

3) Move the cursor to the Barcode field. Scan the items. When finishing backdated check-in, change the Effective Date back to today’s date.

111.2.3. Backdate Post-Checkin

After an item has been checked in, you may use the Backdate Post-Checkin function to backdate the check-in date.

1) Select the item on the Check In screen, click Actions → Backdate Post-Checkin.

2) In Effective Date field enter the date in yyyy-mm-dd format. The check-in date will be adjusted according to the new effective check-in date.

Checkin Modifiers

At the right bottom corner there is a Checkin Modifiers pop-up list. The options are:

-Ignore Pre-cat Items: no prompt when checking in a pre-cat item. Item will be routed to Cataloguing with Cataloguing status.

-Supress Holds and Transit: item will not be used to fill holds or sent in transit. Item has Reshelving status.

-Amnesty Mode/Forgive Fines: overdue fines will be voided if already created or not be inserted if not yet created (e.g. hourly loans).

-Auto-Print Hold and Transit Slips: slips will be automatically printed without prompt for confirmation.

-Clear Holds Shelf. Checking in hold-shelf-expired items will clear the items from the hold shelf (holds to be cancelled).

-Retarget Local Holds. When checking in in process items that are owned by the library, attempt to find a local hold to retarget. This is intended to help with proper targeting of newly-catalogued items.

-Retarget All Statuses. Similar to Retarget Local Holds, this modifier will attempt to find a local hold to retarget, regardless of the status of the item being checked in. This modifier must be used in conjunction with the Retarget Local Holds modifier.

-Capture Local Holds as Transits. With this checkin modifier, any local holds will be given an in transit status instead of on holds shelf. The intent is to stop the system from sending holds notifications before the item is ready to be placed on the holds shelf and item will have a status of in-transit until checked in again. If you wish to simply delay notification and allow time for staff to process item to holds shelf, you may wish to use the Hold Shelf Status Delay setting in Library Settings Editor instead. See Local Administration section for more information.

These options may be selected simultaneously. The selected option is displayed in the header area.

111.3. Renewal and Editing the Item’s Due Date

Checked-out items can be renewed if your library’s policy allows it. The new due date is calculated from the renewal date. Existing loans can also be extended to a specific date by editing the due date or renewing with a specific due date.

111.3.1. Renewing via a Patron’s Account

1) Retrieve the patron record and go to the Items Out screen.

2) Select the item you want to renew. Click on Actions → Renew. If you want to renew all items in the account, click Renew All instead.

3) If you want to specify the due date, click Renew with Specific Due Date. You will be prompted to select a due date. Once done, click Apply.

111.3.2. Renewing by Item Barcode

1) To renew items by barcode, select Circulation → Renew Items.

2) Scan or manually entire the item barcode.

3) If you want to specify the due date, click Specific Due Date and enter a new due date in yyyy-mm-dd format.

111.3.3. Editing Due Date

1) Retrieve the patron record and go to the Items Out screen.

2) Select the item you want to renew. Click on Actions → Edit Due Date.

3) Enter a new due date in yyyy-mm-dd format in the pop-up window, then click OK.

Editing a due date is not included in the renewal count.

111.4. Marking Items Lost and Claimed Returned

111.4.1. Lost Items

1) To mark items Lost, retrieve patron record and click Items Out.

2) Select the item. Click on Actions → Mark Lost (by Patron).

3) The lost item now displays as lost in the Items Checked Out section of the patron record.

4) The lost item also adds to the count of Lost items in the patron summary on the left (or top) of the screen.

Lost Item Billing

Marking an item Lost will automatically bill the patron the replacement cost of the item as recorded in the price field in the item record, and a processing fee as determined by your local policy. If the lost item has overdue charges, the overdue charges may be voided or retained based on local policy.

A lost-then-returned item will disappear from the Items Out screen only when all bills linked to this particular circulation have been resolved. Bills may include replacement charges, processing fees, and manual charges added to the existing bills.

The replacement fee and processing fee for lost-then-returned items may be voided if set by local policy. Overdue fines may be reinstated on lost-then-returned items if set by local policy.

111.4.2. Refunds for Lost Items

If an item is returned after a lost bill has been paid and the library’s policy is to void the replacement fee for lost-then-returned items, there will be a negative balance in the bill. A refund needs to be made to close the bill and the circulation record. Once the outstanding amount has been refunded, the bill and circulation record will be closed and the item will disappear from the Items Out screen.

If you need to balance a bill with a negative amount, you need to add two dummy bills to the existing bills. The first one can be of any amount (e.g. $0.01), while the second should be of the absolute value of the negative amount. Then you need to void the first dummy bill. The reason for using a dummy bill is that Evergreen will check and close the circulation record only when payment is applied or bills are voided.

111.4.3. Claimed Returned Items

1) To mark an item Claimed Returned, retrieve the patron record and go to the Items Out screen.

2) Select the item, then select Actions → Mark Claimed Returned from the dropdown menu.

3) Enter date in yyyy-mm-dd format and click Submit.

4) The Claimed Returned item now displays in the Other/Special Circulations section of the patron record.

5) The Claimed Returned item adds to the count of items that are Claimed Returned in the patron summary on the left (or top) of the screen. It also adds to the total Other/Special Circulations that is displayed when editing the patron’s record.

More on Claimed Returned Items

The date entered for a Claimed Returned item establishes the fine. If the date given has passed, bills will be adjusted accordingly.

When a Claimed Returned item is returned, if there is an outstanding bill associated with it, the item will not disappear from the Items Out screen. It will disappear when the outstanding bills are resolved.

When an item is marked Claimed Returned, the value in Claims-returned Count field in the patron record is automatically increased. Staff can manually adjust this count by editing the patron record.

111.5. In-house Use (F6)

1) To record in-house use, select Circulation → Record-In House Use, click Check Out → Record In-House Use on the circulation toolbar , or press F6.

2) To record in-house use for cataloged items, enter number of uses, scan barcode or type barcode and click Submit.

There are two independent library settings that will allow copy alerts to display when scanned in In-house Use: Display copy alert for in-house-use set to true will cause an alert message to appear, if it has one, when recording in-house-use for the copy. Display copy location check in alert for in-house-use set to true will cause an alert message indicating that the item needs to be routed to its location if the location has check in alert set to true.

3) To record in-house use for non-cataloged items, enter number of uses, choose non-cataloged type from drop-down menu, and click Submit.

The statistics of in-house use are separated from circulation statistics. The in-house use count of cataloged items is not included in the items' total use count.

111.6. Item Status

The Item Status screen is very useful. Many actions can be taken by either circulation staff or catalogers on this screen. Here we will cover some circulation-related functions, namely checking item status, viewing past circulations, inserting item alert messages, marking items missing or damaged, etc.

111.6.1. Checking item status

1) To check the status of an item, select Search → Search for copies by Barcode.

2) Scan the barcode or type it and click Submit. The current status of the item is displayed with selected other fields. You can use the column picker to select more fields to view.

3) Click the Detail View button and the item summary and circulation history will be displayed.

4) Click List View to go back.

If the item’s status is "Available", the displayed due date refers to the previous circulation’s due date.

Upload From File allows you to load multiple items saved in a file on your local computer. The file contains a list of the barcodes in text format. To ensure smooth uploading and further processing on the items, it is recommended that the list contains no more than 100 items.

111.6.2. Viewing past circulations

1) To view past circulations, retrieve the item on the Item Status screen as described above.

2) Select Detail view.

3) Choose Recent Circ History. The item’s recent circulation history is displayed.

4) To retrieve the patron(s) of the last circulations, click on the name of the patron. The patron record will be displayed.

The number of items that displays in the circulation history can be set in Local Administration → Library Settings Editor.

You can also retrieve the past circulations on the patron’s Items Out screen and from the Check In screen.

111.6.3. Marking items damaged or missing and other functions

1) To mark items damaged or missing, retrieve the item on the Item Status screen.

2) Select the item. Click on Actions for Selected Items → Mark Item Damaged or Mark Item Missing.

Depending on the library’s policy, when marking an item damaged, bills (cost and/or processing fee) may be inserted into the last borrower’s account.

3) Following the above procedure, you can check in and renew items by using the Check in Items and Renew Items on the dropdown menu.

111.6.4. Item alerts

The Edit Item Attributes function on the Actions for Selected Items dropdown list allows you to edit item records. Here, we will show you how to insert item alert messages by this function. See cataloging instructions for more information on item editing. 1) Retrieve record on Item Status screen.

2) Once item is displayed, highlight it and select Actions for Selected Items → Edit Item Attributes.

3) The item record is displayed in the Copy Editor.

4) Click Alert Message in the Miscellaneous column. The background color of the box changes. Type in the message then click Apply.

5) Click Modify Copies, then confirm the action.

111.7. Mark an Item Long Overdue

Marking an item Long Overdue

Once an item has been overdue for a configurable amount of time, Evergreen will mark the item long overdue in the borrowing patron’s account. This will be done automatically through a Notification/Action Trigger. When the item is marked long overdue, several actions will take place:

The item will go into the status of “Long Overdue”

The item will be moved to the “Lost, Claimed Returned, Long Overdue, Has Unpaid Billings” section of the Items Out screen in the patron’s account

The accrual of overdue fines will be stopped

Optionally the patron can be billed for the item price, a long overdue processing fee, and any overdue fines can be voided from the account. Patrons can also be sent a notification that the item was marked long overdue.

Checking in a Long Overdue item

If an item that has been marked long overdue is checked in, an alert will appear on the screen informing the staff member that the item was long overdue. Once checked in, the item will go into the status of “In process”. Optionally, the item price and long overdue processing fee can be voided and overdue fines can be reinstated on the patron’s account. If the item is checked in at a library other than its home library, a library setting controls whether the item can immediately fill a hold or circulate, or if it needs to be sent to its home library for processing.

Notification/Action Triggers

Evergreen has two sample Notification/Action Triggers that are related to marking items long overdue. The sample triggers are configured for 6 months. These triggers can be configured for any amount of time according to library policy and will need to be activated for use.

Sample Triggers

6 Month Auto Mark Long-Overdue—will mark an item long overdue after the configured period of time

6 Month Long Overdue Notice—will send patron notification that an item has been marked long overdue on their account

Library Settings

The following Library Settings enable you to set preferences related to long overdue items:

Circulation: Long-Overdue Check-In Interval Uses Last Activity Date —Use the long-overdue last-activity date instead of the due_date to determine whether the item has been checked out too long to perform long-overdue check-in processing. If set, the system will first check the last payment time, followed by the last billing time, followed by the due date. See also circ.max_accept_return_of_longoverdue

Circulation: Long-Overdue Items Usable on Checkin —Long-overdue items are usable on checkin instead of going "home" first

Circulation: Long-Overdue Max Return Interval —Long-overdue check-in processing (voiding fees, re-instating overdues, etc.) will not take place for items that have been overdue for (or have last activity older than) this amount of time

Circulation: Restore Overdues on Long-Overdue Item Return

Circulation: Void Long-Overdue item Billing When Returned

Circulation: Void Processing Fee on Long-Overdue Item Return

Finances: Leave transaction open when long overdue balance equals zero —Leave transaction open when long-overdue balance equals zero. This leaves the lost copy on the patron record when it is paid

Finances: Long-Overdue Materials Processing Fee

Finances: Void Overdue Fines When Items are Marked Long-Overdue

Permissions to use this Feature

The following permissions are related to this feature:

COPY_STATUS_LONG_OVERDUE.override

Allows the user to check-in long-overdue items thus removing the long-overdue status on the item

Chapter 112. Holds Management

112.1. Placing Holds

Holds can be placed by staff in the Staff Client and by patrons in the OPAC. In this chapter we demonstrate placing holds in the Staff Client.

112.2. Holds Levels

Evergreen has different levels of holds. Library staff can place holds at all levels, while patrons can only place title-level holds, and parts-level holds. The chart below summarizes the levels of holds.

Hold level

Abbreviation

When to use

How to use

Who can use

Hold tied to

Title

T

Patron wants first available copy of a title

Staff or patron click on Place Hold next to title.

Patron or staff

Holdings attached to a single MARC (title) record

Parts

P

Patron wants a particular part of title (e.g. volume or disk number)

Staff or patron selects part on the create/edit hold screen when setting holds notification options.

Patron or staff

Holdings with identical parts attached to a single MARC (title) record.

Volume

V

Patron or staff want any title associated with a particular call number

In the staff client, click on Volume Hold under Holdable?

Staff only

Holdings attached to a single call number (volume)

Copy

C

Patron or staff want a specific copy of an item

In the staff client, click on Copy Hold under Holdable?

Staff only

A specific copy (barcode)

112.3. Title Level Hold

A default hold expiration date will be displayed if the library has set up a default holds expiration period in their library settings. Uncaptured holds will not be targeted after the expiration date.

If you select the Suspend this Hold checkbox, the hold will be suspended and not be captured until you activate it.

To place a title level hold, retrieve the title record on the catalog and click the Place Hold link beside the title on the search results list, or click the Place Hold link on the title summary screen.

Scan or type patron’s barcode into the Place hold for patron by barcode box, or choose Place this hold for me.

If this title contains multiple parts, you can specify which part to request. If you do not select a part, the hold will target any of the other copies on this record, that is, those with no parts attached. Those copies are usually the complete set, containing all the parts.

Edit patron hold notification and expiration date fields as required. Be sure to choose a valid Pickup location.

Click Submit.

A confirmation screen appears with the message "Hold was successfully placed".

Advanced Hold Options

Clicking the Advanced Hold Options link will take you into the metarecord level hold feature, where you can select multiple formats and/or languages, if available.

Selecting multiple formats will not place all of these formats on hold. For example, selecting CD Audiobook and Book implies that either the CD format or the book format is the acceptable format to fill the hold. If no format is selected, then any of the available formats may be used to fill the hold. The same holds true for selecting multiple languages.

See also the section on placing Metarecord Holds.

112.4. Parts Level Hold

To place a parts level hold, retrieve a record with parts-level items attached to the title, such as a multi-disc DVD, an annual travel guide, or a multi-volume book set.

Place the hold as you would for a title-level hold, including patron barcode, notification details, and a valid pickup location.

Select the applicable part from the Select a Part dropdown menu.

Click Submit.

Requested formats are listed in the Holdable Part column in hold records. Use the Column Picker to display it when the hold record is displayed.

112.5. Placing Holds in Patron Records

Holds can be placed from patron records too. In the patron record on the Holds screen, click the Place Hold button on the left top corner.

The catalog is displayed in the Holds screen to search for the title on which you want to place a hold.

Search for the title and click the Place Hold link.

The patron’s account information is retrieved automatically. Set up the notification and expiration date fields. Click Place Hold and confirm your action in the pop-up window.

You may continue to search for more titles. Once you are done, click the Holds button on the top to go back to the Holds screen. Click the Refresh button to display your newly placed holds.

112.5.1. Placing Multiple Holds on Same Title

After a successful hold placement, staff have the option to place another hold on the same title by clicking the link Place another hold for this title. This returns to the hold screen, where a different patron’s information can be entered.

This feature can be useful for book groups or new items where a list of waiting patrons needs to be transferred into the system.

112.6. Managing Holds

Holds can be cancelled at any time by staff or patrons. Before holds are captured, staff or patrons can suspend them or set them as inactive for a period of time without losing the hold queue position, activate suspended holds, change notification method, phone number, pick-up location (for multi-branch libraries only), expiration date, activation date for inactive holds, etc. Once a hold is captured, staff can change the pickup location and extend the hold shelf time if required.

Staff can edit holds in either patron’s records or the title records. Patrons can edit their holds in their account on the OPAC.

If you use the column picker to change the holds display from one area of the staff client (e.g. the patron record), it will change the display for all parts of the staff client that deal with holds, including the title record holds display, the holds shelf display, and the pull list display.

112.6.1. Actions for Selected Holds

Retrieve the patron record and go to the Holds screen.

Highlight the hold record, then select Actions for Selected Holds.

Manage the hold by choosing an action on the list.

If you want to cancel the hold, click Cancel Hold from the menu. You are prompted to select a reason and put in a note if required. To finish, click Apply.

A captured hold with a status of On Hold Shelf can be cancelled by either staff or patrons. But the status of the item will not change until staff check it in.

If you want to suspend a hold or activate a suspended hold, click the appropriate action on the list. You will be prompted to confirm your action. Suspended holds have a No value in the Active? column.

Suspended holds will not be filled but its hold position will be kept. They will automatically become active on the activation date if there is an activation date in the record. Without an activation date, the holds will remain inactive until staff or a patron activates them manually.

You may edit the Activation Date and Expiration Date by using the corresponding action on the Action for Selected Holds dropdown menu. You will be prompted to enter the new date. Use the calendar widget to choose a date, then click Apply. Use the Remove button to unset the date.

Hold shelf expire time is automatically recorded in the hold record when a hold is filled. You may edit this time by using the Edit Shelf Expire Time on the Action for Selected Holds dropdown menu. You will be prompted to enter the new date. Use the calendar widget to choose a date, then click Apply.

If you want to enable or disable phone notification or change the phone number, click Edit Phone Notification. You will be prompted to enter the new phone number. Make sure you enter a valid and complete phone number. The phone number is used for this hold only and can be different from the one in the patron account. It has no impact on the patron account. If you leave it blank, no phone number will be printed on the hold slip.

If you want to enable or disable email notification for the hold, click Set Email Notification. Click Email or No Email on the prompt screen.

Pickup location can be changed by clicking Edit Pickup Library. Click the dropdown list of all libraries and choose the new pickup location. Click Done.

Staff can change the pickup location for holds with in-transit status. Item will be sent in transit to the new destination. Staff cannot change the pickup location once an item is on the holds shelf.

The item’s physical condition is recorded in the copy record as Good or Mediocre in the Quality field. You may request that your holds be filled with copies of good quality only. Click Set Desired Copy Quality on the Actions for Selected Holds list. Make your choice in the pop-up window.

112.6.2. Transferring Holds

Holds on one title can be transferred to another with the hold request time preserved. To do so, you need to find the destination title and click Actions for this Record → Mark as Title Hold Transfer Destination.

Select the hold you want to transfer. Click Actions for Selected Holds → Transfer to Marked Title.

112.6.3. Cancelled Holds

Cancelled holds can be displayed. Click the Show Cancelled Holds button on the Holds screen.

You can un-cancel holds.

Based on your library’s setting, hold request time can be reset when a hold is un-cancelled.

112.6.4. Viewing Details & Adding Notes to Holds

You can view details of a hold by selecting a hold then clicking the Detail View button on the Holds screen.

You may add a note to a hold in the Detail View.

Notes can be printed on the hold slip if the Print on slip? checkbox is selected. Key in the message then click Add Note.

112.6.5. Displaying Queue Position

Using the Column Picker, you can display Queue Position and Total number of Holds.

112.6.6. Managing Holds in Title Records

Retrieve and display the title record in the catalog.

Click Actions for this Record → View Holds.

All holds on this title to be picked up at your library are displayed. Use the Filter checkbox and Pickup Library to view holds to be picked up at other libraries.

Highlight the hold you want to edit. Choose an action from the Actions for Selected Holds menu. For more information see the Actions for Selected Holds section.

You can retrieve the hold requestor’s account by selecting Retrieve Patron on the above dropdown menu.

112.6.7. Retargeting Holds

Holds need to be retargeted whenever a new item is added to a record, or after some types of item status changes, for instance when an item is changed from On Order to In Process. The system does not automatically recognize the newly added items as available to fill holds.

View the holds for the item.

Highlight all the holds for the record, which have a status of Waiting for Copy. If there are a lot of holds, it may be helpful to sort the holds by Status.

Click on the head of the status column.

Under Actions for Selected Holds (Alt+S), select Find Another Target (Alt+T)

A window will open asking if you are sure you would like to reset the holds for these items.

Click Yes (Alt+Y). Nothing may appear to happen, or if you are retargeting a lot of holds at once, your screen may go blank or seem to freeze for a moment while the holds are retargeted.

When the screen refreshes, the holds will be retargeted. The system will now recognize the new items as available for holds.

112.6.8. Pulling & Capturing Holds

112.6.8.1. Holds Pull List

There are usually four statuses a hold may have: Waiting for Copy, Waiting for Capture, In Transit and Ready for Pickup.

Waiting-for-copy: all holdable copies are checked out or not available.

Waiting-for-capture: an available copy is assigned to the hold. The item shows up on the Holds Pull List waiting for staff to search the shelf and capture the hold.

In Transit: holds are captured at a non-pickup branch and on the way to the pick-up location.

Ready-for-pick-up: holds are captured and items are on the Hold Shelf waiting for patrons to pick up. Besides capturing holds when checking in items, Evergreen matches holds with available items in your library at regular intervals. Once a matching copy is found, the item’s barcode number is assigned to the hold and the item is put on the Holds Pull List. Staff can print the Holds Pull List and search for the items on shelves.

To retrieve your Holds Pull List, select Circulation → Pull List for Hold Requests.

The Holds Pull List is displayed. You may re-sort it by clicking the column labels, e.g. Title. You can also add fields to the display by using the column picker.

Column adjustments will only affect the screen display and the CSV download for the holds pull list. It will not affect the printable holds pull list.

The maximum number of holds initially displayed on the pull list is about 100. Use Fetch More Holds to retrieve more records. You may have to click Reload for those records to appear in the display.

The following options are available for printing the pull list:

Print Full Pull List prints Title, Author, Shelving Location, Call Number and Item Barcode. This method uses less paper than the alternate strategy.

Print Full Pull List (Alternate Strategy) prints the same fields as the above option but also includes a patron barcode. This list will also first sort by copy location, as ordered under Admin → Local Administration → Copy Location Order.

Save List CSV to File – This option is available from the List Actions button and saves all fields in the screen display to a CSV file. This file can then be opened in Excel or another spreadsheet program. This option provides more flexibility in identifying fields that should be printed.

With the CSV option, if you are including barcodes in the holds pull list, you will need to take the following steps to make the barcode display properly: in Excel, select the entire barcode column, right-click and select Format Cells, click Number as the category and then reduce the number of decimal places to 0.

You may perform hold management tasks by using the Actions for Selected Holds dropdown list.

The Holds Pull List is updated constantly. Once an item on the list is no longer available or a hold on the list is captured, the items will disappear from the list. The Holds Pull List should be printed at least once a day.

112.6.8.2. Capturing Holds

Holds can be captured when a checked-out item is returned (checked in) or an item on the Holds Pull List is retrieved and captured. When a hold is captured, the hold slip will be printed and if the patron has chosen to be notified by email, the email notification will be sent out. The item should be put on the hold shelf.

To capture a hold, select Circulation → Capture Holds; click Check In → Capture Holds on the circulation toolbar; or hit Shift-F2.

Scan or type barcode and click Submit.

The following hold slip is automatically printed. (This slip will not display on the Capture Holds screen, but will display on a Check In screen not set to automatically print slips.)

If the item should be sent to another location, a hold transit slip will be printed. (This slip will not display on the Capture Holds screen, but may display on a Check In screen that is not set to automatically print slips.)

If a patron has an OPAC/Staff Client Holds Alias in his/her account, it will be used on the hold slip instead of the patron’s name. Holds can also be captured on the Circulation → Check In Items screen where you have more control over automatic slip printing.

112.6.9. Handling Missing and Damaged Item

If an item on the holds pull list is missing or damaged, you can change its status directly from the holds pull list.

From the Holds Pull List, right-click on the item and either select Mark Item Missing or Mark Item Damaged.

Evergreen will update the status of the item and will immediately retarget the hold.

112.6.10. Holds Notification Methods

In Evergreen, patrons can set up their default holds notification method in the Account Preferences area of My Account. Staff cannot set these preferences for patrons; the patrons must do it when they are logged into the public catalog.

The “Default Phone Number” option is the default for those users who have not yet set a preference.

Patrons with a default notification preference for phone will see their phone number at the time they place a hold. The checkboxes for email and phone notification will also automatically be checked.

The patron can remove these checkmarks at the time they place the hold or they can enter a different phone number if they prefer to be contacted at a different number. The patron cannot change their e-mail address at this time.

When the hold becomes available, the holds slip will display the patron’s e-mail address only if the patron selected the Notify by Email by default when a hold is ready for pickup? checkbox. It will display a phone number only if the patron selected the Notify by Phone by default when a hold is ready for pickup? checkbox.

If the patron changes their contact telephone number when placing the hold, this phone number will display on the holds slip. It will not necessarily be the same phone number contained in the patron’s record.

112.6.11. Clearing Shelf-Expired Holds

Items with Ready-for-Pickup status are on the Holds Shelf List. The Holds Shelf List can help you manage items on the holds shelf. To see the holds shelf list, select Circulation → Browse Holds Shelf.

The Holds Shelf List is displayed. Note the Actions for Selected Holds are available, as in the patron record.

You can cancel stale holds here.

Use the column picker to add and remove fields from this display. Two fields you may want to display are Shelf Expire Time and Shelf Time.

Check the View Clearable Holds checkbox to list expired holds, wrong-shelf holds and canceled holds only. Expired holds are holds that expired before today’s date.

Click the Print button if you need a printed list. To format the printout customize the Holds_shelf receipt template. This can be done in Admin → Workstation Administration → Receipt Template Editor.

The Clear These Holds button is lit up. Click it and the expired holds will be canceled.

Bring items down from the hold shelf and check them in.

If you cancel a ready-for-pickup hold, you must check in the item to make it available for circulation or trigger the next hold in line.

Hold shelf expire time is inserted when a hold achieves on-hold-shelf status. It is calculated based on the interval entered in Local Admin → Library Settings → Default hold shelf expire interval.

The clear-hold-shelf function cancels shelf-expired holds only. It does not include holds canceled by patron. Staff needs to trace these items manually according to the hold slip date.

112.7. Alternate Hold Pick up Location

Abstract

This feature enables libraries to configure an alternate hold pick up location. The alternate pick up location will appear in the staff client to inform library staff that a patron has a hold waiting at that location. In the stock Evergreen code, the default alternate location is called "Behind Desk". This label can be changed to accommodate a library’s specific hold pick up location. For example, if a library has a drive thru window for hold pick up, the alternate location can be changed to display as "Drive Thru".

Configuration

The alternate pick up location is disabled in Evergreen by default. It can be enabled by setting Holds: Behind Desk Pickup Supported to True in the Library Settings Editor. Server side changes to configuration files are required to enable this feature and edit the alternate pick up location label. The following files and labels need to be changed:

Open-ILS/src/templates/opac/myopac/prefs_settings.tt2

<td><label for='[% setting %]'>[% l('Pickup holds from the drive-thru when possible?') %]</label></td>

Open-ILS/web/opac/locale/en-US/lang.dtd

<!ENTITY staff.patron_display.holds_available_behind_desk.label 'Drive-Thru:'>

Open-ILS/xul/staff_client/server/locale/en-US/circ.properties

staff.circ.utils.hold.behind_desk=Drive-Thru

Open-ILS/xul/staff_client/server/locale/en-US/patron.properties

staff.patron.summary.hold_counts_behind_desk=Available / Total (Drive-Thru)

Libraries can also choose to give patrons the ability to opt-in to pick up holds at the alternate location through their OPAC account. To add this option, set the OPAC/Patron Visible field in the User Setting Type Hold is behind Circ Desk to True. The User Setting Types can be found under Admin → Server Administration → User Setting Types.

Display

When enabled, the alternate pick up location will appear in several places in the staff client. The alternate pick up location and the number of items that are ready for pick up at that location will be displayed in the Patron Account Summary and under the Holds button in the patron account. Staff will also see the general number of holds available and holds placed by the patron.

If configured, patrons will see the option to opt-in to the alternate location in the Account Preferences section of their OPAC Account.

112.8. Display Hold Types on Pull Lists

This feature ensures that the hold type can be displayed on all hold interfaces.

You will find the following changes to the hold type indicator:

The hold type indicator will display by default on all XUL-based hold interfaces. XUL-based hold interfaces are those that number the items on the interface. This can be overridden by saving column configurations that remove the Type column.

The hold type indicator will display by default on the HTML-based pull list. To access, click Circulation → Pull List for Hold Requests → Print Full Pull List (Alternate Strategy).

The hold type indicator can be added to the Simplified Pull List. To access, click Circulation → Pull List for Hold Requests → Simplified Pull List Interface.

To add the hold type indicator to the simplified pull list, click Simplified Pull List Interface, and right click on any of the column headers. The Column Picker appears in a pop up window. Click the box adjacent to Hold Type, and Click Save. The Simplified Pull List Interface will now include the hold type each time that you log into the staff client.

Chapter 113. Booking Module

113.1. Creating a Booking Reservation

Only staff members may create reservations. A reservation can be started from a patron record, or a booking resource. To reserve catalogued items, you may start from searching the catalogue, if you do not know the booking item’s barcode.

113.1.1. To create a reservation from a patron record

1) Retrieve the patron’s record.

2) Select Other -→ Booking -→ Create or Cancel Reservations. This takes you to the Reservations Screen.

3) For non-catalogued items, choose a Bookable Resource Type and click Next. For catalogued items, enter the barcode in Enter the barcode of a catalogued, bookable resource box, then click Next beside the box.

4) For non-catalogued resources, the Bookable Resource Type and the items associated with the type will appear.

For catalogued items, the title and the item will display in the box.

5) Select the date and time for the reservation in I need this resource… area. Click the date field. A calendar widget will be displayed for you to choose a date. Click the time field to choose time from the dropdown list.

If incorrect date and time is selected, the date/time boxes will appear in red. For example, if the time for which the reservation is set has already passed, the boxes will appear in red. There must be at least 15 minutes between the creation of the reservation and the start time of the reservation.

6) For non-catalogued resources, patrons may specify special feature(s), if any, of the resource. With these attributes: allows you to do so. For example, if a patron is booking a laptop he/she can choose between PC and Mac and even choose a specific operating system if they need to. Click the drop down arrow to select your option from the list.

7) Select the pickup location from the dropdown list.

8) If there are multiple copies of the resource and any item listed is acceptable, click Reserve Any. To choose a specific item, select it and then click Reserve Selected.

9) A message will confirm that the action succeeded. Click OK on the prompt.

10) The screen will refresh and the reservation will appear below the patron’s name at the bottom of the screen.

113.1.2. To create a reservation from a booking resource

You need to know the barcode of the patron when you create a reservation for him/her from a booking resource.

1) From the Booking menu, select Create Reservations

2) Choose a Bookable Resource Type and click Next or enter the barcode of a catalogued resource and click Next.

3) For non-catalogued resources, a screen showing the Bookable Resource Type and the items associated with the type will appear.

For catalogued resources, the title and item will appear.

4) Enter the user’s barcode in the Reserve to patron barcode box. The user’s existing reservations, if any, will appear at the bottom of the screen.

5) Select the date and time for the reservation in I need this resource… area. Click the date field. A calendar widget will be displayed for you to choose a date. Click the time field to choose time from the dropdown list.

If incorrect date and time is selected, the date/time boxes will appear in red. For example, if the time for which the reservation is set has already passed, the boxes will appear in red. The times must be set correctly for the reservation to be created. There must be at least 15 minutes between the creation of the reservation and the start time of the reservation.

6) For non-catalogued resources, patrons may specify special feature(s), if any, of the resource. The With these attributes: allows you to do so. For example, if a patron is booking a laptop they can choose between PC and Mac and even choose a specific operating system if they need to. Click the dropdown arrow to select your option from the list.

7) Select the pickup location from the dropdown list.

8) If there are multiple copies of the resource and any item listed is acceptable, click Reserve Any. To choose a specific item, select it and then click Reserve Selected.

9) A message will confirm that the action succeeded. Click OK on the prompt.

10) The screen will refresh and the reservation will appear below the patron’s name at the bottom of the screen.

113.1.3. Search the catalogue to create a reservation

If you would like to reserve a catalogued item but do not know the item barcode, you may start with a catalogue search.

1) In the staff client, select Cataloguing -→ Search the Catalogue or keyboard shortcut F3 to search for the item you wish to reserve. You may search by any bibliographic information.

2) Click the title to display the record summary. In the Copy Summary, select Copy Details in Actions column.

3) The Copy Details will appear in a new row. In the barcode column, click the book now link.

4) A screen showing the title and barcodes of available copies will appear.

5) Enter the user’s barcode in the Reserve to patron barcode box. The user’s existing reservations, if any, will appear at the bottom of the screen.

6) Select the date and time in I need this resource… section. If the date and time set is incorrect the boxes appear in red. For example, if the time for which the reservation is set has already passed, the boxes will appear in red.

7) Select pickup location. If there are multiple copies and any of the listed items is acceptable, click Reserve Any. To choose a specific item, select it and then click Reserve Selected.

8) A message will confirm that the action succeeded. Click OK on the prompt.

9) The screen will refresh, and the reservation will appear below the user’s name.

Reservations on catalogued items can be created on Item Status (F5) screen. Select the item, then Actions for Selected Items → Book Item Now.

113.2. Reservation Pull List

Reservation pull list can be generated dynamically on the Staff Client.

1) To create a pull list, select Booking -→ Pull List.

2) You can decide how many days in advance you would like to pull reserved items. Enter the number of days in the box adjacent to Generate list for this many days hence. For example, if you would like to pull items that are needed today, you can enter 1 in the box, and you will retrieve items that need to be pulled today.

3) Click Fetch to retrieve the pull list.

4) The pull list will appear. Click Print to print the pull list.

113.3. Capturing Items for Reservations

Reservations must be captured before they are ready to be picked up by the patron.

Always capture reservations in Booking Module. Check In function in Circulation does not function the same as Capture Resources.

1) In the staff client, select Booking -→ Capture Resources.

2) Scan the item barcode or type the barcode then click Capture.

3) The message Capture succeeded will appear to the right. Information about the item will appear below the message. Click Print button to print a slip for the reservation.

113.4. Picking Up Reservations

Always use the dedicated Booking Module interfaces for tasks related to reservations. Items that have been captured for a reservation cannot be checked out using the Check Out interface, even if the patron is the reservation recipient.

1) Ready-for-pickup reservations can be listed from Other -→ Booking -→ Pick Up Reservations within a patron record or Booking -→ Pick Up Reservations.

2) Scan the patron barcode if using Booking -→ Pick Up Reservations.

3) The reservation(s) available for pickup will display. Select those you want to pick up and click Pick Up.

4) The screen will refresh to show that the patron has picked up the reservation(s).

113.5. Returning Reservations

When a reserved item is brought back, staff must use the Booking Module to return the reservation.

1) To return reservations, select Booking -→ Return Reservations

2) You can return the item by patron or item barcode. Here we choose Resource to return by item barcode. Scan or enter the barcode, and click Go.

3) A pop up box will tell you that the item was returned. Click OK on the prompt.

4) If we select Patron on the above screen, after scanning the patron’s barcode, reservations currently out to that patron are displayed. Highlight the reservations you want to return, and click Return.

5) The screen will refresh to show any resources that remain out and the reservations that have been returned.

Reservations can be returned from within patron records by selecting Other -→ Booking -→ Return Reservations

113.6. Cancelling a Reservation

A reservation can be cancelled in a patron’s record or reservation creation screen.

113.6.1. Cancel a reservation from the patron record

1) Retrieve the patron’s record.

2) Select Other -→ Booking -→ Create or Cancel Reservations.

3) The existing reservations will appear at the bottom of the screen.

4) Highlight the reservation that you want to cancel. Click Cancel Selected.

Use Shift or Ctrl on keyboard and mouse click to select multiple reservations if needed.

5) A pop-up window will confirm the cancellation. Click OK on the prompt.

6) The screen will refresh, and the cancelled reservation(s) will disappear.

113.6.2. Cancel a reservation on reservation creation screen

1) Access the reservation creation screen by selecting Booking -→ Create Reservations.

2) Select any Bookable Resource Type, then click Next.

3) Scan or type in the patron barcode in Reserve to Patron box then hit Enter.

4) Patron’s existing reservations will display at the bottom of the screen.

5) Select those that you want to cancel, then click Cancel Selected.

Chapter 114. Circulation - Patron Record

114.1. Searching Patrons

To search for a patron, select Search → Search for Patrons from the menu bar.

The Patron Search screen will display. It will contain options to search on the following fields:

Last Name

First Name

Middle Name

Next to the Clear Form button there is a button with an arrow pointing down that will display the following additional search fields:

Barcode

Alias

Username

Email

Identification

database ID

Phone

Street 1

Street 2

City

State

Postal Code

Profile Group

Home Library

You patrons searches may also include patrons marked “inactive” if you click on the Include Inactive? checkbox.

[Tip]
Tips for searching

Search one field or combine fields for more precise results.

Truncate search terms for more search results.

Search ignores punctuation such as diacritics, apostrophes, hyphens and commas.

Once you have located the desired patron, click on the entry row for this patron in the results screen. A summary for this patron will display on the left hand side.

The Patron Search button on the upper right may be used to resume searching for patrons.

114.2. Registering New Patrons

To register a new patron, select Circulation → Register Patron from the menu bar. The Patron Registration form will display.

Mandatory fields display in yellow.

The Show Only Required Fields and Show Suggested Fields may be used to limit the options on this page.

When one of these options is selected, it is possible switch to the other limited view or to revert to the original view by selecting Show All Fields.

When finished entering the necessary information, select Save to save the new patron record or Save & Clone to register a patron with the same address. When Save & Clone is selected, the address information is copied into the resulting patron registration screen. It is linked to the original patron. Address information may only be edited through the original record.

Requested fields may be configured in the Library Settings Editor (Admin → Local Admin → Library Settings Editor).

Statistical categories may be created for information tracked by your library that is not in the default patron record.

These may be configured in the Statistical Categories Editor (Admin → Local Admin → Statistical Categories Editor).

Staff accounts may also function as patron accounts.

You must select a Main (Profile) Permission Group before the Update Expire Date button will work, since the permission group determines the expiration date.

114.3. Patron Self-Registration

Abstract

Patron Self-Registration allows patrons to initiate registration for a library account through the OPAC. Patrons can fill out a web-based form with basic information that will be stored as a “pending patron” in Evergreen. Library staff can review pending patrons in the staff-client and use the pre-loaded account information to create a full patron account. Pending patron accounts that are not approved within a configurable amount of time will be automatically deleted.

Patron Self-Registration

In the OPAC, click on the link to Request Library Card

Fill out the self-registration form to request a library card, and click Submit Registration.

Patrons will see a confirmation message: “Registration successful! Please see library staff to complete your registration.”

Managing Pending Patrons

In the staff client select Circulation → Pending Patrons.

Select the patron you would like to review. In this screen you have the option to Load the pending patron information to create a permanent library account.

To create a permanent library account for the patron, click on the patron’s row, click on the Load Patron button at the top of the screen. This will load the patron self-registration information into the main Patron Registration form.

Fill in the necessary patron information for your library, and click Save to create the permanent patron account.

114.4. Updating Patron Information

Retrieve the patron record as described in the section Searching Patrons.

Click on Edit from the options that display at the top of the patron record.

Edit information as required. When finished, select Save.

After selecting Save, the page will refresh. The edited information will be reflected in the patron summary pane.

To quickly renew an expired patron, click the Update Expire Date button. You will need a Main (Profile) Permission Group selected for this to work, since the permission group determines the expiration date.

114.5. Renewing Library Cards

Expired patron accounts when initially retrieved – an alert stating that the “Patron account is EXPIRED.”

Open the patron record in edit mode as described in the section Updating Patron Information.

Navigate to the information field labeled Privilege Expiration Date. Enter a new date in this box. When you place your cursor in the Patron Expiration Date box, a calendar widget will display to help you easily navigate to the desired date.

Select the date using the calendar widget or key the date in manually. Click the Save button. The screen will refresh and the “expired” alerts on the account will be removed.

114.6. Lost Library Cards

Retrieve the patron record as described in the section Searching Patrons.

Open the patron record in edit mode as described in the section Updating Patron Information.

Next to the Barcode field, select the Replace Barcode button.

This will clear the barcode field. Enter a new barcode and Save the record. The screen will refresh and the new barcode will display in the patron summary pane.

If a patron’s barcode is mistakenly replaced, the old barcode may be reinstated. Retrieve the patron record as described in the section Searching Patrons. Open the patron record in edit mode as described in the section Updating Patron Information.

Select the See All button next to the Replace Barcode button. This will display the current and past barcodes associated with this account.

Check the box(es) for all barcodes that should be “active” for the patron. An “active” barcode may be used for circulation transactions. A patron may have more than one “active” barcode. Only one barcode may be designated “primary.” The “primary” barcode displays in the patron’s summary information in the Library Card field.

Once you have modified the patron barcode(s), Save the patron record. If you modified the “primary” barcode, the new primary barcode will display in the patron summary screen.

114.7. Resetting Patron’s Password

A patron’s password may be reset from the OPAC or through the staff client. To reset the password from the staff client, retrieve the patron record as described in the section Searching Patrons.

Open the patron record in edit mode as described in the section Updating Patron Information.

Select the Reset Password button next to the Password field.

The existing password is not displayed in patron records for security reasons.

A new number will populate the Password and Verify Password text boxes. Make note of the new password and Save the patron record. The screen will refresh and the new password will be suppressed from view.

If you need to change a patron or staff account password without using the staff client, here is how you can reset it with SQL.

Connect to your Evergreen database using psql or similar tool, and retreive and verify your admin username:

psql -U <user-name> -h <hostname> -d <database>

SELECT id, usrname, passwd from actor.usr where usrname = 'admin';

If you do not remember the username that you set, search for it in the actor.usr table, and then reset the password.

UPDATE actor.usr SET passwd = <password> WHERE id=<id of row to be updated>;

The new password will automatically be hashed.

114.8. Barring a Patron

A patron may be barred from circulation activities. To bar a patron, retrieve the patron record as described in the section Searching Patrons.

Open the patron record in edit mode as described in the section Updating Patron Information.

Check the box for Barred in the patron account.

Save the user. The screen will refresh.

Barring a patron from one library bars that patron from all consortium member libraries.

To unbar a patron, uncheck the Barred checkbox.

114.9. Barred vs. Blocked

Barred: Stops patrons from using their library cards; alerts the staff that the patron is banned/barred from the library. The “check-out” functionality is disabled for barred patrons (NO option to override – the checkout window is unusable and the bar must be removed from the account before the patron is able to checkout items).  These patrons may still log in to the OPAC to view their accounts.

Blocked: Often, these are system-generated blocks on patron accounts. 

Some examples:

Patron exceeds fine threshold

Patron exceeds max checked out item threshold

A notice appears when a staff person tries to checkout an item to blocked patrons, but staff may be given permissions to override blocks.

114.10. Staff-Generated Messages

There are several types of messages available for staff to leave notes on patron records.

Patron Notes: These notes are added via Other → Notes in the patron record. These notes can be viewable by staff only or shared with the patron. Staff initials can be required. (See the section Patron Notes for more.)

Patron Alerts: This type of alert is added via Edit button in the patron record. There is currently no way to require staff initials for this type of alert. (See the section Patron Alerts for more.)

Staff-Generated Penalties/Messages: These messages are added via the Messages button in the patron record. They can be a note, alert or block. Staff initials can be required. (See the section Staff-Generated Penalties/Messages for more.)

114.11. Patron Alerts

When an account has an alert on it, a Stop sign is displayed when the record is retrieved.

Navigating to an area of the patron record using the navigation buttons at the top of the record (for example, Edit or Bills) will clear the message from view.

If you wish to view these alerts after they are cleared from view, they may be retrieved. Use the Other menu to select Display Alert and Messages.

There are two types of Patron Alerts:

System-generated alerts: Once the cause is resolved (e.g. patron’s account has been renewed), the message will disappear automatically.

Staff-generated alerts: Must be added and removed manually.

To add an alert to a patron account, retrieve the patron record as described in the section Searching Patrons.

Open the patron record in edit mode as described in the section Updating Patron Information.

Enter the alert text in the Alert Message field.

Save the record. The screen will refresh and the alert will display.

To remove the alert, retrieve the patron record as described in the section Searching Patrons.

Open the patron record in edit mode as described in the section Updating Patron Information.

Delete the alert text in the Alert Message field.

Save the record.

The screen will refresh and the indicators for the alert will be removed from the account.

114.12. Patron Notes

Notes are strictly communicative and may be made visible to the patron via their account on the OPAC. In the OPAC, these notes display on the account summary screen in the OPAC.

To insert or remove a note, retrieve the patron record as described in the section Searching Patrons.

Open the patron record in edit mode as described in the section Updating Patron Information.

Use the Other menu to navigate to Notes.

Select the Add New Note button. A Create a new note window displays.

To add a box in the Add Note window for staff initials and require their entry, see the "Require staff initials…" settings in the Library Settings Editor section.

Enter note information.

Select the check box for Patron Visible to display the note in the OPAC.

Select OK to save the note to the patron account.

To delete a note, go to Other → Notes and use the Delete button on the right of each note.

114.13. Staff-Generated Penalties/Messages

To access this feature, use the Messages button in the patron record.

114.13.1. Add a Message

Click Apply Penalty/Message to begin the process of adding a message to the patron.

There are three options: Notes, Alerts, Blocks

Note: This will create a non-blocking, non-alerting note visible to staff. Staff can view the message by clicking the Messages button on the patron record. (Notes created in this fashion will not display via Other → Notes, and cannot be shared with the patron. See the Patron Notes section for notes which can be shared with the patron.)

Alert: This will create a non-blocking alert which appears when the patron record is first retrieved. The alert will cause the patron name to display in red, rather than black, text. Alerts may be viewed by clicking the Messages button on the patron record or by selecting Other → Display Alerts and Messages.

Block: This will create a blocking alert which appears when the patron record is first retrieved, and which behaves much as the non-blocking alert described previously. The patron will be also blocked from circulation, holds and renewals until the block is cleared by staff.

After selecting the type of message to create, enter the message body into the box. If Staff Initials are required, they must be entered into the Initials box before the message can be added. Otherwise, fill in the optional Initials box and click OK

The message should now be visible in the Staff-Generated Penalties/Messages list. If a blocking or non-blocking alert, the message will also display immediately when the patron record is retrieved.

114.13.2. Modify a Message

Messages can be edited by staff after they are created.

Click to select the message to be modified, then click Actions → Modify Penalty/Message. This menu can also be accessed by right-clicking in the message area.

To change the type of message, click on Note, Alert, Block to select the new type. Edit or add new text in the message body. Enter Staff Initials into the Initials box (may be required.) and click OK to submit the alterations.

114.13.3. Archive a Message

Messages which are no longer current can be archived by staff. This action will remove any alerts or blocks associated with the message, but retains the information contained there for future reference.

Click to select the message to be archived, then click Actions → Archive Penalty/Message. This menu can also be accessed by right-clicking in the message area.

Archived messages will be shown in the section labelled Archived Penalties/Messages. To view messages, click Retrieve Archived Penalties. By default, messages archived within the past year will be retrieved. To retrieve messages from earlier dates, change the start date to the desired date before clicking Retrieve Archived Penalties.

114.13.4. Remove a Message

Messages which are no longer current can be removed by staff. This action removes any alerts or blocks associated with the message and deletes the information from the system.

Click to select the message to be removed, then click Actions → Remove Penalty/Message. This menu can also be accessed by right-clicking in the message area.

Chapter 115. Triggered Events and Notices

Improvements to the Triggered Events interface enables you to easily filter, sort, and print triggered events from the patron’s account or an item’s details. This feature is especially useful when tracking notice completion from a patron’s account.

115.1. Access and View

You can access Triggered Events from two Evergreen interfaces: a patron’s account or an item’s details.

To access this interface in the patron’s account, open the patron’s record and click Other → Triggered Events.

To access this interface from the item’s details, enter the item barcode into the Item Status screen, and click Actions for Selected Items → Triggered Events.

Information about the patron, the item, and the triggered event appear in the center of the screen. Add or delete columns to the display by right clicking on any column. The Column Picker appears in a pop up box and enables you to select the columns that you want to display.

115.2. Filter

The triggered events that display are controlled by the filters on the right side of the screen. By default, Evergreen displays completed circulation events. Notice that the default filters display Event State is Complete and Core Type is Circ.

To view completed hold-related events, such as hold capture or hold notice completion, choose Event State is Complete and Core Type is Hold from the drop down menu.

You can also use the Event State filter to view circs and holds that are pending or have an error.

Add and delete filters to customize the list of triggered events that displays. To add another filter, click Add Row. To delete a filter, click the red X adjacent to a row.

115.3. Sort

You can sort your results by clicking the column name.

115.4. Print

You can select the events that you want to print, or you can print all events. To print selected events, check the boxes adjacent to the events that you want to print, and click Print Selected Events. To print all events, simply click Print All Events.

115.5. Reset

If the triggered event does not complete or the notice is not sent and the trigger needs to be run again, then select the event, and click Reset Selected Events.

Chapter 116. Offline Transactions

Evergreen’s Standalone Interface / Offline Interface is designed to log transactions during network outage, which can be uploaded and processed once network operations are restored.

The terms Offline Interface and Standalone Interface mean the same thing: a separate program to handle simple circulation tasks while the network is down.

To access the Offline Interface, navigate to the Staff Client login screen and click Standalone Interface. The Evergreen Standalone Interface window opens.

116.1. Patron Registration

Patron registration on the Evergreen Offline Interface records the minimum patron information necessary to register a new patron.

All of the fields, except for Line 2 of Billing Address, on the Patron Registration screen are required. If your library does not record information for any field, you need to work out a standard fake value for it, for example, 1900-01-01 for Date of Birth.

The account password is automatically generated. Patrons can access their account with the password after the offline transactions are uploaded and processed.

To register a patron:

Click Register Patron on the top menu bar. The Patron Registration window opens.

Fill in the form with patron information, using the drop down list if available.

Click Save patron registration. A confirmation dialog opens.

Click OK to finish registering the patron.

116.2. Checking Out Items

To circulate items from the Evergreen standalone interface:

Click Check Out on the top menu bar. The Standalone Check Out screen opens.

Ensure that the date on the left-hand side of the menu bar is correct.

Enter the patron’s library card barcode in the Enter the patron’s barcode field by scanning or typing the barcode.

Ensure that the due date is correct in the Enter the item due date field. You may enter a different due date manually, or select a different duration from the dropdown list to select a relative due date based on the loan period.

Check out items:

For cataloged items, scan each item’s barcode in Enter the item barcode field. The barcode appears on the right side of the screen.

For non-cataloged items:

Click Choose a non-barcode option to select a non-catalogued category from the drop-down list.

Enter the number of items you want to check out, then click OK on the prompt window.

Scan all items, changing the due date if necessary.

To print a receipt, select the Print receipt? checkbox.

Click Save these transactions.

The default dates are based on your computer settings.

Pre-catalogued item circulation is not available on Offline Interface. If an existing pre-cat barcode happens to be used, it is checked out with the previous author and title. If a new pre-cat barcode is attempted, an error of ASSET NOT FOUND (item not found) is returned upon processing offline transactions.

116.3. Renew

To renew an item, you must know the item’s barcode number. The patron’s barcode is optional.

To renew items from the Evergreen standalone interface:

Click Renew on the top menu bar.

The Renew window is very similar to the Check Out window. The differences are that a patron’s barcode is optional on the Renew window, and the non-barcoded option is not available on the Renew window, as non-barcoded items can not be renewed.

Ensure that the date on the left-hand side of the menu bar is correct.

(Optional): Enter the patron’s library card barcode in the Enter the patron’s barcode field by scanning or typing the barcode.

Ensure that the due date is correct in the Enter the item due date field. You may enter a different due date manually, or select a different duration from the dropdown list to select a relative due date based on the loan period.

For each item to be renewed, enter the item’s barcode in the Enter the item barcode field. The barcode appears on the right side of the screen.

To print a receipt, select the Print receipt? checkbox.

Click Save these transactions.

116.4. In-house Use

To record in-house use transactions from the Evergreen standalone interface:

Click In House Use on the top menu bar.

Ensure the date is correct.

Enter the number of uses to record for the item in the Enter the number of uses of the item field.

Enter the item barcode number in the Enter the item barcode field.

Repeat the previous 2 steps until all items have been scanned.

To print a receipt, select the Print receipt? checkbox.

Click Save these transactions.

116.5. Check In

To check in items from the Evergreen standalone interface:

Click Check In on the top menu bar. The Check In screen opens.

Ensure the date is correct.

For each item you want to check in, enter the item’s barcode in the Enter item barcode field. The number is displayed on the right side of the screen.

To print a receipt, select the Print receipt? checkbox.

Click Save these transactions.

Without access to Evergreen database, items on holds or with special status will not be captured in offline mode.

116.6. Uploading Offline Transactions

Once you are able to connect to the server, you need to upload the offline transactions. To avoid confusion for patrons and in the system, you should upload the offline transactions as soon as possible.

Once you can connect to the server, there are 3 steps to uploading offline transactions:

Create a session: to be done by local system administrators at an administration workstation.

Upload transactions to a session: to be done by circulation staff at circulation workstations.

Process the uploaded transactions: to be done by local system administrators at an administration workstation.

Once network connectivity has been restored, a local system administrator must create an offline transaction session. Then, staff can upload transactions from each of the workstations used in offline circulation mode to that session. Once all of the branch workstations have uploaded their transactions to the session, the manager processes all the transactions from all the workstations at once.

Uploading transactions to the session does not put the transactions into the Evergreen database. The transactions will not be sent to the Evergreen database until the manager processes the session.

116.6.1. Creating an Offline Session

In the Evergreen staff client:

Log into Evergreen using an account with local system administrator privileges.

Select Admin (-) → Offline Transaction Management from the menu. The Offline Transactions screen opens. Previously created sessions are listed in the Offline Sessions section.

In the upper Offline Sessions section, click Create to create a new session.

Enter a name for the session, like Internet Down 2012-12-02. Click OK.

In the Offline Sessions section, highlight the session you created. An Uploaded Transactions section appears in the bottom of the screen. Initially, this section is empty.

Inform library staff that the session has been created and tell them the name of the session.

116.6.2. Uploading Workstation Transactions to a Session

Wait until the local system administrator has created a session and told you that it’s ready for your upload. There may be several sessions shown on the Offline Transaction Management screen, so you will need the name of the correct session from your local system administrator.

Each workstation used to perform offline circulation during the outage must upload its transactions to the offline transaction session.

To upload offline transaction from a workstation to a session, perform the following steps in the Evergreen staff client:

Log into Evergreen with your regular username and password.

Select Admin (-) → Offline Transaction Management from the menu. The Offline Transactions screen opens. You should see at least one session in the Offline Sessions section. You may also see older sessions.

In the upper Offline Sessions section, highlight the correct session, then click Upload. The transactions are transferred to the Evergreen server.

When the transactions have been uploaded, select the session in the Offline Sessions section. The value in the Upload Count column has increased by 1 and your workstation is now listed in the Uploaded Transactions section.

Inform your local system administrator that your transaction has been uploaded to the session.

116.6.3. Processing the Transactions

When all of the participating staff workstations have uploaded their transactions to the offline session, the workstation names are listed in the Uploaded Transactions section. To process the offline transactions and make them live on the Evergreen server:

Log into Evergreen using an account with local system administrator privileges.

Select Admin (-) → Offline Transaction Management from the menu. The Offline Transactions screen opens. Previously created sessions are listed in the Offline Sessions section.

Highlight the correct session and, if necessary, click Refresh to verify all the participating workstations have uploaded their transactions to your session.

Click Process. The processing may take some time to complete, depending on how many transactions you have done. Click Refresh to see the updated status of the processing step. Processing is complete when the Processing? column shows Completed.

The number in the Transactions Processed column is equal to the number of items checked out or checked in. For example, 5 transactions processed could mean that:

5 items were checked out, or

3 items were checked in and 2 items were checked out, or

5 items were checked in.

116.6.4. Exceptions

Exceptions are problems that were encountered during processing. For example, a mis-scanned patron barcode, an open circulation, or an item that was not checked in before it was checked out to another patron would be listed as an exception. Those transactions causing exceptions may not be loaded into Evergreen database. Staff should examine the exceptions and take necessary action.

These are a few notes about possible exceptions. It is not an all-inclusive list.

Checking out a DVD with the wrong date (leaving due date set at +2 weeks instead of +1 week) does not cause an exception.

Overdue books are not flagged as exceptions.

Checking out a reference book does not cause an exception.

Checking out an item belonging to another library does not cause an exception.

The Standalone Interface does not recognize books on hold, so no exceptions will be generated when matching items are checked in or checked out.

The Standalone Interface can recognize blocked, barred, and expired patrons, as well as lost cards, if you have recently run an Admin (-) → Download Offline Patron List action on the workstation on which you are using the Standalone Interface. You will get an error message indicating the patron status from within the Standalone Interface at check-out time.

116.6.4.1. Common error messages

ROUTE-ITEM - Indicates the book should be routed to another branch or library system. You’ll need to find the book and re-check it in (online) to get the Transit Slip to print.

COPY_STATUS_LOST - Indicates a book previously marked as lost was found and checked in.

CIRC_CLAIMS_RETURNED - Indicates a book previously marked as claimed-returned was found and checked in.

ASSET_COPY_NOT_FOUND - Indicates the item barcode was mis-scanned/mis-typed.

ACTOR_CARD_NOT_FOUND - Indicates the patron’s library barcode was mis-scanned/ mis-typed.

OPEN_CIRCULATION_EXISTS - Indicates a book was checked out that had never been checked in.

MAX_RENEWALS_REACHED - Indicates the item has already been renewed the maximum times allowed (or it’s a video/DVD).

Chapter 117. Self checkout

Evergreen includes a self check interface designed for libraries that simply want to record item circulation without worrying about security mechanisms like magnetic strips or RFID tags.

117.1. Initializing the self check

The self check interface runs in a web browser. Before patrons can use the self check station, a staff member must initialize the interface by logging in.

Open your self check interface page in a web browser. By default, the URL is https://[hostname]/eg/circ/selfcheck/main, where [hostname] represents the host name of your Evergreen web server.

Log in with a staff account with circulation permissions.

117.1.1. Setting library hours of operation

When the self check prints a receipt, the default template includes the library’s hours of operation in the receipt. If the library has no configured hours of operation, the attempt to print a receipt fails and the browser hangs.

117.1.2. Configuring self check behavior

Several library settings control the behavior of the self check:

Audio Alerts: Plays sounds when events occur in the self check. These events are defined in the templates/circ/selfcheck/audio_config.tt2 template. To use the default sounds, you could run the following command from your Evergreen server as the root user (assuming that /openils/ is your install prefix):

cp -r /openils/var/web/xul/server/skin/media/audio /openils/var/web/.

Block copy checkout status: Prevent the staff user’s permission override from enabling patrons to check out items that they would not normally be able to check out, such as the "On reservation shelf" status. The status IDs are found in the config.copy_status database table.

Patron Login Timeout: Automatically logs the patron out of the self check after a certain period of inactivity. NOT CURRENTLY SUPPORTED

Pop-up alert for errors: In addition to displaying an alert message on the screen, this setting raises patron awareness of possible problems by raising an alert box that the patron must dismiss before they can check out another item.

Require Patron Password: By default, users can enter either their user name or barcode, without having to enter their password, to access their account. This setting requires patrons to enter their password for additional security.

Workstation Required: If set, the URL must either include a ?ws=[workstation] parameter, where [workstation] is the name of a registered Evergreen workstation, or the staff member must register a new workstation when they login. The workstation parameter ensures that check outs are recorded as occurring at the correct library.

117.2. Basic Check Out

Patron scans their barcode.

Optional Patron enters their account password.

Patron scans the barcodes for their items OR Patron places items, one at a time, on the RFID pad.

Items will be listed below with a check out confirmation message.

If a check out fails a message will advise patrons.

Patron clicks Logout to print a checkout receipt and logout. OR Patron clicks Logout (No Receipt) to logout with no receipt.

If the patron forgets to logout the system will automatically log out after the time period specified in the library setting Patron Login Timeout (in seconds). An inactivity pop-up will appear to warn patrons 20 seconds before logging out.

117.3. View Items Out

Patrons are able to view the items they currently have checked out by clicking View Items Out

The items currently checked out will display with their due dates. Using the Print List button patrons can print out a receipt listing all of the items they currently have checked out.

117.4. View Holds

Patrons are able to view their current holds by clicking View Holds

Items currently on hold display. Patrons can also see which, if any, items are ready for pickup.

Using the Print List button patrons can print out a receipt listing all of the items they currently have on hold.

117.5. View Fines

Patrons are able to view the fines they currently owe by clicking View Details

Current fines owed by the patron display.

Chapter 118. RFID Product Integration

118.1. Evergreen Integration with PV Supa GoodStuff RFID Reader

This feature enables the Evergreen staff client to "talk" to the PV Supa Goodstuff RFID reader so that libraries can utilize PV Supa Goodstuff’s RFID technology when checking items in and out.

Administration

To use PV Supa Goodstuff, you must add code to the Admin module that Evergreen can use to identify the reader.

Click Admin → Workstation Admin → Server Add-ons.

Enter the code, pv_supa_goodstuff, to identify PV Supa Goodstuff in the Active Server Add-Ons field.

Click Update Active Add-Ons.

Look at the next field, Add-on Preferences. Enter information in the GoodStuff tab.

Check the Enabled check box to enable this add-on.

Enter the IP/Hostname of the hardware.

Enter the port.

Click Update.

Using RFID at the Circulation Desk

RFID functionality is available in the Circulation module via the check-out interface, the check-out function in the patron account, and the check-in interface.

From the Check-Out interface (F1):

Check the RFID checkbox if your library cards have embedded RFID chips that Evergreen can use to retrieve the patron barcode. RFID check boxes appear only if appropriate code words have been added in the Server Add-Ons.

Place the patron’s library card and/or item(s) on the PV Supa Goodstuff Reader. Evergreen will take you to the patron’s account. If item(s) with RFID chips have also been placed on the reader, and the corresponding checkbox is checked, then Evergreen will scan the item(s) into the patron’s account.

RFID check boxes are sticky, so if you have checked an RFID box once, then it will continue to be checked when you re-open the interface.

If you do not use RFID chips to retrieve patrons' accounts, then leave the RFID box unchecked. You can scan a patron barcode with a barcode scanner, and Evergreen will retrieve the patron data without using the RFID feature. From the patron’s account, Evergreen can check out items using the RFID reader. See the next section for details.

Click Done to complete the transaction, or close the window.

From the Check-Out tab in a patron’s record:

Open a patron’s record, and stack the item(s) to be checked out on the RFID reader. To retrieve item data using the RFID chips embedded in the item barcodes, click the RFID check box at the bottom of the patron account. When this box is checked, Evergreen will read the item(s) that are stacked on the RFID reader, check out the item(s), and disable the security bits.

Click Done to complete the transaction, or close the window.

Evergreen pop-up messages, such as an Alert Message or Item Already Circulating may appear during transactions. Two new dialogs specific to PV Supa Goodstuff may also appear. One dialog, Incomplete Sets, allows you to continue checking out an incomplete set, such as a CD collection, or you can ask the hardware to rescan the RFID tags to look again for a full set. The second dialog allows you to manually attempt to set or unset the security bit on an item if the automatic attempt failed.

From the Check In interface:

Click the RFID check box.

Place the items on the PV Supa Goodstuff Reader.

Evergreen will tell the reader to check in the item(s) and enable the security bits. The item(s) appear in a list on the screen.

Part XII. Reports

Chapter 119. Introduction

Learn how to create and use reports in Evergreen.

Chapter 120. Starting and Stopping the Reporter Daemon

Before you can view reports, the Evergreen administrator must start the reporter daemon from the command line of the Evergreen server.

The reporter daemon periodically checks for requests for new reports or scheduled reports and gets them running.

120.1. Starting the Reporter Daemon

To start the reporter daemon, run the following command as the opensrf user:

clark-kent.pl --daemon

You can also specify other options:

sleep=interval: number of seconds to sleep between checks for new reports to run; defaults to 10

lockfile=filename: where to place the lockfile for the process; defaults to /tmp/reporter-LOCK

concurrency=integer: number of reporter daemon processes to run; defaults to 1

boostrap=filename: OpenSRF bootstrap configuration file; defaults to /openils/conf/opensrf_core.xml

The open-ils.reporter process must be running and enabled on the gateway before the reporter daemon can be started.

Remember that if the server is restarted, the reporter daemon will need to be restarted before you can view reports unless you have configured your server to start the daemon automatically at start up time.

120.2. Stopping the Reporter Daemon

To stop the reporter daemon, you have to kill the process and remove the lockfile. Assuming you’re running just a single process and that the lockfile is in the default location, perform the following commands as the opensrf user:

kill `ps wax | grep "Clark Kent" | grep -v grep | cut -b1-6`

rm /tmp/reporter-LOCK

Chapter 121. Folders

There are three main components to reports: Templates, Reports, and Output. Each of these components must be stored in a folder. Folders can be private (accessible to your login only) or shared with other staff at your library, other libraries in your system or consortium. It is also possible to selectively share only certain folders and/or subfolders.

There are two parts to the folders pane. The My Folders section contains folders created with your Evergreen account. Folders that other users have shared with you appear in the Shared Folders section under the username of the sharing account.

121.1. Creating Folders

Whether you are creating a report from scratch or working from a shared template you must first create at least one folder.

The steps for creating folders are similar for each reporting function. It is easier to create folders for templates, reports, and output all at once at the beginning, though it is possible to do it before each step. This example demonstrates creating a folder for a template.

Click on Templates in the My Folders section.

Name the folder. Select Share or Do not share from the dropdown menu.

If you want to share your folder, select who you want to share this folder with from the dropdown menu.

Click Create Sub Folder.

Click OK.

Next, create a folder for the report definition to be saved to. Click on Reports.

Repeat steps 2-5 to create a Reports folder also called Circulation.

Finally, you need to create a folder for the report’s output to be saved in. Click on Output.

Repeat steps 2-5 to create an Output folder named Circulation.

Using a parallel naming scheme for folders in Templates, Reports, and Output helps keep your reports organized and easier to find

The folders you just created will now be visible by clicking the arrows in My Folders. Bracketed after the folder name is whom the folder is shared with. For example, Circulation (BNCLF) is shared with the North Coast Library Federation. If it is not a shared folder there will be nothing after the folder name. You may create as many folders and sub-folders as you like.

121.2. Managing Folders

Once a folder has been created you can change the name, delete it, create a new subfolder, or change the sharing settings. This example demonstrates changing a folder name; the other choices follow similar steps

Click on the folder that you wish to rename.

Click Manage Folder.

Select Change folder name from the dropdown menu and click Go.

Enter the new name and click Submit.

Click OK.

You will get a confirmation box that the Action Succeeded. Click OK.

Chapter 122. Creating Templates

Once you have created a folder, the next step in building a report is to create or clone a template. Templates allow you to run a report more than once without building it anew every time, by changing definitions to suit current requirements. For example, you can create a shared template that reports on circulation at a given library. Then, other libraries can use your template and simply select their own library when they run the report.

It may take several tries to refine a report to give the output that you want. It can be useful to plan out your report on paper before getting started with the reporting tool. Group together related fields and try to identify the key fields that will help you select the correct source.

It may be useful to create complex queries in several steps. For example, first add all fields from the table at the highest source level. Run a report and check to see that you get results that seem reasonable. Then clone the report, add any filters on fields at that level and run another report. Then drill down to the next table and add any required fields. Run another report. Add any filters at that level. Run another report. Continue until you’ve drilled down to all the fields you need and added all the filters. This might seem time consuming and you will end up cloning your initial report several times. However, it will help you to check the correctness of your results, and will help to debug if you run into problems because you will know exactly what changes caused the problem. Also consider adding extra fields in the intermediate steps to help you check your results for correctness.

This example illustrates creating a template for circulation statistics. This is an example of the most basic template that you can create. The steps required to create a template are the same every time, but the tables chosen, how the data is transformed and displayed, and the filters used will vary depending on your needs.

122.1. Choosing Report Fields

Click on the My Folder template folder where you want the template to be saved.

Click on Create a new Template for this folder.

You can now see the template creating interface. The upper half of the screen is the Database Source Browser. The top left hand pane contains the database Sources drop-down list. This is the list of tables available as a starting point for your report. Commonly used sources are Circulation (for circ stats and overdue reports), ILS User (for patron reports), and Item (for reports on a library’s holdings).

The Enable source nullability checkbox below the sources list is for advanced reporting and should be left unchecked by default.

Select Circulation in the Sources dropdown menu. Note that the Core Sources for reporting are listed first, however it is possible to access all available sources at the bottom of this dropdown menu. You may only specify one source per template.

Click on Circulation to retrieve all the field names in the Field Name pane. Note that the Source Specifier (above the middle and right panes) shows the path that you took to get to the specific field.

Select Circ ID in the middle Field Name pane, and Count Distinct from the right Field Transform pane. The Field Transform pane is where you choose how to manipulate the data from the selected fields. You are counting the number of circulations.

Field Transforms have either an Aggregate or Non-Aggregate output type. See the section called Field Transforms for more about Count, _Count Distinct, and other transform options.

Click Add Selected Fields underneath the Field Transform pane to add this field to your report output. Note that Circ ID now shows up in the bottom left hand pane under the Displayed Fields tab.

Circ ID will be the column header in the report output. You can rename default display names to something more meaningful. To do so in this example, select the Circ ID row and click Alter Display Header.

Double-clicking on the displayed field name is a shortcut to altering the display header.

Type in the new column header name, for example Circ count and click OK.

Add other data to your report by going back to the Sources pane and selecting the desired fields. In this example, we are going to add Circulating Item -→ Shelving Location to further refine the circulation report.

In the top left hand Sources pane, expand Circulation. Depending on your computer you will either click on the + sign or on an arrow to expand the tree.

Click on the + or arrow to expand Circulating Item. Select Shelving Location.

When you are creating a template take the shortest path to the field you need in the left hand Sources pane. Sometimes it is possible to find the same field name further in the file structure, but the shortest path is the most efficient.

In the Field Name pane select Name.

In the upper right Field Transform pane, select Raw Data and click Add Selected Fields. Use Raw Data when you do not wish to transform field data in any manner.

Name will appear in the bottom left pane. Select the Name row and click Alter Display Header.

Enter a new, more descriptive column header, for example, Shelving location. Click OK.

Note that the order of rows (top to bottom) will correspond to the order of columns (left to right) on the final report. Select Shelving location and click on Move Up to move Shelving location before Circ count.

Return to the Sources pane to add more fields to your template. Under Sources click Circulation, then select Check Out Date/Time from the middle Field Name pane.

Select Year + Month in the right hand Field Transform pane and click Add Selected Fields

Check Out Date/Time will appear in the Displayed Fields pane. In the report it will appear as a year and month (YYYY-MM) corresponding to the selected tranform.

Select the Check Out Date/Time row. Click Alter Display Header and change the column header to Check out month.

Move Check out month to the top of the list using the Move Up button, so that it will be the first column in an MS Excel spreadsheet or in a chart. Report output will sort by the first column.

Note the Change Transform button in the bottom left hand pane. It has the same function as the upper right Field Transform pane for fields that have already been added.

122.2. Applying Filters

Evergreen reports access the entire database, so to limit report output to a single library or library system you need to apply filters.

After following the steps in the previous section you will see three fields in the bottom left hand Template Configuration pane. There are three tabs in this pane: Displayed Fields (covered in the previous section), Base Filters and Aggregate Filters. A filter allows you to return only the results that meet the criteria you set.

Base Filters apply to non-aggregate output types, while Aggregate Filters are used for aggregate types. In most reports you will be using the Base Filters tab. For more information on aggregate and non-aggregate types see the section called “Field Transforms”.

There are many available operators when using filters. Some examples are Equals, In list, is NULL, Between, Greater than or equal to, and so on. In list is the most flexible operator, and in this case will allow you flexibility when running a report from this template. For example, it would be possible to run a report on a list of timestamps (in this case will be trimmed to year and month only), run a report on a single month, or run a report comparing two months. It is also possible to set up recurring reports to run at the end of each month.

In this example we are going to use a Base Filter to filter out one library’s circulations for a specified time frame. The time frame in the template will be configured so that you can change it each time you run the report.

122.2.1. Using Base Filters

Select the Base Filters tab in the bottom Template Configuration pane.

For this circulation statistics example, select Circulation -→ Check Out Date/Time -→ Year + Month and click on Add Selected Fields. You are going to filter on the time period.

Select Check Out Date/Time. Click on Change Operator and select In list from the dropdown menu.

To filter on the location of the circulation select Circulation -→ Circulating library -→ Raw Data and click on Add Selected Fields.

Select Circulating Library and click on Change Operator and select Equals. Note that this is a template, so the value for Equals will be filled out when you run the report.

For multi-branch libraries, you would select Circulating Library with In list as the operator, so you could specify the branch(es) when you run the report. This leaves the template configurable to current requirements. In comparison, sometimes you will want to hardcode true/false values into a template. For example, deleted bibliographic records remain in the database, so perhaps you want to hardcode deleted=false, so that deleted records don’t show up in the results. You might want to use deleted=true, for a template for a report on deleted items in the last month.

Once you have configured your template, you must name and save it. Name this template Circulations by month for one library. You can also add a description. In this example, the title is descriptive enough, so a description is not necessary. Click Save.

Click OK.

You will get a confirmation dialogue box that the template was successfully saved. Click OK.

After saving it is not possible to edit a template. To make changes you will need to clone it and edit the clone

The bottom right hand pane is also a source specifier. By selecting one of these rows you will limit the fields that are visible to the sources you have specified. This may be helpful when reviewing templates with many fields. Use Ctrl+Click to select or deselect items.

Chapter 123. Generating Reports from Templates

Now you are ready to run the report from the template you have created.

In the My Folders section click the arrow next to Templates to expand this folder and select circulation.

Select the box beside Circulations by month for one library. Select Create a new report from selected template from the dropdown menu. Click Submit.

Complete the first part of report settings. Only Report Name and Choose a folder… are required fields.

1) Template Name, Template Creator, and Template Description are for informational purposes only. They are hard coded when the template is created. At the report definition stage it is not possible to change them.

2) Report Name is required. Reports stored in the same folder must have unique names.

3) Report Description is optional but may help distinguish among similar reports.

4) Report Columns lists the columns that will appear in the output. This is derived from the template and cannot be changed during report definition.

5) Pivot Label Column and Pivot Data Column are optional. Pivot tables are a different way to view data. If you currently use pivot tables in MS Excel it is better to select an Excel output and continue using pivot tables in Excel.

6) You must choose a report folder to store this report definition. Only report folders under My Folders are available. Click on the desired folder to select it.

Select values for the Circulation > Check Out Date/Time. Use the calendar widget or manually enter the desired dates, then click Add to include the date on the list. You may add multiple dates.

The Transform for this field is Year + Month, so even if you choose a specific date (2009-10-20) it will appear as the corresponding month only (2009-10).

It is possible to select relative dates. If you select a relative date 1 month ago you can schedule reports to automatically run each month. If you want to run monthly reports that also show comparative data from one year ago, select a relative date 1 month ago, and 13 months ago.

Select a value for the Circulating Library.

Complete the bottom portion of the report definition interface, then click Save.

1) Select one or more output formats. In this example the report output will be available as an Excel spreadsheet, an HTML table (for display in the staff client or browser), and as a bar chart.

2) If you want the report to be recurring, check the box and select the Recurrence Interval as described in Recurring Reports. In this example, as this is a report that will only be run once, the Recurring Report box is not checked.

3) Select Run as soon as possible for immediate output. It is also possible to set up reports that run automatically at future intervals.

4) It is optional to fill out an email address where a completion notice can be sent. The email will contain a link to password-protected report output (staff login required). If you have an email address in your Local System Administrator account it will automatically appear in the email notification box. However, you can enter a different email address or multiple addresses separated by commas.

Select a folder for the report’s output.

You will get a confirmation dialogue box that the Action Succeeded. Click OK.

Once saved, reports stay there forever unless you delete them.

123.1. Viewing and Editing Report Parameters

New options to view or edit report parameters are available from the reports folder.

To view the parameters of a report, select the report that you want to view from the Reports folder, and click View. This will enable you to view the report, inlcuding links to external documentation and field hints. However, you cannot make any changes to the report.

To edit the parameters of a report, select the report that you want to view from the Reports folder, and click Edit. After making changes, you can Save [the] Report or Save as New. If you Save the Report, any subsequent report outputs that are generated from this report will reflect the changes that you have made.

In addition, whenever there is a pending (scheduled, but not yet started) report output, the interface will warn you that the pending output will be modified. At that point, you can either continue or choose the alternate Save as New option, leaving the report output untouched.

If, after making changes, you select, Save as New, then you have created a new report by cloning and ammending a previously existing report. Note that if you create a new report, you will be prompted to rename the new report. Evergreen does not allow two reports with the same name to exist. To view or edit your new report, select the reports folder to which you saved it.

Chapter 124. Viewing Report Output

When a report runs Evergreen sends an email with a link to the output to the address defined in the report. Output is also stored in the specified Output folder and will remain there until manually deleted.

To view report output in the staff client, open the reports interface from Admin (-) -→ Local Administration -→ Reports

Click on Output to expand the folder. Select Circulation (where you just saved the circulation report output).

View report output is the default selection in the dropdown menu. Select Recurring Monthly Circ by Location by clicking the checkbox and click Submit.

A new tab will open for the report output. Select either Tabular Output or Excel Output. If Bar Charts was selected during report definition the chart will also appear.

Tabular output looks like this:

If you want to manipulate, filter or graph this data, Excel output would be more useful. Excel output will generate a ".xlsx" file. Excel output looks like this in Excel:

Chapter 125. Cloning Shared Templates

This chapter describes how to make local copies of shared templates for routine reports or as a starting point for customization. When creating a new template it is a good idea to review the shared templates first: even if the exact template you need does not exist it is often faster to modify an existing template than to build a brand new one. A Local System Administrator account is required to clone templates from the Shared Folders section and save them to My Folders.

The steps below assume you have already created at least one Templates folder. If you haven’t done this, please see Creating Folders.

Access the reports interface from Administration → Reports

Under Shared Folders expand the Templates folder and the subfolder of the report you wish to clone. To expand the folders click on the grey arrow or folder icon. Do not click on the blue underlined hyperlink.

Click on the subfolder.

Select the template you wish to clone. From the dropdown menu choose Clone selected templates, then click Submit.

By default Evergreen only displays the first 10 items in any folder. To view all content, change the Limit output setting from 10 to All.

Choose the folder where you want to save the cloned template, then click Select Folder. Only template folders created with your account will be visible. If there are no folders to choose from please see Creating Folders.

The cloned template opens in the template editor. From here you may modify the template by adding, removing, or editing fields and filters as described in Creating Templates. Template Name and Description can also be edited. When satisfied with your changes click Save.

Click OK in the resulting confirmation windows.

Once saved it is not possible to edit a template. To make changes, clone a template and change the clone.

Chapter 126. Adding Data Sources to Reporter

You can further customize your Evergreen reporting environment by adding additional data sources.

The Evergreen reporter module does not build and execute SQL queries directly, but instead uses a data abstraction layer called Fieldmapper to mediate queries on the Evergreen database.Fieldmapper is also used by other core Evergreen DAO services, including cstore and permacrud. The configuration file fm_IDL.xml contains the mapping between Fieldmapper class definitions and the database. The fm_IDL.xml file is located in the /openils/conf directory.

There are 3 basic steps to adding a new data source. Each step will be discussed in more detail in the

Create a PostgreSQL query, view, or table that will provide the data for your data source.

Add a new class to fm_IDL.xml for your data source.

Restart the affected services to see the new data source in Reporter.

There are two possbile sources for new data sources:

An SQL query built directly into the class definition in fm_IDL.xml. You can use this method if you are only going to access this data source through the Evergreen reporter and/or cstore code that you write.

A new table or view in the Evergreen PostgresSQL database on which a class definition in fm_IDL.xml. You can use this method if you want to be able to access this data source through directly through SQL or using other reporting tool.

126.1. Create a PostgreSQL query, view, or table for your data source

You need to decide whether you will create your data source as a query, a view, or a table.

Create a query if you are planning to access this data source only through the Evergreen reporter and/or cstore code that you write. You will use this query to create an IDL only view.

Create a view if you are planning to access this data source through other methods in addition to the Evergreen reporter, or if you may need to do performance tuning to optimize your query.

You may also need to use an additional table as part of your data source if you have additional data that’s not included in the base Evergreen, or if you need to use a table to store the results of a query for performance reasons.

To develop and test queries, views, and tables, you will need

Access to the Evergree PostgreSQL database at the command line. This is normally the psql application. You can access the Postgres documentation at the Official Postgres documentation for more information about PostgreSQL.

Knowledge of the Evergreen database structure for the data that you want to access. You can find this information by looking at the Evergreen schema Evergreen schema

If the views that you are creating are purely local in usage and are not intended for contribution to the core Evergreen code, create the Views and Tables in the extend_reporter schema. This schema is intended to be used for local customizations and will not be modified during upgrades to the Evergreen system.

You should make that you have an appropriate version control pocess for the SQL used to create you data sources.

Here’s an example of a view created to incorporate some locally defined user statistical categories:

example view for reports. 

create view extend_reporter.patronstats as
select u.id,
grp.name as "ptype",
rl.stat_cat_entry as "reg_lib",
gr.stat_cat_entry as "gender",
ag.stat_cat_entry as "age_group",
EXTRACT(YEAR FROM age(u.dob)) as "age",
hl.id as "home_lib",
u.create_date,
u.expire_date,
ms_balance_owed
from actor.usr u
join permission.grp_tree grp
    on (u.profile = grp.id and (grp.parent = 2 or grp.name = 'patron'))
join actor.org_unit hl on (u.home_ou = hl.id)
left join money.open_usr_summary ms
    on (ms.usr = u.id)
left join actor.stat_cat_entry_usr_map rl
    on (u.id = rl.target_usr and rl.stat_cat = 4)
left join actor.stat_cat_entry_usr_map bt
    on (u.id = bt.target_usr and bt.stat_cat = 3)
left join actor.stat_cat_entry_usr_map gr
    on (u.id = gr.target_usr and gr.stat_cat = 2)
left join actor.stat_cat_entry_usr_map gr
    on (u.id = gr.target_usr and gr.stat_cat = 2)
left join actor.stat_cat_entry_usr_map ag
    on (u.id = ag.target_usr and ag.stat_cat = 1)
where u.active = 't' and u.deleted <> 't';

126.2. Add a new class to fm_IDL.xml for your data source

Once you have your data source, the next step is to add that data source as a new class in fm_IDL.xml.

You will need to add the following attributes for the class definition:

id. You should follow a consistent naming convention for your class names that won’t create conflicts in the future with any standard classes added in future upgrades. Evergreen normally names each class with the first letter of each word in the schema and table names. You may want to add a local prefix or suffix to your local class names.

controller=”open-ils.cstore”

oils_obj:fieldmapper=”extend_reporter::long_name_of_view”

oils_persist.readonly=”true”

reporter:core=”true” (if you want this to show up as a “core” reporting source)

reporter:label. This is the name that will appear on the data source list in the Evergreen reporter.

oils_persist:source_definition. If this is an IDL-only view, add the SQL query here. You don’t need this attribute if your class is based on a PostgreSQL view or table.

oils_persist:tablename="schemaname.viewname or tablename" If this class is based on a PostgreSQL view or table, add the table name here. You don’t need this attribute is your class is an IDL-only view.

For each column in the view or query output, add field element and set the following attributes. The fields should be wrapped with <field> </field>:

reporter:label. This is the name that appears in the Evergreen reporter.

name. This should match the column name in the view or query output.

reporter:datatype (which can be id, bool, money, org_unit, int, number, interval, float, text, timestamp, or link)

For each linking field, add a link element with the following attributes. The elements should be wrapped with <link> </link>:

field (should match field.name)

reltype (“has_a”, “might_have”, or “has_many”)

map (“”)

key (name of the linking field in the foreign table)

class (ID of the IDL class of the table that is to be linked to)

The following example is a class definition for the example view that was created in the previous section.

example class definition for reports. 

<class id="erpstats" controller="open-ils.reporter-store"
oils_obj:fieldmapper="extend_reporter::patronstats"
oils_persist:tablename="extend_reporter.patronstats" oils_persist:readonly="true"
reporter:label="Patron Statistics" reporter:core="true">
  <fields oils_persist:primary="id">
  <field reporter:label="Patron ID" name="id" reporter:datatype="link" />
  <field reporter:label="Patron Type" name="ptype" reporter:datatype="text" />
  <field reporter:label="Reg Lib" name="reg_lib" reporter:datatype="text" />
  <field reporter:label="Boro/Twp" name="boro_twp" reporter:datatype="text" />
  <field reporter:label="Gender" name="gender" reporter:datatype="text" />
  <field reporter:label="Age Group" name="age_group" reporter:datatype="text" />
  <field reporter:label="Age" name="age" reporter:datatype="int" />
  <field reporter:label="Home Lib ID" name="home_lib_id"
    reporter:datatype="link" />
  <field reporter:label="Home Lib Code" name="home_lib_code"
    reporter:datatype="text" />
  <field reporter:label="Home Lib" name="home_lib" reporter:datatype="text" />
  <field reporter:label="Create Date" name="create_date"
    reporter:datatype="timestamp" />
  <field reporter:label="Expire Date" name="expire_date"
    reporter:datatype="timestamp" />
  <field reporter:label="Balance Owed" name="balance_owed"
    reporter:datatype="money" />
</fields>
<links>
  <link field="id" reltype="has_a" key="id" map="" class="au"/>
  <link field="home_lib_id" reltype="has_a" key="id" map="" class="aou"/>
</links>
</class>

fm_IDL.xml is used by other core Evergreen DAO services, including cstore and permacrud. So changes to this file can affect the entire Evergreen application, not just reporter. After making changes fm_IDL.xml, it is a good idea to ensure that it is valid XML by using a utility such as xmllint – a syntax error can render much of Evergreen nonfunctional. Set up a good change control system for any changes to fm_IDL.xml. You will need to keep a separate copy of you local class definitions so that you can reapply the changes to fm_IDL.xml after Evergreen upgrades.

126.3. Restart the affected services to see the new data source in the reporter

The following steps are needed to for Evergreen to recognize the changes to fm_IDL.xml

Copy the updated fm_IDL.xml into place:

cp fm_IDL.xml /openils/conf/.

(Optional) Make the reporter version of fm_IDL.xml match the core version. Evergreen systems supporting only one interface language will normally find that /openils/var/web/reports/fm_IDL.xml is a symbolic link pointing to /openils/conf/fm_IDL.xml, so no action will be required. However, systems supporting multiple interfaces will have a different version of fm_IDL.xml in the /openils/var/web/reports directory. The right way to update this is to go through the Evergreen internationalization build process to create the entity form of fm_IDL.xml and the updated fm_IDL.dtd files for each supported language. However, that is outside the scope of this document. If you can accept the reporter interface supporting only one language, then you can simply copy your updated version of fm_IDL.xml into the /openils/var/web/reports directory:

cp /openils/conf/fm_IDL.xml /openils/var/web/reports/.

As the opensrf user, run Autogen to to update the Javascript versions of the fieldmapper definitions.

/openils/bin/autogen.sh

As the opensrf user, restart services:

osrf_control --localhost --restart-services

As the root user, restart the Apache web server:

service apache2 restart

As the opensrf user, restart the Evergreen reporter. You may need to modify this command depending on your system configuration and PID path:

opensrf-perl.pl -l -action restart -service open-ils.reporter \
-config /openils/conf/opensrf_core.xml -pid-dir /openils/var/run

Restart the Evergreen staff client, or use Admin -→ For Developers -→ Clear Cache

Chapter 127. Running Recurring Reports

Recurring reports are a useful way to save time by scheduling reports that you run on a regular basis, such as monthly circulation and monthly patron registration statistics. When you have set up a report to run on a monthly basis you’ll get an email informing you that the report has successfully run. You can click on a link in the email that will take you directly to the report output. You can also access the output through the reporter interface as described in Viewing Report Output.

To set up a monthly recurring report follow the procedure in Generating Reports from Templates but make the changes described below.

Select the Recurring Report check-box and set the recurrence interval to 1 month.

Do not select Run ASAP. Instead schedule the report to run early on the first day of the next month. Enter the date in YYYY-MM-DD format.

Ensure there is an email address to receive completion emails. You will receive an email completion notice each month when the output is ready.

Select a folder for the report’s output.

Click Save Report.

You will get a confirmation dialogue box that the Action Succeeded. Click OK.

You will get an email on the 1st of each month with a link to the report output. By clicking this link it will open the output in a web browser. It is still possible to login to the staff client and access the output in Output folder.

How to stop or make changes to an existing recurring report? Sometimes you may wish to stop or make changes to a recurring report, e.g. the recurrence interval, generation date, email address to receive completion email, output format/folder or even filter values (such as the number of days overdue). You will need to delete the current report from the report folder, then use the above procedure to set up a new recurring report with the desired changes. Please note that deleting a report also deletes all output associated with it.

Once you have been on Evergreen for a year, you could set up your recurring monthly reports to show comparative data from one year ago. To do this select relative dates of 1 month ago and 13 months ago.

Chapter 128. Template Terminology

128.1. Data Types

The central column of the Database Source Browser lists Field Name and Data Type for the selected database table.

Each data type has its own characteristics and uses:

Data Type
Description
Notes

int

Integer

money

id

Unique number assigned by the database to identify a record

A number that is a meaningful reference for the database but not of much use to a human user. Use in displayed fields when counting records or in filters.

text

Text field

Usually uses the Raw Data transform.

timestamp

Exact date and time

Select appropriate date/time transform. Raw Data includes second and timezone information, usually more than is required for a report.

bool

True or False

Commonly used to filter out deleted item or patron records.

org_unit

A number representing a library, library system, or federation

When you want to filter on a library, make sure that the field name is on an org_unit or id data type.

link

A link to another database table

Link outputs a number that is a meaningful reference for the database but not of much use to a human user. You will usually want to drill further down the tree in the Sources pane and select fields from the linked table. However, in some instances you might want to use a link field. For example, to count the number of patrons who borrowed items you could do a count on the Patron link data.

128.2. Field Transforms

A Field Transform tells the reporter how to process a field for output. Different data types have different transform options.

Raw Data. To display a field exactly as it appears in the database use the Raw Data transform, available for all data types.

Count and Count Distinct. These transforms apply to the id data type and are used to count database records (e.g. for circulation statistics). Use Count to tally the total number of records. Use Count Distinct to count the number of unique records, removing duplicates.

To demonstrate the difference between Count and Count Distinct, consider an example where you want to know the number of active patrons in a given month, where ``active" means they borrowed at least one item. Each circulation is linked to a Patron ID, a number identifying the patron who borrowed the item. If we use the Count Distinct transform for Patron IDs we will know the number of unique patrons who circulated at least one book (2 patrons in the table below). If instead, we use Count, we will know how many books were circulated, since every circulation is linked to a patron ID and duplicate values are also counted. To identify the number of active patrons in this example the Count Distinct transform should be used.

Title
Patron ID
Patron Name

Harry Potter and the Philosopher’s Stone

222

Jane Doe

Harry Potter and the Chamber of Secrets

001

John Doe

Northern Lights

001

John Doe

Output Type. Note that each transform has either an Aggregate or Non-Aggregate output type.

Selecting a Non-Aggregate output type will return one row of output in your report for each row in the database. Selecting an Aggregate output type will group together several rows of the database and return just one row of output with, say, the average value or the total count for that group. Other common aggregate types include minimum, maximum, and sum.

When used as filters, non-aggregate and aggregate types correspond to Base and Aggregate filters respectively. To see the difference between a base filter and an aggregate filter, imagine that you are creating a report to count the number of circulations in January. This would require a base filter to specify the month of interest because the month is a non-aggregate output type. Now imagine that you wish to list all items with more than 25 holds. This would require an aggregate filter on the number of holds per item because you must use an aggregate output type to count the holds.

Chapter 129. Template Enhancements

129.1. Documentation URL

You can add a link to local documentation that can help staff create a report template. To add documentation to a report template, click Admin → Local Administration → Reports, and create a new report template. A new field, Documentation URL, appears in the Template Configuration panel. Enter a URL that points to relevant documentation.

The link to this documentation will also appear in your list of report templates.

129.2. Field Hints

Descriptive information about fields or filters in a report template can be added to the Field Hints portion of the Template Configuration panel. For example, a circulation report template might include the field, Circ ID. You can add content to the Field hints to further define this field for staff and provide a reminder about the type of information that they should select for this field.

To view a field hint, click the Column Picker, and select Field Hint. The column will be added to the display.

To add or edit a field hint, select a filter or field, and click Change Field Hint. Enter text, and click Ok.

Chapter 130. Exporting Report Templates Using phpPgAdmin

Once the data is exported. Database Administrators/Systems Administrators can easily import this data into the templates folder to make it available in the client.

130.1. Dump the Entire Reports Template Table

The data exported in this method can create issues importing into a different system if you do not have a matching folder and owner. This is going to export report templates created in your system. The most important fields for importing into the new system are name, description, and data. Data defines the actual structure of the report. The owner and folder fields will unique to the system they were exported from and will have to be altered to ensure they match the appropriate owner and folder information for the new system.

Go to the Reporter schema. Report templates are located in the Template table

Click on the link to the Template table

Click the export button at the top right of the phpPgAdmin screen

Make sure the following is selected

Data Only (checked)

Format: Select CSV or Tabbed did get the data in a text format

Download checked

Click export button at the bottom

A text file will download to your local system

130.2. Dump Data with an SQL Statement

The following statement could be used to grab the data in the folder and dump it with admin account as the owner and the first folder in your system.

SELECT 1 as owner, name, description, data, 1 as folder FROM reporter.template

or use the following to capture your folder names for export

SELECT 1 as owner, t.name, t.description, t.data, f.name as folder
        FROM reporter.template t
        JOIN reporter.template_folder f ON t.folder=f.id

Run the above query

Click the download link at the bottom of the page

Select the file format (CSV or Tabbed)

Check download

A text file with the report template data will be downloaded.

Part XIII. Using the Public Access Catalog

Chapter 131. Introduction

Evergreen has a public OPAC that meets WCAG guidelines (http://www.w3.org/WAI/intro/wcag), which helps make the OPAC accessible to users with a range of disabilities. This part of the documentation explains how to use the Evergreen public OPAC. It covers the basic catalog and more advanced search topics. It also describes the “My Account” tools users have to find information and manage their personal library accounts through the OPAC. This section could be used by staff and patrons but would be more useful for staff as a generic reference when developing custom guides and tutorials for their users.

Chapter 132. Using the Public Access Catalog

132.1. Basic Search

From the OPAC home, you can conduct a basic search of all materials owned by all libraries in your Evergreen system.

This search can be as simple as typing keywords into the search box and clicking the Search button. Or you can make your search more precise by limiting your search by fields to search, material type or library location.

The Homepage contains a single search box for you to enter search terms. You can get to the Homepage at any time by clicking the Another Search link from the leftmost link on the bar above your search results in the catalogue, or you can enter a search anywhere you see a search box.

You can select to search by:

Keyword: finds the terms you enter anywhere in the entire record for an item, including title, author, subject, and other information.

Title: finds the terms you enter in the title of an item.

Journal Title: finds the terms you enter in the title of a serial bib record.

Author: finds the terms you enter in the author of an item.

Subject: finds the terms you enter in the subject of an item. Subjects are categories assigned to items according to a system such as the Library of Congress Subject Headings.

Series: finds the terms you enter in the title of a multi-part series.

To search an item copy call number, use Advanced Search: Numeric

132.1.1. Formats

You can limit your search by formats based on MARC fixed field type:

All Books

All Music

Audiocassette music recording

Blu-ray

Braille

Cassette audiobook

CD Audiobook

CD Music recording

DVD

E-audio

E-book

E-video

Equipment, games, toys

Kit

Large Print Book

Map

Microform

Music Score

Phonograph music recording

Phonograph spoken recording

Picture

Serials and magazines

Software and video games

VHS

132.1.1.1. Libraries

If you are using a catalogue in a library or accessing a library’s online catalogue from its homepage, the search will return items for your local library. If your library has multiple branches, the result will display items available at your branch and all branches of your library system separately.

132.2. Advanced Search

Advanced searches allow users to perform more complex searches by providing more options. Many kinds of searches can be performed from the Advanced Search screen. You can access by clicking Advanced Search on the catalogue Homepage or search results screen.

The available search options are the same as on the basic search. But you may use one or many of them simultaneously. If you want to combine more than three search options, use Add Search Row button to add more search input rows. Clicking the X button will close the search input row.

132.2.1. Sort Results

By default, the search results are in order of greatest to least relevance, see Order of Results. In the sort results menu you may select to order the search results by relevance, title, author, or publication date.

132.2.2. Search Library

The current search library is displayed under Search Library drop down menu. By default it is your library. The search returns results for your local library only. If your library system has multiple branches, use the Search Library box to select different branches or the whole library system.

132.2.3. Limit to Available

This checkbox is at the bottom line of Search Library. Select Limit to Available to limit results to those titles that have items with a circulation status of "available" (by default, either Available or Reshelving).

132.2.4. Exclude Electronic Resources

This checkbox is below Limit to Available. Select Exclude Electronic Resources to limit results to those bibliographic records that do not have an "o" or "s" in the Item Form fixed field (electronic forms) and overrides other form limiters.

This feature is optional and will not appear for patrons or staff until enabled.

To display the Exclude Electronic Resources checkbox in the advance search page and search results, set the ctx.exclude_electronic_checkbox setting in config.tt2 to 1.

132.2.5. Search Filter

You can filter your search by Item Type, Item Form, Language, Audience, Video Format, Bib Level, Literary Form, Search Library, and Publication Year. Publication year is inclusive. For example, if you set Publication Year Between 2005 and 2007, your results can include items published in 2005, 2006 and 2007.

For each filter type, you may select multiple criteria by holding down the CTRL key as you click on the options. If nothing is selected for a filter, the search will return results as though all options are selected.

132.2.5.1. Search Filter Enhancements

Enhancements to the Search Filters now makes it easier to view, remove, and modify search filters while viewing search results in the Evergreen OPAC. Filters that are selected while conducting an advanced search in the Evergreen OPAC now appear below the search box in the search results interface.

For example, the screenshot below shows a Keyword search for "violin concerto" while filtering on Item Type: Musical sound recording and Shelving Location: Music.

In the search results, the Item Type and Shelving Location filters appear directly below the search box.

Each filter can be removed by clicking the X next to the filter name to modify the search within the search results screen. Below the search box on the search results screen, there is also a link to Refine My Original Search, which will bring the user back to the advanced search screen where the original search parameters selected can be viewed and modified.

132.2.6. Numeric Search

If you have details on the exact item you wish to search for, use the Numeric Search tab on the advanced search page. Use the drop-down menu to select your search by ISBN, ISSN, Bib Call Number, Call Number (Shelf Browse), LCCN, TCN, or Item Barcode. Enter the information and then click the Search button.

132.2.7. Expert Search

If you are familiar with MARC cataloging, you may search by MARC tag in the Expert Search option on the left of the screen. Enter the three-digit tag number, the subfield if relevant, and the value or text that corresponds to the tag. For example, to search by publisher name, enter 260 b Random House. To search several tags simultaneously, use the Add Row option. Click Submit to run the search.

Use the MARC Expert Search only as a last resort, as it can take much longer to retrieve results than by using indexed fields. For example, rather than running an expert search for "245 a Gone with the wind", simply do a regular title search for "Gone with the wind".

132.3. Boolean operators

Classic search interfaces (that is, those used primarily by librarians) forced users to learn the art of crafting search phrases with Boolean operators. To a large extent this was due to the inability of those systems to provide relevancy ranking beyond a "last in, first out" approach. Thankfully, Evergreen, like most modern search systems, supports a rather sophisticated relevancy ranking system that removes the need for Boolean operators in most cases.

By default, all terms that have been entered in a search query are joined with an implicit AND operator. Those terms are required to appear in the designated fields to produce a matching record: a search for golden compass will search for entries that contain both golden and compass.

Words that are often considered Boolean operators, such as AND, OR, and NOT, are not special in Evergreen: they are treated as just another search term. For example, a title search for golden and compass will not return the title Golden Compass.

However, Evergreen does support Boolean searching for those rare cases where you might require it, using symbolic operators as follows:

Table 132.1. Boolean symbolic operators

Operator
Symbol
Example

AND

&&

a && b

OR

||

a || b

NOT

-term

a -b

132.4. Search Tips

Evergreen tries to approach search from the perspective of a major search engine: the user should simply be able to enter the terms they are looking for as a general keyword search, and Evergreen should return results that are most relevant given those terms. For example, you do not need to enter author’s last name first, nor do you need to enter an exact title or subject heading. Evergreen is also forgiving about plurals and alternate verb endings, so if you enter dogs, Evergreen will also find items with dog.

The search engine has no stop words (terms are ignored by the search engine): a title search for to be or not to be (in any order) yields a list of titles with those words.

Don’t worry about white space, exact punctuation, or capitalization.

White spaces before or after a word are ignored. So, a search for [ golden compass ] gives the same results as a search for [golden compass].

A double dash or a colon between words is reduced to a blank space. So, a title search for golden:compass or golden — compass is equivalent to golden compass.

Punctuation marks occurring within a word are removed; the exception is _. So, a title search for gol_den com_pass gives no result.

Diacritical marks and solitary & or | characters located anywhere in the search term are removed. Words or letters linked together by . (dot) are joined together without the dot. So, a search for go|l|den & comp.ass is equivalent to golden compass.

Upper and lower case letters are equivalent. So, Golden Compass is the same as golden compass.

Enter your search words in any order. So, a search for compass golden gives the same results as a search for golden compass. Adding more search words gives fewer but more specific results.

This is also true for author searches. Both David Suzuki and Suzuki, David will return results for the same author.

Use specific search terms. Evergreen will search for the words you specify, not the meanings, so choose search terms that are likely to appear in an item description. For example, the search luxury hotels will produce more relevant results than nice places to stay.

Search for an exact phrase using double-quotes. For example “golden compass”.

The order of words is important for an exact phrase search. golden compass is different than compass golden.

White space, punctuation and capitalization are removed from exact phrases as described above. So a phrase retains its search terms and its relative order, but not special characters and not case.

Two phrases are joined by and, so a search for "golden compass" "dark materials" is equivalent to golden compass and dark materials.

Truncation Words may be right-hand truncated using an asterisk. Use a single asterisk * to truncate any number of characters. (example: environment* agency)

132.5. Search Methodology

132.5.1. Stemming

A search for dogs will also return hits with the word dog and a search for parenting will return results with the words parent and parental. This is because the search uses stemming to help return the most relevant results. That is, words are reduced to their stem (or root word) before the search is performed.

The stemming algorithm relies on common English language patterns - like verbs ending in ing - to find the stems. This is more efficient than looking up each search term in a dictionary and usually produces desirable results. However, it also means the search will sometimes reduce a word to an incorrect stem and cause unexpected results. To prevent a word or phrase from stemming, put it in double-quotes to force an exact search. For example, a search for parenting will also return results for parental, but a search for "parenting" will not.

Understanding how stemming works can help you to create more relevant searches, but it is usually best not to anticipate how a search term will be stemmed. For example, searching for gold compass does not return the same results as golden compass, because -en is not a regular suffix in English, and therefore the stemming algorithm does not recognize gold as a stem of golden.

132.5.2. Order of Results

By default, the results are listed in order of relevance, similar to a search engine like Google. The relevance is determined using a number of factors, including how often and where the search terms appear in the item description, and whether the search terms are part of the title, subject, author, or series. The results which best match your search are returned first rather than results appearing in alphabetical or chronological order.

In the Advanced Search screen, you may select to order the search results by relevance, title, author, or publication date before you start the search. You can also re-order your search results using the Sort Results dropdown list on the search result screen.

132.6. Search URL

When performing a search or clicking on the details links, Evergreen constructs a GET request url with the parameters of the search. The url for searches and details in Evergreen are persistent links in that they can be saved, shared and used later.

Here is a basic search URL structure:

[hostname]/eg/opac/results?query=[search term]&qtype=keyword&fi%3Aitem_type=&locg=[location id]

132.6.1. locg Parameter

This is the id of the search location. It is an integer and maches the id of the location the user selected in the location drop down menu.

132.6.2. qtype Parameter

The qtype parameter in the URL represents the search type values and represent one of the following search or request types:

Keyword

Title

Journal Title

Author

Subject

Series

Bib Call Number

These match the options in the search type drop-down box.

132.6.3. Sorting

The sort parameter sorts the results on one of these criteria.

sort=pubdate (publication date) - chronological order

sort=titlesort - Alphabetical order

sort=authorsort - Alphabetical order on family name first

To change the sort direction of the results, the sort parameter value has the ".descending" suffix added to it.

sort=titlesort.descending

sort=authorsort.descending

sort=pubdate.descending

In the absence of the sort parameter, the search results default to sorting by relevance.

132.7. Search Results

The search results are a list of relevant works from the catalogue. If there are many results, they are divided into several pages. At the top of the list, you can see the total number of results and go back and forth between the pages by clicking the links that say Previous or Next on top or bottom of the list. You can also click on the adjacent results page number listed. These page number links allow you to skip to that results page, if your search results needed multiple pages to display. Here is an example:

Brief information about the title, such as author, edition, publication date, etc. is displayed under each title. The icons beside the brief information indicate formats such as books, audio books, video recordings, and other formats. If you hover your mouse over the icon, a text explanation will show up in a small pop-up box.

Clicking a title goes to the title details. Clicking an author searches all works by the author. If you want to place a hold on the title, click Place Hold beside the format icons.

On the top right, there is a Limit to Available checkbox. Checking this box will filter out those titles with no available copies in the library or libraries at the moment. Usually you will see your search results are re-displayed with fewer titles.

When enabled, under the Limit to Available checkbox, there is an Exclude Electronic Resources checkbox. Checking this box will filter out materials that are cataloged as electronic in form.

The Sort by dropdown list is found at the top of the search results, beside the Show More Details link. Clicking an entry on the list will re-sort your search results accordingly.

132.7.1. Facets: Subjects, Authors, and Series

At the left, you may see a list of Facets of Subjects, Authors, and Series. Selecting any one of these links filters your current search results using that subject, author, or series to narrow down your current results. The facet filters can be undone by clicking the link a second time, thus returning your original results before the facet was activated.

132.7.2. Availability

The number of available copies and total copies are displayed under each search result’s call number. If you are using a catalogue inside a library or accessing a library’s online catalogue from its homepage, you will see how many copies are available in the library under each title, too. If the library belongs to a multi-branch library system you will see an extra row under each title showing how many copies are available in all branches.

You may also click the Show More Details link at the top of the results page, next to the Limit to available items check box, to view each search result’s copies' individual call number, status, and shelving location.

132.7.3. Viewing a record

Click on a search result’s title to view a detailed record of the title, including descriptive information, location and availability, current holds, and options for placing holds, add to my list, and print/email.

132.8. Details

The record shows details such as the cover image, title, author, publication information, and an abstract or summary, if available.

Near the top of the record, users can easily see the number of copies that are currently available in the system and how many curent holds are on the title.

If there are other formats and editions of the same work in the database, links to those alternate formats will display. The formats used in this section are based on the configurable catalog icon formats.

The Record Details view shows how many copies are at the library or libraries you have selected, and whether they are available or checked out. It also displays the Call number and Copy Location for locating the item on the shelves. Clicking on Text beside the call number will allow you to send the item’s call number by text message, if desired. Clicking the location library link will reveal information about owning library, such as address and open hours.

Below the local details you can open up various tabs to display more information. You can select Reviews and More to see the book’s summaries and reviews, if available. You can select Shelf Browser to view items appearing near the current item on the library shelves. Often this is a good way to browse for similar items. You can select MARC Record to display the record in MARC format. If your library offers the service, clicking on Awards, Reviews, and Suggested Reads will reveal that additional information.

Copies are sorted by (in order): org unit, call number, part label, copy number, and barcode.

132.8.1. Placing Holds

Holds can be placed on either title results or search results page. If the item is available, it will be pulled from the shelf and held for you. If all copies at your local library are checked out, you will be placed on a waiting list and you will be notified when items become available.

On title details page, you can select the Place Hold link in the upper right corner of the record to reserve the item. You will need your library account user name and password. You may choose to be notified by phone or email.

In the example below, the phone number in your account will automatically show up. Once you select the Enable phone notifications for this hold checkbox, you can supply a different phone number for this hold only. The notification method will be selected automatically if you have set it up in your account references. But you still have a chance to re-select on this screen. You may also suspend the hold temporarily by checking the Suspend box. Click the Help beside it for details.

You can view and cancel a hold at anytime. Before your hold is captured, which means an item has been held waiting for you to pick up, you can edit, suspend or activate it. You need log into your patron My Account to do it. From your account you can also set up a Cancel if not filled by date for your hold. Cancel if not filled by date means after this date, even though your hold has not been fulfilled you do not need the item anymore.

132.8.2. Permalink

The record summary page offers a link to a shorter permalink that can be used for sharing the record with others. All URL parameters are stripped from the link with the exception of the locg and copy_depth parameters. Those parameters are maintained so that people can share a link that displays just the holdings from one library/system or displays holdings from all libraries with a specific library’s holdings floating to the top.

132.8.3. SMS Call Number

If configured by the library system administrator, you may send yourself the call number via SMS message by clicking on the Text link, which appears beside the call number.

See the Sending Copy Details via Text Message section of the documentation for more information on how to use this feature.

Carrier charges may apply when using the SMS call number feature.

132.8.4. Going back

When you are viewing a specific record, you can always go back to your title list by clicking the link Search Results on the top right or left bottom of the page.

You can start a new search at any time by entering new search terms in the search box at the top of the page, or by selecting the Another Search or Advanced Search links in the left-hand sidebar.

132.9. My Account

132.9.1. Logging In

Logging into your account from the online catalog:

Open a web browser and navigate to your Evergreen OPAC.

Click My Account .

Enter your Username and Password.

By default, your username is your library card number.

Your password is a 4 digit code provided when your account was created. If you have forgotten your password, contact your local library to have it reset or use the the section called Password Reset tool.

Click Login.

At the first login, you may be prompted to change your password.

If you updated your password, you must enter your Username and Password again.

Your Account Summary page displays.

To view your account details, click one of the My Account tabs.

To start a search, enter a term in the search box at the top of the page and click Search!

If using a public computer be sure to log out!

132.9.2. Password Reset

To reset your password:

click on the Forgot your password? link located beside the login button.

Fill in the Barcode and User name text boxes.

A message should appear indicating that your request has been processed and that you will receive an email with further instructions.

An email will be sent to the email addressed you have registered with your Evergreen library. You should click on the link included in the email to open the password reset page. Processing time may vary.

You will need to have a valid email account set up in Evergreen for you to reset your password. Otherwise, you will need to contact your library to have your password reset by library staff.

At the reset email page you should enter the new password in the New password field and re-enter it in the Re-enter new password field.

Click Submit.

A message should appear on the page indicating that your password has been reset.

Login to your account with your new password.

132.9.3. Account Summary

In the My Account → Account Summary page, you can see when your account expires and your total number of items checked out, items on hold, and items ready for pickup. In addition, the Account Summary page lists your current fines and payment history.

132.9.4. Items Checked Out

Users can manage items currently checked out, like renew specific items. Users can also view overdue items and see how many renewals they have remaining for specific item.

As of Evergreen version 2.9, sorting of selected columns is available in the Items Checked Out and Check Out History pages. Clicking on the appropriate column heads sorts the contents from "ascending" to "descending" to "no sort". (The "no sort" restores the original list as presented in the screen.) The sort indicator (an up or down arrow) is placed to the right of the column head, as appropriate.

Within Items Checked Out → Current Items Checked Out, the following column headers can be sorted: Title, Author, Renewals Left, Due Date, Barcode, and Call Number.

Within Items Checked Out → Check Out History, the following column headers can be sorted: Title, Author, Checkout Date, Due Date, Date Returned, Barcode, and Call Number

To protect patron privacy, the Check Out History will be completely blank unless the patron has previously opted in under the Account Preferences tab, in the Search and History Preferences area.

132.9.5. Holds

From My Account, patrons can see Items on Hold and Holds History and manage items currently being requested. In Holds → Items on Hold, the content shown can be sorted by clicking on the following column headers: Title, Author, and Format (based on format name represented by the icon).

Actions include:

Suspend - set a period of time during which the hold will not become active, such as during a vacation

Activate - manually remove the suspension

Cancel - remove the hold request

Edit options include:

Change pick up library

Change the Cancel unless filled by date, also known as the hold expiration date

Change the status of the hold to either active or suspended.

Change the If suspended, activate on date, which reactivates a suspended hold at the specified date

To edit items on hold:

Login to My Account, click the Holds tab.

Select the hold to modify.

Click Edit for selected holds.

Select the change to make and follow the instructions.

To protect patron privacy, the Holds History will be completely blank unless the patron has previously opted in under the Account Preferences tab, in the Search and History Preferences area.

132.9.6. Account Preferences

From here you can manage display preferences including your Personal Information, Notification Preferences, and Search and History Preferences. Additional static information, such as your Account Expiration Date, can be found under Personal Information.

For example:

Personal Information

change password - allows patrons to change their password

change email address - allows patrons to change their email address.

Notification Preferences

Notify by Email by default when a hold is ready for pickup?

Notify by Phone by default when a hold is ready for pickup?

Default Phone Number

Search and History Preferences

Search hits per page

Preferred pickup location

Keep history of checked out items?

Keep history of holds?

Turning off the Keep history of checked out items? or Keep history of holds? features will permanently delete all entries in the relevant patron screens. After this is unchecked, there is no way for a patron to recover those data.

After changing any of these settings, you must click Save to store your preferences.

132.9.7. Patron Messages

The Patron Message Center provides a way for libraries to communicate with patrons through messages that can be accessed through the patron’s OPAC account. Library staff can create messages manually by adding an OPAC visible Patron Note to an account. Messages can also be automatically generated through an Action Trigger event. Patrons can access and manage messages within their OPAC account. See Circulation - Patron Record - Patron Message Center for more information on adding messages to patron accounts.

Viewing Patron Messages in the OPAC

Patrons will see a new tab for Messages in their OPAC account, as well as a notification of Unread Messages in the account summary.

Patrons will see a list of the messages from the library by clicking on the Messages tab.

Patrons can click on a message Subject to view the message. After viewing the message, it will automatically be marked as read. Patrons have the options to mark the message as unread and to delete the message.

Patron deleted messages will still appear in the patron’s account in the staff client under Other → Message Center.

Chapter 133. My Lists

The My Lists feature replaces the bookbag feature that was available in versions prior to 2.2. The My Lists feature is a part of the Template Toolkit OPAC that is available in version 2.2. This feature enables you to create temporary and permanent lists; create and edit notes for items in lists; place holds on items in lists; and share lists via RSS feeds and CSV files.

There is now a direct link to My Lists from the My Account area in the top right part of the screen. This gives users the ability to quickly access their lists while logged into the catalog.

133.1. Create New Lists

1) Log in to your account in the OPAC.

2) Search for titles.

3) Choose a title to add to your list. Click Add to My List.

4) Scroll up to the gray row on top of the Search Results. Click View My List

5) Items are added to a temporary list. Your temporary list appears at the bottom of the screen.

6) The Actions for these items menu on the right side of the screen demonstrates the actions that you can apply to this list. You can place holds on items in your temporary list; remove items from the list; or move selected items to a permanent list.

To place a hold or remove items from the list, check the box adjacent to the title of the item, and select the desired function.

To move selected items into an existing list, check the box adjacent to the title, and highlight the list in which you will store the item.

7) If you do not want to place the item into an existing list, you can create a new list to contain the item. Enter the name of the new list, and, if desired, enter a description.

8) Click Submit.

9) The new list appears beneath the temporary list.

10) Select the title(s) of the items that you want to add to the list, and click Actions for these items. Select the permanent list that you created from the drop down menu.

11) Click Go.

12) Your existing lists appear. Click on a list to view the items in the list. You can sort the items in the permanent list. You can also add, edit, and remove notes.

13) Click Edit to add or edit a note.

14). Enter desired notes, and click Save Notes.

15) You can keep your list private, or you can share it. To share your list, click Share, and click the orange RSS icon to share through an RSS reader. You can also click HTML View to share your list as an HTML link.

You can also download your list into a CSV file by clicking Download CSV.

16) When you no longer need a list, click Delete List.

133.2. Local Call Number in My Lists

When a title is added to a list in the TPAC, a local call number will be displayed in the list to assist patrons in locating the physical item. Evergreen will look at the following locations to identify the most relevant call number to display in the list:

1) Physical location - the physical library location where the search takes place

2) Preferred library - the Preferred Search Location, which is set in patron OPAC account Search and History Preferences, or the patron’s Home Library

3) Search library - the search library or org unit that is selected in the OPAC search interface

The call number that is displayed will be the most relevant call number to the searcher. If the patron is searching at the library, Evergreen will display a call number from that library location. If the patron is not searching at a library, but is logged in to their OPAC account, Evergreen will display a call number from their Home Library or Preferred Search Location. If the patron is not searching at the library and is not signed in to their OPAC account, then Evergreen will display a call number from the org unit, or library, that they choose to search in the OPAC search interface.

The local call number and associated library location will appear in the list:

133.3. My Lists Preferences

Patrons can adjust the number of lists or list items displayed in a page. This setting can be found under the Account Preferences tab, in the My Lists Preferences section.

Chapter 134. Kids OPAC

The Kids OPAC (KPAC) is a public catalog search that was designed for children and teens. Colorful menu items,large buttons, and simple navigation make this an appealing search interface for kids. Librarians will appreciate the flexible configuration of the KPAC. Librarians can create links to canned search results for kids and can apply these links by branch. The KPAC uses the same infrastructure as the Template Toolkit OPAC (TPAC), the adult catalog search, so you can easily extend the KPAC using the code that already exists in the TPAC. Finally, third party content, such as reader reviews, can be integrated into the KPAC.

134.1. Choose a Skin

Two skins, or design interfaces, have been created for the KPAC. The KPAC was designed to run multiple skins on a single web server. A consortium, then, could allow each library system to choose a skin for their patrons.

Default Skin:

In this skin, the search bar is the focal point of the top panel and is centered on the screen. The search grid appears beneath the search bar. Help and Login links appear at the top right of the interface. You can customize the appearance and position of these links with CSS. After you login, the user name is displayed in the top right corner, and the Login link becomes an option to Logout.

Alternate Monster Skin:

In this skin, the search bar shares the top panel with a playful monster. The search grid appears beneath the search bar. Help and Login links appear in bold colors at the top right of the interface although you can customize these with CSS. After you login, the Login button disappears.

134.2. Search the Catalog

You can search the catalog using only the search bar, the search grid, or the search bar and the collection drop down menu.

Search using the Search Bar

To search the catalog from the home page, enter text into the search bar in the center of the main page, or enter text into the search bar to the right of the results on a results page. Search indices are configurable, but the default search indices include author, title and (key)word.

You can use this search bar to search the entire catalog, or, using the configuration files, you can apply a filter so that search queries entered here retrieve records that meet specific criteria, such as child-friendly copy locations or MARC audience codes.

Search using the Grid

From the home page, you can search the catalog by clicking on the grid of icons. An icon search can link to an external web link or to a canned search. For example, the icon, Musical Instruments, could link to the results of a catalog search on the subject heading, Musical instruments.

The labels on the grid of icons and the content that they search are configurable by branch. You can use the grid to search the entire catalog, or, using the configuration files, you can apply a filter so that search queries entered here retrieve records associated with specific criteria, such as child-friendly copy locations or MARC audience codes.

You can add multiple layers of icons and searches to your grid:

Search using the Search Bar and the Collection Drop Down Menu

On the search results page, a search bar and drop down menu appear on the right side of the screen. You can enter a search term and into the search bar and select a collection from the drop down menu to search these configured collections. Configured collections might provide more targeted searching for your audience than a general catalog search. For example, you could create collections by shelving location or by MARC audience code.

Using any search method, the search results display in the center of the screen. Brief information displays beneath each title in the initial search result. The brief information that displays, such as title, author, or publication information, is configurable.

For full details on a title, click More Info. The full details displays the configured fields from the title record and copy information. Click Show more copies to display up to fifty results. Use the breadcrumbs at the top to trace your search history.

134.3. Place a Hold

From the search results, click the Get it! link to place a hold.

The brief information about the title appears, and, if you have not yet logged in, the Get It! panel appears with fields for username and password. Enter the username and password, and select the pick up library. Then click Submit. If you have already logged into your account, you need only to select the pick up location, and click Submit.

A confirmation of hold placement appears. You can return to the previous record or to your search results.

134.4. Save Items to a List

You can save items to a temporary list, or, if you are logged in, you can save to a list of your own creation. To save items to a list, click the Get it button on the Search Results page.

Select a list in the Save It! panel beneath the brief information, and click Submit.

A confirmation of the saved item appears. To save the item to a list or to manage the lists, click the My Lists link to return to the list management feature in the TPAC.

134.5. Third Party Content

Third party content, such as reader reviews, can be viewed in the Kids OPAC. The reviews link appears adjacent to the brief information.

Click the Reviews link to view reader reviews from a third party source. The reader reviews open beneath the brief information.

Summaries and reviews from other publications appear in separate tabs beneath the copy information.

134.6. Configuration Files

Configuration files allow you to define labels for canned searches in the icon grid, determine how icons lead users to new pages, and define whether those icons are canned searches or links to external resources. Documentation describing how to use the configuration files is available in the Evergreen repository.

Chapter 135. Catalog Browse

Abstract

Catalog Browse enables you to browse bibliographic headings available in your catalog. You can click the hyperlinked bibliographic headings to retrieve catalog records that contain these headings. Also, if a given bibliographic heading is linked to an authority record, and if that authority is linked to another one via the first authority’s See and See Also tags, the additional variants of (e.g.) an author’s name will appear in your search results.

Use Catalog Browse

To access this feature, navigate to the catalog search page, and click the link, Browse the Catalog. By default, you can browse by title, author, subject, or series. System administrators can revise this list by editing the file at the location opac/parts/qtype_selector.tt2, and they can even make use of custom indices based on defintions in the database’s config.metabib_field table.

Enter a term or part of a term to browse. Evergreen will retrieve a list of bibliographic headings that match your query. Click the Back and Forward buttons to page through you results. To limit your browse results to a specific branch or copy location group, select the appropriate unit from the drop down menu, and click Go.

Select a link from the search results. Each linked heading displays the number of bibliographic records associated with the heading. Appropriate information from linked authority records, if any, appears below the main entry heading.

To return to your list of results, click the browser’s back button or Browse the Catalog. Evergreen will return you to your previous position in your list of results.

Administration

A new global flag warns users when they are entering a browse term that begins with an article. Systems administrators can create a regular expression to configure articles matched with specific indices that would prompt a warning for the user. By default, this setting is not enabled.

To enable this feature, click Admin → Server Administration → Global Flags.

Double click Map of search classes to regular expressions to warn user about leading articles.

Make changes, and click Save.

Chapter 136. Bibliographic Search Enhancements

Enhancements to the bibliographic search function enable you to search for records that were created, edited, or deleted within a date range. You can use the catalog interface or the record feed to search for records with specific date ranges.

Note that all dates should be formatted as YYYY-MM-DD and should be included in parentheses.

136.1. Use the Catalog to Retrieve Records with Specified Date Ranges:

136.1.1. Search by Create Date or Range

To find records that were created on or after a specific date, enter the term, create_date, and the date in the catalog search field. For example, to find records that were created on or after April 1, 2013, enter the following into the catalog search field:

create_date(2013-04-01)

To find records that were created within a specific date range, enter the term, create_date, followed by comma-separated dates in parentheses. For example, to find records that were created between April 1, 2013 and April 8, 2013, enter the following into the catalog search field:

create_date(2013-04-01,2013-04-08)

136.1.2. Search by Edit Date or Range

To find records that were edited on or before a specific date, enter the term, edit-date, and the date in the catalog search field. The date should be preceded by a comma. For example, to find records that were edited on or before April 1, 2013, enter the following into the catalog search field:

edit_date(,2013-04-01)

To find records that were edited on or after a specific date, enter the term, edit_date, and the date in the catalog search field. For example, to find records that were edited on or after April 1, 2013, enter the following into the catalog search field:

edit_date(2013-04-01)

To find records that were edited within a specific range, enter the term, edit_date, followed by comma-separated dates in parentheses. For example, to find records that were edited between April 1, 2013 and April 8, 2013, enter the following into the catalog search field:

edit_date(2013-04-01,2013-04-08)

136.1.3. Search by Deleted Status

To search for deleted records, enter in your catalog search field the term, edit_date, the date that you want to search, and the term, #deleted. For example, to find records that were deleted on or after April 1, 2013, enter the following into the catalog search field:

edit_date(2013-04-01)#deleted

To find records that were deleted within a specific range, enter the term, edit_date, followed by comma-separated dates in parentheses. For example, to find records that were deleted between April 1, 2013 and April 8, 2013, enter the following into the catalog search field:

edit_date(2013-04-01,2013-04-08)#deleted

136.2. Use a Feed to Retrieve Records with Specified Date Ranges:

You can use a feed to retrieve records that were created, edited, or deleted within specific date ranges by adding the dates to the catalog’s URL. You can do this manually, or you can write a script that would automatically retrieve this information.

To manually retrieve records that were created, edited, or deleted within a specific date, enter the terms and dates as specified above within the search terms in the URL. For example, to retrieve records created on or after April 1, 2013, enter the following in your URL:

http://test.esilibrary.com/opac/extras/opensearch/1.1/-/html-full?searchTerms=create_date(2013-04-01)&searchClass=keyword

To retrieve deleted records, replace the # with %23 in your URL.

Chapter 137. Binary MARC21 Feeds

Evergreen’s OpenSearch service can return search results in many formats, including HTML, MARCXML, and MODS. As of version 2.4, it can also return results in binary MARC21 format.

When making an HTTP request to an Evergreen system using the OpenSearch API, you must include the term "marc21" in the appropriate location within the URL to retrieve a feed of MARC21 records in a binary format. The following example demonstrates the appropriate form of the URL:

http://test.esilibrary.com/opac/extras/opensearch/1.1/-/marc21?searchTerms=create_date%282013-04-01%29&searchClass=keyword

You can add this term manually to the URL produced by a catalog search, or you can create a script that would retrieve this information automatically.

Chapter 138. TPAC Metarecord Search and Metarecord Level Holds

Metarecords are compilations of individual bibliographic records that represent the same work. This compilation allows for several records to be represented on a single line on the TPAC search results page, which can help to reduce result duplications.

Advanced Search Page

Selecting the Group Formats and Editions checkbox on the Advanced Search page allows the user to perform a metarecord search.

Administrators can also configure the catalog to default to a Group Formats and Editions search by enabling the relevant config.tt2 setting on the server. Setting this option will pre-select the checkbox on the Advanced Search and Search Result Pages. Users can remove the checkmark, but new searches will revert to the default search behavior.

Search Results Page

Within the Search Results page, users can also refine their searches and filter on metarecord search results by selecting the Group Formats and Editions checkbox.

The metarecord search results will display both the representative metarecord bibliographic data and the combined metarecord holdings data (if the holdings data is OPAC visible).

The number of records represented by the metarecord are displayed in parenthesis next to the title.

The formats contained within the metarecord are displayed under the title.

For the metarecord search result, the Place Hold link defaults to a metarecord level hold.

To place a metarecord level hold:

Click the Place Hold link.

Users who are not logged into their accounts will be directed to the Log in to Your Account screen, where they will enter their username and password. Users who are already logged into their accounts will be directed to the Place Hold screen.

Within the Place Hold screen, users can select the multiple formats and/or languages that are available.

Continue to enter any additional hold information (such as Pickup Location), if needed.

Click Submit.

Selecting multiple formats will not place all of these formats on hold for the user. For example, a user cannot select CD Audiobook and Book and expect to place both the CD and book on hold at the same time. Instead, the user is implying that either the CD format or the book format is the acceptable format to fill the hold. If no format is selected, then any of the available formats may be used to fill the hold. The same holds true for selecting multiple languages.

Advanced Hold Options

When users place a hold on an individual bibliographic record they will see an Advanced Hold Options link within the Place Hold screen. Clicking the Advanced Hold Options link will take the users into the metarecord level hold feature, enabling them to select multiple formats and/or languages.

Metarecord Constituent Records Page

The TPAC now includes a Metarecord Constituent Records page, which displays a listing of the individual bibliographic records grouped within the metarecord. Access the Metarecord Constituent Records page by clicking on the metarecord title on the Search Results page.

This will allow the user to view the results for grouped records.

Show Holds on Bib

Within the staff client, Show Holds on Bib for a metarecord level hold will take the staff member into the Metarecord Constituent Records page.

Global Flag: OPAC Metarecord Hold Formats Attribute

To utilize the metarecord level hold feature, the Global Flag: OPAC Metarecord Hold Formats Attribute must be enabled and its value set at mr_hold_format, which is the system’s default configuration.

Chapter 139. Library Information Pages

The branch name displayed in the copy details section of the search results page, the record summary page, and the kids catalog record summary page will link to a library information page. This page is located at http://hostname/eg/opac/library/<SHORTNAME> and at http://hostname/eg/opac/library/<ID>.

Evergreen automatically generates this page based on information entered in Admin → Server Administration → Organizational Units (actor.org_unit).

The library information page displays:

The name of the library

Opening hours

E-mail address

Phone number

Mailing address

The branch’s parent library system

An Evergreen site can also display a link to the library’s web site on the information page.

To display a link:

Go to Admin → Local Administration → Library Settings Editor.

Edit the Library Information URL setting for the branch.

If you set the URL at the system level, that URL will be used as the link for the system and for all child branches that do not have its own URL set. . Enter the URL in the following format: http://example.com/about.html.

An Evergreen site may also opt to link directly from the copy details section of the catalog to the library web site, bypassing the automatically-generated library information page. To do so:

Add the library’s URL to the Library Information URL setting as described above.

Go to Admin → Local Administration → Library Settings Editor.

Set the Use external "library information URL" in copy table, if available setting to true.

The library information pages publish schema.org structured data, as do parts of the OPAC bibliographic record views, which can enable search engines and other systems to better understand your libraries and their resources.

Chapter 140. Adding OpenSearch to Firefox browser

OpenSearch is a collection of simple formats for the sharing of search results. More information about OpenSearch can be found on their website.

The following example illustrates how to add an OpenSearch source to the list of search sources in a Firefox browser:

Navigate to any catalog page in your Firefox browser and click on the top right box’s dropdown and select the option for Add "Example Consortium OpenSearch". The label will match the current scope.

At this point, it will add a new search option for the location the catalog is currently using. In this example, that is CONS (searching the whole consortium).

Enter search terms to begin a keyword search using this source. The next image illustrates an example search for "mozart" using the sample bib record set.

You can select which search source to use by clicking on the dropdown picker.

Chapter 141. Adding an Evergreen search form to a web page

To enable users to quickly search your Evergreen catalog, you can add a simple search form to any HTML page. The following code demonstrates how to create a quick search box suitable for the header of your web site:

141.1. Simple search form

<form action="http://example.com/eg/opac/results" method="get" accept-charset="UTF-8">    <!--  -->
    <input type="search" alt="Catalog Search" maxlength="200"
            size="20" name="query"
            placeholder="Search catalog for..." />
    <input type="hidden" name="qtype" value="keyword" />           <!--  -->
    <input type="hidden" name="locg" value="4" />                  <!--  -->
    <input type="submit" value="Search" />
</form>

Replace 'example.com' with the hostname for your catalog. To link to the Kid’s OPAC instead of the TPAC, replace 'opac' with 'kpac'.

Replace 'keyword' with 'title', 'author', 'subject', or 'series' if you want to provide more specific searches. You can even specify 'identifier|isbn' for an ISBN search.

Replace '4' with the ID number of the organizational unit at which you wish to anchor your search. This is the value of the 'locg' parameter in your normal search.

141.2. Advanced search form

<form role="search" id="searchForm" method="get" class="searchform" action="http://your_catalog/eg/opac/results" accept-charset="UTF-8">
     <label id="searchLabel" for="search"><b>Search the Catalog: </b></label>
     <input type="search" value="" name="query" id="search" size="30">
     <label id="search_qtype_label"><b>Type:</b>
     <select name="qtype" id="qtype"    aria-label="Select query type:">
        <option value='keyword' selected="selected">Keyword</option>
        <option value='title'>Title</option>
        <option value='jtitle'>Journal Title</option>
        <option value='author'>Author</option>
        <option value='subject'>Subject</option>
        <option value='series'>Series</option>
     </select>
     </label>  &nbsp;&nbsp;

     <label id="search_itype_label"><b>Format: </b>
     <select id='item_type_selector' name='fi:item_type' aria-label="Select item type:">
       <option value=''>All Formats</option>
       <option value='a'>Books and Journals</option>
       <option value='i'>Nonmusical Sound Recording</option>
       <option value='j'>Musical Sound Recording</option>
       <option value='g'>Video</option>
       </select>  &nbsp;&nbsp;
     </label>

    <label id="search_locg_label"><b>Library: </b>
    <select aria-label='Select search library'   name='locg'>
            <option value='1' class="org_unit">
                All Libraries
            </option>
            <option value='2' selected="selected" class="org_unit">
               &nbsp;&nbsp;Central Library
            </option>
             <option value='10'   class="org_unit">
                &nbsp;&nbsp;&nbsp;&nbsp;Little Library
            </option>
     </select>
     </label>
          <input class="searchbutton" type="submit" value="SEarch" />
</form>

141.3. Encoding

For non English characters it is vital to set the attribute accept-charset="UTF-8" in the form tag (as in the examples above). If the parameter is not set, records with non English characters will not be retrieved.

141.4. Setting the document type

You can set the document types to be searched using the attribute option value= in the form. For the value use MARC 21 code defining the type of record (i.e. Leader, position 06).

For example, for musical recordings you could use <option value='j'>Musical Sound Recording</option>

141.5. Setting the library

Instead of searching the entire consortium, you can set the Library to be searched in using the attribute option value= in the form. For the value use Evergreen database.organization unit ID.

Part XIV. Developer Resources

Chapter 142. Introduction

Developers can use this part to learn more about the programming languages, communication protocols and standards used in Evergreen.

Chapter 143. Support Scripts

Various scripts are included with Evergreen in the /openils/bin/ directory (and in the source code in Open-ILS/src/support-scripts and Open-ILS/src/extras). Some of them are used during the installation process, such as eg_db_config, while others are usually run as cron jobs for routine maintenance, such as fine_generator.pl and hold_targeter.pl. Others are useful for less frequent needs, such as the scripts for importing/exporting MARC records. You may explore these scripts and adapt them for your local needs. You are also welcome to share your improvements or ask any questions on the Evergreen IRC channel or email lists.

Here is a summary of the most commonly used scripts. The script name links to more thorough documentation, if available.

action_trigger_runner.pl  — Useful for creating events for specified hooks and running pending events

authority_authority_linker.pl  — Links reference headings in authority records to main entry headings in other authority records. Should be run at least once a day (only for changed records).

authority_control_fields.pl  — Links bibliographic records to the best matching authority record. Should be run at least once a day (only for changed records). You can accomplish this by running authority_control_fields.pl --days-back=1

autogen.sh  — Generates web files used by the OPAC, especially files related to organization unit hierarchy, fieldmapper IDL, locales selection, facet definitions, compressed JS files and related cache key

clark-kent.pl  — Used to start and stop the reporter (which runs scheduled reports)

eg_db_config  — Creates database and schema, updates config files, sets Evergreen administrator username and password

fine_generator.pl

hold_targeter.pl

marc2are.pl  — Converts authority records from MARC format to Evergreen objects suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)

marc2bre.pl  — Converts bibliographic records from MARC format to Evergreen objects suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)

marc2sre.pl  — Converts serial records from MARC format to Evergreen objects suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)

marc_export  — Exports authority, bibliographic, and serial holdings records into any of these formats: USMARC, UNIMARC, XML, BRE, ARE

osrf_control  — Used to start, stop and send signals to OpenSRF services

parallel_pg_loader.pl  — Uses the output of marc2bre.pl (or similar tools) to generate the SQL for importing records into Evergreen in a parallel fashion

143.1. marc_export: Exporting Bibliographic Records into MARC files

The following procedure explains how to export Evergreen bibliographic records into MARC files using the marc_export support script. All steps should be performed by the opensrf user from your Evergreen server.

Processing time for exporting records depends on several factors such as the number of records you are exporting. It is recommended that you divide the export ID files (records.txt) into a manageable number of records if you are exporting a large number of records.

Create a text file list of the Bibliographic record IDs you would like to export from Evergreen. One way to do this is using SQL:

SELECT DISTINCT bre.id FROM biblio.record_entry AS bre
    JOIN asset.call_number AS acn ON acn.record = bre.id
    WHERE bre.deleted='false' and owning_lib=101 \g /home/opensrf/records.txt;

This query creates a file called records.txt containing a column of distinct IDs of items owned by the organizational unit with the id 101.

Navigate to the support-scripts folder

cd /home/opensrf/Evergreen-ILS*/Open-ILS/src/support-scripts/

Run marc_export, using the ID file you created in step 1 to define which files to export. The following example exports the records into MARCXML format.

cat /home/opensrf/records.txt | ./marc_export --store -i -c /openils/conf/opensrf_core.xml \
    -x /openils/conf/fm_IDL.xml -f XML --timeout 5 > exported_files.xml

marc_export was updated in Evergreen 2.6 and now does not output progress as it executes.

You can use the --since option to export records modified after a certain date and time.

By default, marc_export will use the reporter storage service, which should work in most cases. But if you have a separate reporter database and you know you want to talk directly to your main production database, then you can set the --store option to cstore or storage.

For more information, run marc_export with the -h option:

./marc_export -h

143.2. Importing Authority Records from Command Line

The major advantages of the command line approach are its speed and its convenience for system administrators who can perform bulk loads of authority records in a controlled environment. For alternate instructions, see Importing Authority Records from the Staff Client.

Run marc2are.pl against the authority records, specifying the user name, password, MARC type (USMARC or XML). Use STDOUT redirection to either pipe the output directly into the next command or into an output file for inspection. For example, to process a file with authority records in MARCXML format named auth_small.xml using the default user name and password, and directing the output into a file named auth.are:

cd Open-ILS/src/extras/import/
perl marc2are.pl --user admin --pass open-ils --marctype XML auth_small.xml > auth.are

The MARC type will default to USMARC if the --marctype option is not specified.

Run parallel_pg_loader.pl to generate the SQL necessary for importing the authority records into your system. This script will create files in your current directory with filenames like pg_loader-output.are.sql and pg_loader-output.sql (which runs the previous SQL file). To continue with the previous example by processing our new auth.are file:

cd Open-ILS/src/extras/import/
perl parallel_pg_loader.pl --auto are --order are auth.are

To save time for very large batches of records, you could simply pipe the output of marc2are.pl directly into parallel_pg_loader.pl.

Load the authority records from the SQL file that you generated in the last step into your Evergreen database using the psql tool. Assuming the default user name, host name, and database name for an Evergreen instance, that command looks like:

psql -U evergreen -h localhost -d evergreen -f pg_loader-output.sql

143.3. MARC Stream Importer

The MARC Stream Importer can import authority records or bibliographic records. A single running instance of the script can import either type of record, based on the record leader.

This support script has its own configuration file, marc_stream_importer.conf, which includes settings related to logs, ports, uses, and access control.

The importer is even more flexible than the staff client import, including the following options:

--bib-auto-overlay-exact and --auth-auto-overlay-exact: overlay/merge on exact 901c matches

--bib-auto-overlay-1match and --auth-auto-overlay-1match: overlay/merge when exactly one match is found

--bib-auto-overlay-best-match and --auth-auto-overlay-best-match: overlay/merge on best match

--bib-import-no-match and --auth-import-no-match: import when no match is found

One advantage to using this tool instead of the staff client Import interface is that the MARC Stream Importer can load a group of files at once.

Chapter 144. Developing with pgTAP tests

144.1. Setting up pgTAP on your development server

Currently, Evergreen pgTAP tests expect a version of pgTAP (0.93) that is not yet available in the packages for most Linux distributions. Therefore, you will have to install pgTAP from source as follows:

Download, make, and install pgTAP on your database server. pgTAP can be downloaded from http://pgxn.org/dist/pgtap/ and the instructions for building and installing the extension are available from http://pgtap.org/documentation.html

Create the pgTAP extension in your Evergreen database. Using psql, connect to your Evergreen database and then issue the command:

CREATE EXTENSION pgtap;

144.2. Running pgTAP tests

The pgTAP tests can be found in subdirectories of Open-ILS/src/sql/Pg/ as follows:

t: contains pgTAP unit tests that can be run on a freshly installed Evergreen database

live_t: contains pgTAP unit tests meant to be run on an Evergreen database that also has had the "concerto" sample data loaded on it

To run the pgTAP unit and regression tests, use the pg_prove command. For example, from the Evergreen source directory, you can issue the command: pg_prove -U evergreen Open-ILS/src/sql/Pg/t Open-ILS/src/sql/Pg/t/regress

Chapter 145. Easing gently into OpenSRF

145.1. Abstract

The Evergreen open-source library system serves library consortia composed of hundreds of branches with millions of patrons - for example, the Georgia Public Library Service PINES system. One of the claimed advantages of Evergreen over alternative integrated library systems is the underlying Open Service Request Framework (OpenSRF, pronounced "open surf") architecture. This article introduces OpenSRF, demonstrates how to build OpenSRF services through simple code examples, and explains the technical foundations on which OpenSRF is built.

145.2. Introducing OpenSRF

OpenSRF is a message routing network that offers scalability and failover support for individual services and entire servers with minimal development and deployment overhead. You can use OpenSRF to build loosely-coupled applications that can be deployed on a single server or on clusters of geographically distributed servers using the same code and minimal configuration changes. Although copyright statements on some of the OpenSRF code date back to Mike Rylander’s original explorations in 2000, Evergreen was the first major application to be developed with, and to take full advantage of, the OpenSRF architecture starting in 2004. The first official release of OpenSRF was 0.1 in February 2005 (http://evergreen-ils.org/blog/?p=21), but OpenSRF’s development continues a steady pace of enhancement and refinement, with the release of 1.0.0 in October 2008 and the most recent release of 1.2.2 in February 2010.

OpenSRF is a distinct break from the architectural approach used by previous library systems and has more in common with modern Web applications. The traditional "scale-up" approach to serve more transactions is to purchase a server with more CPUs and more RAM, possibly splitting the load between a Web server, a database server, and a business logic server. Evergreen, however, is built on the Open Service Request Framework (OpenSRF) architecture, which firmly embraces the "scale-out" approach of spreading transaction load over cheap commodity servers. The initial GPLS PINES hardware cluster, while certainly impressive, may have offered the misleading impression that Evergreen is complex and requires a lot of hardware to run.

This article hopes to correct any such lingering impression by demonstrating that OpenSRF itself is an extremely simple architecture on which one can easily build applications of many kinds – not just library applications – and that you can use a number of different languages to call and implement OpenSRF methods with a minimal learning curve. With an application built on OpenSRF, when you identify a bottleneck in your application’s business logic layer, you can adjust the number of the processes serving that particular bottleneck on each of your servers; or if the problem is that your service is resource-hungry, you could add an inexpensive server to your cluster and dedicate it to running that resource-hungry service.

145.2.1. Programming language support

If you need to develop an entirely new OpenSRF service, you can choose from a number of different languages in which to implement that service. OpenSRF client language bindings have been written for C, Java, JavaScript, Perl, and Python, and server language bindings have been written for C, Perl, and Python. This article uses Perl examples as a lowest common denominator programming language. Writing an OpenSRF binding for another language is a relatively small task if that language offers libraries that support the core technologies on which OpenSRF depends:

Extensible Messaging and Presence Protocol (XMPP, sometimes referred to as Jabber) - provides the base messaging infrastructure between OpenSRF clients and servers

JavaScript Object Notation (JSON) - serializes the content of each XMPP message in a standardized and concise format

memcached - provides the caching service

syslog - the standard UNIX logging service

Unfortunately, the OpenSRF reference documentation, although augmented by the OpenSRF glossary, blog posts like the description of OpenSRF and Jabber, and even this article, is not a sufficient substitute for a complete specification on which one could implement a language binding. The recommended option for would-be developers of another language binding is to use the Python implementation as the cleanest basis for a port to another language.

145.2.2. OpenSRF communication flows over XMPP

The XMPP messaging service underpins OpenSRF, requiring an XMPP server such as ejabberd. When you start OpenSRF, the first XMPP clients that connect to the XMPP server are the OpenSRF public and private routers. OpenSRF routers maintain a list of available services and connect clients to available services. When an OpenSRF service starts, it establishes a connection to the XMPP server and registers itself with the private router. The OpenSRF configuration contains a list of public OpenSRF services, each of which must also register with the public router. Services and clients connect to the XMPP server using a single set of XMPP client credentials (for example, opensrf@private.localhost), but use XMPP resource identifiers to differentiate themselves in the Jabber ID (JID) for each connection. For example, the JID for a copy of the opensrf.simple-text service with process ID 6285 that has connected to the private.localhost domain using the opensrf XMPP client credentials could be opensrf@private.localhost/opensrf.simple-text_drone_at_localhost_6285.

145.2.3. OpenSRF communication flows over HTTP

Any OpenSRF service registered with the public router is accessible via the OpenSRF HTTP Translator. The OpenSRF HTTP Translator implements the OpenSRF-over-HTTP proposed specification as an Apache module that translates HTTP requests into OpenSRF requests and returns OpenSRF results as HTTP results to the initiating HTTP client.

Issuing an HTTP POST request to an OpenSRF method via the OpenSRF HTTP Translator. 

# curl request broken up over multiple lines for legibility
curl -H "X-OpenSRF-service: opensrf.simple-text"                                \ #
    --data 'osrf-msg=[                                                          \ #
        {"__c":"osrfMessage","__p":{"threadTrace":0,"locale":"en-CA",           \ #
            "type":"REQUEST","payload": {"__c":"osrfMethod","__p":              \
                {"method":"opensrf.simple-text.reverse","params":["foobar"]}    \
            }}                                                                  \
        }]'                                                                     \
http://localhost/osrf-http-translator                                           \ #

The X-OpenSRF-service header identifies the OpenSRF service of interest.

The POST request consists of a single parameter, the osrf-msg value, which contains a JSON array.

The first object is an OpenSRF message ("__c":"osrfMessage") with a set of parameters ("__p":{}) containing:

the identifier for the request ("threadTrace":0); this value is echoed back in the result

the message type ("type":"REQUEST")

the locale for the message; if the OpenSRF method is locale-sensitive, it can check the locale for each OpenSRF request and return different information depending on the locale

the payload of the message ("payload":{}) containing the OpenSRF method request ("__c":"osrfMethod") and its parameters ("__p:"{}), which in turn contains:

the method name for the request ("method":"opensrf.simple-text.reverse")

a set of JSON parameters to pass to the method ("params":["foobar"]); in this case, a single string "foobar"

The URL on which the OpenSRF HTTP translator is listening, /osrf-http-translator is the default location in the Apache example configuration files shipped with the OpenSRF source, but this is configurable.

Results from an HTTP POST request to an OpenSRF method via the OpenSRF HTTP Translator. 

# HTTP response broken up over multiple lines for legibility
[{"__c":"osrfMessage","__p":                                                    \ #
    {"threadTrace":0, "payload":                                                \ #
        {"__c":"osrfResult","__p":                                              \ #
            {"status":"OK","content":"raboof","statusCode":200}                 \ #
        },"type":"RESULT","locale":"en-CA"                                      \ #
    }
},
{"__c":"osrfMessage","__p":                                                     \ #
    {"threadTrace":0,"payload":                                                 \ #
        {"__c":"osrfConnectStatus","__p":                                       \ #
            {"status":"Request Complete","statusCode":205}                      \ #
        },"type":"STATUS","locale":"en-CA"                                      \ #
    }
}]

The OpenSRF HTTP Translator returns an array of JSON objects in its response. Each object in the response is an OpenSRF message ("__c":"osrfMessage") with a collection of response parameters ("__p":).

The OpenSRF message identifier ("threadTrace":0) confirms that this message is in response to the request matching the same identifier.

The message includes a payload JSON object ("payload":) with an OpenSRF result for the request ("__c":"osrfResult").

The result includes a status indicator string ("status":"OK"), the content of the result response - in this case, a single string "raboof" ("content":"raboof") - and an integer status code for the request ("statusCode":200).

The message also includes the message type ("type":"RESULT") and the message locale ("locale":"en-CA").

The second message in the set of results from the response.

Again, the message identifier confirms that this message is in response to a particular request.

The payload of the message denotes that this message is an OpenSRF connection status message ("__c":"osrfConnectStatus"), with some information about the particular OpenSRF connection that was used for this request.

The response parameters for an OpenSRF connection status message include a verbose status ("status":"Request Complete") and an integer status code for the connection status (`"statusCode":205).

The message also includes the message type ("type":"RESULT") and the message locale ("locale":"en-CA").

Before adding a new public OpenSRF service, ensure that it does not introduce privilege escalation or unchecked access to data. For example, the Evergreen open-ils.cstore private service is an object-relational mapper that provides read and write access to the entire Evergreen database, so it would be catastrophic to expose that service publicly. In comparison, the Evergreen open-ils.pcrud public service offers the same functionality as open-ils.cstore to any connected HTTP client or OpenSRF client, but the additional authentication and authorization layer in open-ils.pcrud prevents unchecked access to Evergreen’s data.

145.2.4. Stateless and stateful connections

OpenSRF supports both stateless and stateful connections. When an OpenSRF client issues a REQUEST message in a stateless connection, the router forwards the request to the next available service and the service returns the result directly to the client.

REQUEST flow in a stateless connection. REQUEST flow in a stateless connection

When an OpenSRF client issues a CONNECT message to create a stateful connection, the router returns the Jabber ID of the next available service to the client so that the client can issue one or more REQUEST message directly to that particular service and the service will return corresponding RESULT messages directly to the client. Until the client issues a DISCONNECT message, that particular service is only available to the requesting client. Stateful connections are useful for clients that need to make many requests from a particular service, as it avoids the intermediary step of contacting the router for each request, as well as for operations that require a controlled sequence of commands, such as a set of database INSERT, UPDATE, and DELETE statements within a transaction.

CONNECT, REQUEST, and DISCONNECT flow in a stateful connection. CONNECT

145.3. Enough jibber-jabber: writing an OpenSRF service

Imagine an application architecture in which 10 lines of Perl or Python, using the data types native to each language, are enough to implement a method that can then be deployed and invoked seamlessly across hundreds of servers. You have just imagined developing with OpenSRF – it is truly that simple. Under the covers, of course, the OpenSRF language bindings do an incredible amount of work on behalf of the developer. An OpenSRF application consists of one or more OpenSRF services that expose methods: for example, the opensrf.simple-text demonstration service exposes the opensrf.simple-text.split() and opensrf.simple-text.reverse() methods. Each method accepts zero or more arguments and returns zero or one results. The data types supported by OpenSRF arguments and results are typical core language data types: strings, numbers, booleans, arrays, and hashes.

To implement a new OpenSRF service, perform the following steps:

Include the base OpenSRF support libraries

Write the code for each of your OpenSRF methods as separate procedures

Register each method

Add the service definition to the OpenSRF configuration files

For example, the following code implements an OpenSRF service. The service includes one method named opensrf.simple-text.reverse() that accepts one string as input and returns the reversed version of that string:

#!/usr/bin/perl

package OpenSRF::Application::Demo::SimpleText;

use strict;

use OpenSRF::Application;
use parent qw/OpenSRF::Application/;

sub text_reverse {
    my ($self , $conn, $text) = @_;
    my $reversed_text = scalar reverse($text);
    return $reversed_text;
}

__PACKAGE__->register_method(
    method    => 'text_reverse',
    api_name  => 'opensrf.simple-text.reverse'
);

Ten lines of code, and we have a complete OpenSRF service that exposes a single method and could be deployed quickly on a cluster of servers to meet your application’s ravenous demand for reversed strings! If you’re unfamiliar with Perl, the use OpenSRF::Application; use parent qw/OpenSRF::Application/; lines tell this package to inherit methods and properties from the OpenSRF::Application module. For example, the call to __PACKAGE__->register_method() is defined in OpenSRF::Application but due to inheritance is available in this package (named by the special Perl symbol __PACKAGE__ that contains the current package name). The register_method() procedure is how we introduce a method to the rest of the OpenSRF world.

145.3.1. Registering a service with the OpenSRF configuration files

Two files control most of the configuration for OpenSRF:

opensrf.xml contains the configuration for the service itself as well as a list of which application servers in your OpenSRF cluster should start the service

opensrf_core.xml (often referred to as the "bootstrap configuration" file) contains the OpenSRF networking information, including the XMPP server connection credentials for the public and private routers; you only need to touch this for a new service if the new service needs to be accessible via the public router

Begin by defining the service itself in opensrf.xml. To register the opensrf.simple-text service, add the following section to the <apps> element (corresponding to the XPath /opensrf/default/apps/):

<apps>
  <opensrf.simple-text>                                                      <!--  -->
    <keepalive>3</keepalive>                                                 <!--  -->
    <stateless>1</stateless>                                                 <!--  -->
    <language>perl</language>                                                <!--  -->
    <implementation>OpenSRF::Application::Demo::SimpleText</implementation>  <!--  -->
    <max_requests>100</max_requests>                                         <!--  -->
    <unix_config>
      <max_requests>1000</max_requests>                                      <!--  -->
      <unix_log>opensrf.simple-text_unix.log</unix_log>                      <!--  -->
      <unix_sock>opensrf.simple-text_unix.sock</unix_sock>                   <!--  -->
      <unix_pid>opensrf.simple-text_unix.pid</unix_pid>                     <!--  -->
      <min_children>5</min_children>                                        <!-- (11) -->
      <max_children>15</max_children>                                       <!-- (12) -->
      <min_spare_children>2</min_spare_children>                            <!-- (13) -->
      <max_spare_children>5</max_spare_children>                            <!-- (14) -->
    </unix_config>
  </opensrf.simple-text>

  <!-- other OpenSRF services registered here... -->
</apps>

The element name is the name that the OpenSRF control scripts use to refer to the service.

Specifies the interval (in seconds) between checks to determine if the service is still running.

Specifies whether OpenSRF clients can call methods from this service without first having to create a connection to a specific service backend process for that service. If the value is 1, then the client can simply issue a request and the router will forward the request to an available service and the result will be returned directly to the client.

Specifies the programming language in which the service is implemented

Specifies the name of the library or module in which the service is implemented

(C implementations): Specifies the maximum number of requests a process serves before it is killed and replaced by a new process.

(Perl implementations): Specifies the maximum number of requests a process serves before it is killed and replaced by a new process.

The name of the log file for language-specific log messages such as syntax warnings.

The name of the UNIX socket used for inter-process communications.

The name of the PID file for the master process for the service.

(11)

The minimum number of child processes that should be running at any given time.

(12)

The maximum number of child processes that should be running at any given time.

(13)

The minimum number of child processes that should be available to handle incoming requests. If there are fewer than this number of spare child processes, new processes will be spawned.

(14)

The maximum number of child processes that should be available to handle incoming requests. If there are more than this number of spare child processes, the extra processes will be killed.

To make the service accessible via the public router, you must also edit the opensrf_core.xml configuration file to add the service to the list of publicly accessible services:

Making a service publicly accessible in opensrf_core.xml. 

<router>                                                                     <!--  -->
    <!-- This is the public router. On this router, we only register applications
     which should be accessible to everyone on the opensrf network -->
    <name>router</name>
    <domain>public.localhost</domain>                                        <!--  -->
    <services>
        <service>opensrf.math</service>
        <service>opensrf.simple-text</service>                               <!--  -->
    </services>
</router>

This section of the opensrf_core.xml file is located at XPath /config/opensrf/routers/.

public.localhost is the canonical public router domain in the OpenSRF installation instructions.

Each <service> element contained in the <services> element offers their services via the public router as well as the private router.

Once you have defined the new service, you must restart the OpenSRF Router to retrieve the new configuration and start or restart the service itself.

145.3.2. Calling an OpenSRF method

OpenSRF clients in any supported language can invoke OpenSRF services in any supported language. So let’s see a few examples of how we can call our fancy new opensrf.simple-text.reverse() method:

145.3.2.1. Calling OpenSRF methods from the srfsh client

srfsh is a command-line tool installed with OpenSRF that you can use to call OpenSRF methods. To call an OpenSRF method, issue the request command and pass the OpenSRF service and method name as the first two arguments; then pass a list of JSON objects as the arguments to the method being invoked.

The following example calls the opensrf.simple-text.reverse method of the opensrf.simple-text OpenSRF service, passing the string "foobar" as the only method argument:

$ srfsh
srfsh # request opensrf.simple-text opensrf.simple-text.reverse "foobar"

Received Data: "raboof"

=------------------------------------
Request Completed Successfully
Request Time in seconds: 0.016718
=------------------------------------

145.3.2.2. Getting documentation for OpenSRF methods from the srfsh client

The srfsh client also gives you command-line access to retrieving metadata about OpenSRF services and methods. For a given OpenSRF method, for example, you can retrieve information such as the minimum number of required arguments, the data type and a description of each argument, the package or library in which the method is implemented, and a description of the method. To retrieve the documentation for an opensrf method from srfsh, issue the introspect command, followed by the name of the OpenSRF service and (optionally) the name of the OpenSRF method. If you do not pass a method name to the introspect command, srfsh lists all of the methods offered by the service. If you pass a partial method name, srfsh lists all of the methods that match that portion of the method name.

The quality and availability of the descriptive information for each method depends on the developer to register the method with complete and accurate information. The quality varies across the set of OpenSRF and Evergreen APIs, although some effort is being put towards improving the state of the internal documentation.

srfsh# introspect opensrf.simple-text "opensrf.simple-text.reverse"
--> opensrf.simple-text

Received Data: {
  "__c":"opensrf.simple-text",
  "__p":{
    "api_level":1,
    "stream":0,                                                      \ #
    "object_hint":"OpenSRF_Application_Demo_SimpleText",
    "remote":0,
    "package":"OpenSRF::Application::Demo::SimpleText",              \ #
    "api_name":"opensrf.simple-text.reverse",                        \ #
    "server_class":"opensrf.simple-text",
    "signature":{                                                    \ #
      "params":[                                                     \ #
        {
          "desc":"The string to reverse",
          "name":"text",
          "type":"string"
        }
      ],
      "desc":"Returns the input string in reverse order\n",          \ #
      "return":{                                                     \ #
        "desc":"Returns the input string in reverse order",
        "type":"string"
      }
    },
    "method":"text_reverse",                                         \ #
    "argc":1                                                         \ #
  }
}

stream denotes whether the method supports streaming responses or not.

package identifies which package or library implements the method.

api_name identifies the name of the OpenSRF method.

signature is a hash that describes the parameters for the method.

params is an array of hashes describing each parameter in the method; each parameter has a description (desc), name (name), and type (type).

desc is a string that describes the method itself.

return is a hash that describes the return value for the method; it contains a description of the return value (desc) and the type of the returned value (type).

method identifies the name of the function or method in the source implementation.

argc is an integer describing the minimum number of arguments that must be passed to this method.

145.3.2.3. Calling OpenSRF methods from Perl applications

To call an OpenSRF method from Perl, you must connect to the OpenSRF service, issue the request to the method, and then retrieve the results.

#/usr/bin/perl
use strict;
use OpenSRF::AppSession;
use OpenSRF::System;

OpenSRF::System->bootstrap_client(config_file => '/openils/conf/opensrf_core.xml'); #

my $session = OpenSRF::AppSession->create("opensrf.simple-text");                   #

print "substring: Accepts a string and a number as input, returns a string\n";
my $result = $session->request("opensrf.simple-text.substring", "foobar", 3);       #
my $request = $result->gather();                                                    #
print "Substring: $request\n\n";

print "split: Accepts two strings as input, returns an array of strings\n";
$request = $session->request("opensrf.simple-text.split", "This is a test", " ");   #
my $output = "Split: [";
my $element;
while ($element = $request->recv()) {                                               #
    $output .= $element->content . ", ";                                            #
}
$output =~ s/, $/]/;
print $output . "\n\n";

print "statistics: Accepts an array of strings as input, returns a hash\n";
my @many_strings = [
    "First I think I'll have breakfast",
    "Then I think that lunch would be nice",
    "And then seventy desserts to finish off the day"
];

$result = $session->request("opensrf.simple-text.statistics", @many_strings);       #
$request = $result->gather();                                                       #
print "Length: " . $result->{'length'} . "\n";
print "Word count: " . $result->{'word_count'} . "\n";

$session->disconnect();                                                             #

The OpenSRF::System->bootstrap_client() method reads the OpenSRF configuration information from the indicated file and creates an XMPP client connection based on that information.

The OpenSRF::AppSession->create() method accepts one argument - the name of the OpenSRF service to which you want to want to make one or more requests - and returns an object prepared to use the client connection to make those requests.

The OpenSRF::AppSession->request() method accepts a minimum of one argument - the name of the OpenSRF method to which you want to make a request - followed by zero or more arguments to pass to the OpenSRF method as input values. This example passes a string and an integer to the opensrf.simple-text.substring method defined by the opensrf.simple-text OpenSRF service.

The gather() method, called on the result object returned by the request() method, iterates over all of the possible results from the result object and returns a single variable.

This request() call passes two strings to the opensrf.simple-text.split method defined by the opensrf.simple-text OpenSRF service and returns (via gather()) a reference to an array of results.

The opensrf.simple-text.split() method is a streaming method that returns an array of results with one element per recv() call on the result object. We could use the gather() method to retrieve all of the results in a single array reference, but instead we simply iterate over the result variable until there are no more results to retrieve.

While the gather() convenience method returns only the content of the complete set of results for a given request, the recv() method returns an OpenSRF result object with status, statusCode, and content fields as we saw in the HTTP results example.

This request() call passes an array to the opensrf.simple-text.statistics method defined by the opensrf.simple-text OpenSRF service.

The result object returns a hash reference via gather(). The hash contains the length and word_count keys we defined in the method.

The OpenSRF::AppSession->disconnect() method closes the XMPP client connection and cleans up resources associated with the session.

145.3.3. Accepting and returning more interesting data types

Of course, the example of accepting a single string and returning a single string is not very interesting. In real life, our applications tend to pass around multiple arguments, including arrays and hashes. Fortunately, OpenSRF makes that easy to deal with; in Perl, for example, returning a reference to the data type does the right thing. In the following example of a method that returns a list, we accept two arguments of type string: the string to be split, and the delimiter that should be used to split the string.

Text splitting method - streaming mode. 

sub text_split {
    my $self = shift;
    my $conn = shift;
    my $text = shift;
    my $delimiter = shift || ' ';

    my @split_text = split $delimiter, $text;
    return \@split_text;
}

__PACKAGE__->register_method(
    method    => 'text_split',
    api_name  => 'opensrf.simple-text.split'
);

We simply return a reference to the list, and OpenSRF does the rest of the work for us to convert the data into the language-independent format that is then returned to the caller. As a caller of a given method, you must rely on the documentation used to register to determine the data structures - if the developer has added the appropriate documentation.

145.3.4. Accepting and returning Evergreen objects

OpenSRF is agnostic about objects; its role is to pass JSON back and forth between OpenSRF clients and services, and it allows the specific clients and services to define their own semantics for the JSON structures. On top of that infrastructure, Evergreen offers the fieldmapper: an object-relational mapper that provides a complete definition of all objects, their properties, their relationships to other objects, the permissions required to create, read, update, or delete objects of that type, and the database table or view on which they are based.

The Evergreen fieldmapper offers a great deal of convenience for working with complex system objects beyond the basic mapping of classes to database schemas. Although the result is passed over the wire as a JSON object containing the indicated fields, fieldmapper-aware clients then turn those JSON objects into native objects with setter / getter methods for each field.

All of this metadata about Evergreen objects is defined in the fieldmapper configuration file (/openils/conf/fm_IDL.xml), and access to these classes is provided by the open-ils.cstore, open-ils.pcrud, and open-ils.reporter-store OpenSRF services which parse the fieldmapper configuration file and dynamically register OpenSRF methods for creating, reading, updating, and deleting all of the defined classes.

Example fieldmapper class definition for "Open User Summary". 

<class id="mous" controller="open-ils.cstore open-ils.pcrud"
 oils_obj:fieldmapper="money::open_user_summary"
 oils_persist:tablename="money.open_usr_summary"
 reporter:label="Open User Summary">                                       <!--  -->
    <fields oils_persist:primary="usr" oils_persist:sequence="">           <!--  -->
        <field name="balance_owed" reporter:datatype="money" />            <!--  -->
        <field name="total_owed" reporter:datatype="money" />
        <field name="total_paid" reporter:datatype="money" />
        <field name="usr" reporter:datatype="link"/>
    </fields>
    <links>
        <link field="usr" reltype="has_a" key="id" map="" class="au"/>     <!--  -->
    </links>
    <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1">  <!--  -->
        <actions>
            <retrieve permission="VIEW_USER">                              <!--  -->
                <context link="usr" field="home_ou"/>                      <!--  -->
            </retrieve>
        </actions>
    </permacrud>
</class>

The <class> element defines the class:

The id attribute defines the class hint that identifies the class both elsewhere in the fieldmapper configuration file, such as in the value of the field attribute of the <link> element, and in the JSON object itself when it is instantiated. For example, an "Open User Summary" JSON object would have the top level property of "__c":"mous".

The controller attribute identifies the services that have direct access to this class. If open-ils.pcrud is not listed, for example, then there is no means to directly access members of this class through a public service.

The oils_obj:fieldmapper attribute defines the name of the Perl fieldmapper class that will be dynamically generated to provide setter and getter methods for instances of the class.

The oils_persist:tablename attribute identifies the schema name and table name of the database table that stores the data that represents the instances of this class. In this case, the schema is money and the table is open_usr_summary.

The reporter:label attribute defines a human-readable name for the class used in the reporting interface to identify the class. These names are defined in English in the fieldmapper configuration file; however, they are extracted so that they can be translated and served in the user’s language of choice.

The <fields> element lists all of the fields that belong to the object.

The oils_persist:primary attribute identifies the field that acts as the primary key for the object; in this case, the field with the name usr.

The oils_persist:sequence attribute identifies the sequence object (if any) in this database provides values for new instances of this class. In this case, the primary key is defined by a field that is linked to a different table, so no sequence is used to populate these instances.

Each <field> element defines a single field with the following attributes:

The name attribute identifies the column name of the field in the underlying database table as well as providing a name for the setter / getter method that can be invoked in the JSON or native version of the object.

The reporter:datatype attribute defines how the reporter should treat the contents of the field for the purposes of querying and display.

The reporter:label attribute can be used to provide a human-readable name for each field; without it, the reporter falls back to the value of the name attribute.

The <links> element contains a set of zero or more <link> elements, each of which defines a relationship between the class being described and another class.

The field attribute identifies the field named in this class that links to the external class.

The reltype attribute identifies the kind of relationship between the classes; in the case of has_a, each value in the usr field is guaranteed to have a corresponding value in the external class.

The key attribute identifies the name of the field in the external class to which this field links.

The rarely-used map attribute identifies a second class to which the external class links; it enables this field to define a direct relationship to an external class with one degree of separation, to avoid having to retrieve all of the linked members of an intermediate class just to retrieve the instances from the actual desired target class.

The class attribute identifies the external class to which this field links.

The <permacrud> element defines the permissions that must have been granted to a user to operate on instances of this class.

The <retrieve> element is one of four possible children of the <actions> element that define the permissions required for each action: create, retrieve, update, and delete.

The permission attribute identifies the name of the permission that must have been granted to the user to perform the action.

The contextfield attribute, if it exists, defines the field in this class that identifies the library within the system for which the user must have privileges to work. If a user has been granted a given permission, but has not been granted privileges to work at a given library, they can not perform the action at that library.

The rarely-used <context> element identifies a linked field (link attribute) in this class which links to an external class that holds the field (field attribute) that identifies the library within the system for which the user must have privileges to work.

When you retrieve an instance of a class, you can ask for the result to flesh some or all of the linked fields of that class, so that the linked instances are returned embedded directly in your requested instance. In that same request you can ask for the fleshed instances to in turn have their linked fields fleshed. By bundling all of this into a single request and result sequence, you can avoid the network overhead of requiring the client to request the base object, then request each linked object in turn.

You can also iterate over a collection of instances and set the automatically generated isdeleted, isupdated, or isnew properties to indicate that the given instance has been deleted, updated, or created respectively. Evergreen can then act in batch mode over the collection to perform the requested actions on any of the instances that have been flagged for action.

145.3.5. Returning streaming results

In the previous implementation of the opensrf.simple-text.split method, we returned a reference to the complete array of results. For small values being delivered over the network, this is perfectly acceptable, but for large sets of values this can pose a number of problems for the requesting client. Consider a service that returns a set of bibliographic records in response to a query like "all records edited in the past month"; if the underlying database is relatively active, that could result in thousands of records being returned as a single network request. The client would be forced to block until all of the results are returned, likely resulting in a significant delay, and depending on the implementation, correspondingly large amounts of memory might be consumed as all of the results are read from the network in a single block.

OpenSRF offers a solution to this problem. If the method returns results that can be divided into separate meaningful units, you can register the OpenSRF method as a streaming method and enable the client to loop over the results one unit at a time until the method returns no further results. In addition to registering the method with the provided name, OpenSRF also registers an additional method with .atomic appended to the method name. The .atomic variant gathers all of the results into a single block to return to the client, giving the caller the ability to choose either streaming or atomic results from a single method definition.

In the following example, the text splitting method has been reimplemented to support streaming; very few changes are required:

Text splitting method - streaming mode. 

sub text_split {
    my $self = shift;
    my $conn = shift;
    my $text = shift;
    my $delimiter = shift || ' ';

    my @split_text = split $delimiter, $text;
    foreach my $string (@split_text) {           #
        $conn->respond($string);
    }
    return undef;
}

__PACKAGE__->register_method(
    method    => 'text_split',
    api_name  => 'opensrf.simple-text.split',
    stream    => 1                              #
);

Rather than returning a reference to the array, a streaming method loops over the contents of the array and invokes the respond() method of the connection object on each element of the array.

Registering the method as a streaming method instructs OpenSRF to also register an atomic variant (opensrf.simple-text.split.atomic).

145.3.6. Error! Warning! Info! Debug!

As hard as it may be to believe, it is true: applications sometimes do not behave in the expected manner, particularly when they are still under development. The server language bindings for OpenSRF include integrated support for logging messages at the levels of ERROR, WARNING, INFO, DEBUG, and the extremely verbose INTERNAL to either a local file or to a syslogger service. The destination of the log files, and the level of verbosity to be logged, is set in the opensrf_core.xml configuration file. To add logging to our Perl example, we just have to add the OpenSRF::Utils::Logger package to our list of used Perl modules, then invoke the logger at the desired logging level.

You can include many calls to the OpenSRF logger; only those that are higher than your configured logging level will actually hit the log. The following example exercises all of the available logging levels in OpenSRF:

use OpenSRF::Utils::Logger;
my $logger = OpenSRF::Utils::Logger;
# some code in some function
{
    $logger->error("Hmm, something bad DEFINITELY happened!");
    $logger->warn("Hmm, something bad might have happened.");
    $logger->info("Something happened.");
    $logger->debug("Something happened; here are some more details.");
    $logger->internal("Something happened; here are all the gory details.")
}

If you call the mythical OpenSRF method containing the preceding OpenSRF logger statements on a system running at the default logging level of INFO, you will only see the INFO, WARN, and ERR messages, as follows:

Results of logging calls at the default level of INFO. 

[2010-03-17 22:27:30] opensrf.simple-text [ERR :5681:SimpleText.pm:277:] Hmm, something bad DEFINITELY happened!
[2010-03-17 22:27:30] opensrf.simple-text [WARN:5681:SimpleText.pm:278:] Hmm, something bad might have happened.
[2010-03-17 22:27:30] opensrf.simple-text [INFO:5681:SimpleText.pm:279:] Something happened.

If you then increase the the logging level to INTERNAL (5), the logs will contain much more information, as follows:

Results of logging calls at the default level of INTERNAL. 

[2010-03-17 22:48:11] opensrf.simple-text [ERR :5934:SimpleText.pm:277:] Hmm, something bad DEFINITELY happened!
[2010-03-17 22:48:11] opensrf.simple-text [WARN:5934:SimpleText.pm:278:] Hmm, something bad might have happened.
[2010-03-17 22:48:11] opensrf.simple-text [INFO:5934:SimpleText.pm:279:] Something happened.
[2010-03-17 22:48:11] opensrf.simple-text [DEBG:5934:SimpleText.pm:280:] Something happened; here are some more details.
[2010-03-17 22:48:11] opensrf.simple-text [INTL:5934:SimpleText.pm:281:] Something happened; here are all the gory details.
[2010-03-17 22:48:11] opensrf.simple-text [ERR :5934:SimpleText.pm:283:] Resolver did not find a cache hit
[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:Cache.pm:125:] Stored opensrf.simple-text.test_cache.masaa => "here" in memcached server
[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:Application.pm:579:] Coderef for [OpenSRF::Application::Demo::SimpleText::test_cache] has been run
[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:Application.pm:586:] A top level Request object is responding de nada
[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:Application.pm:190:] Method duration for [opensrf.simple-text.test_cache]:  10.005
[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:AppSession.pm:780:] Calling queue_wait(0)
[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:AppSession.pm:769:] Resending...0
[2010-03-17 22:48:21] opensrf.simple-text [INTL:5934:AppSession.pm:450:] In send
[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:AppSession.pm:506:] AppSession sending RESULT to opensrf@private.localhost/_dan-karmic-liblap_1268880489.752154_5943 with threadTrace [1]
[2010-03-17 22:48:21] opensrf.simple-text [DEBG:5934:AppSession.pm:506:] AppSession sending STATUS to opensrf@private.localhost/_dan-karmic-liblap_1268880489.752154_5943 with threadTrace [1]
...

To see everything that is happening in OpenSRF, try leaving your logging level set to INTERNAL for a few minutes - just ensure that you have a lot of free disk space available if you have a moderately busy system!

145.3.7. Caching results: one secret of scalability

If you have ever used an application that depends on a remote Web service outside of your control-say, if you need to retrieve results from a microblogging service-you know the pain of latency and dependability (or the lack thereof). To improve response time in OpenSRF applications, you can take advantage of the support offered by the OpenSRF::Utils::Cache module for communicating with a local instance or cluster of memcache daemons to store and retrieve persistent values.

use OpenSRF::Utils::Cache;                                       #
sub test_cache {
    my $self = shift;
    my $conn = shift;
    my $test_key = shift;
    my $cache = OpenSRF::Utils::Cache->new('global');            #
    my $cache_key = "opensrf.simple-text.test_cache.$test_key";  #
    my $result = $cache->get_cache($cache_key) || undef;         #
    if ($result) {
        $logger->info("Resolver found a cache hit");
        return $result;
    }
    sleep 10;                                                    #
    my $cache_timeout = 300;                                     #
    $cache->put_cache($cache_key, "here", $cache_timeout);       #
    return "There was no cache hit.";
}

This example:

Imports the OpenSRF::Utils::Cache module

Creates a cache object

Creates a unique cache key based on the OpenSRF method name and request input value

Checks to see if the cache key already exists; if so, it immediately returns that value

If the cache key does not exist, the code sleeps for 10 seconds to simulate a call to a slow remote Web service, or an intensive process

Sets a value for the lifetime of the cache key in seconds

When the code has retrieved its value, then it can create the cache entry, with the cache key, value to be stored ("here"), and the timeout value in seconds to ensure that we do not return stale data on subsequent calls

145.3.8. Initializing the service and its children: child labour

When an OpenSRF service is started, it looks for a procedure called initialize() to set up any global variables shared by all of the children of the service. The initialize() procedure is typically used to retrieve configuration settings from the opensrf.xml file.

An OpenSRF service spawns one or more children to actually do the work requested by callers of the service. For every child process an OpenSRF service spawns, the child process clones the parent environment and then each child process runs the child_init() process (if any) defined in the OpenSRF service to initialize any child-specific settings.

When the OpenSRF service kills a child process, it invokes the child_exit() procedure (if any) to clean up any resources associated with the child process. Similarly, when the OpenSRF service is stopped, it calls the DESTROY() procedure to clean up any remaining resources.

145.3.9. Retrieving configuration settings

The settings for OpenSRF services are maintained in the opensrf.xml XML configuration file. The structure of the XML document consists of a root element <opensrf> containing two child elements:

<default> contains an <apps> element describing all OpenSRF services running on this system — see Section 145.3.1, “Registering a service with the OpenSRF configuration files” --, as well as any other arbitrary XML descriptions required for global configuration purposes. For example, Evergreen uses this section for email notification and inter-library patron privacy settings.

<hosts> contains one element per host that participates in this OpenSRF system. Each host element must include an <activeapps> element that lists all of the services to start on this host when the system starts up. Each host element can optionally override any of the default settings.

OpenSRF includes a service named opensrf.settings to provide distributed cached access to the configuration settings with a simple API:

opensrf.settings.default_config.get: accepts zero arguments and returns the complete set of default settings as a JSON document

opensrf.settings.host_config.get: accepts one argument (hostname) and returns the complete set of settings, as customized for that hostname, as a JSON document

opensrf.settings.xpath.get: accepts one argument (an XPath expression) and returns the portion of the configuration file that matches the expression as a JSON document

For example, to determine whether an Evergreen system uses the opt-in support for sharing patron information between libraries, you could either invoke the opensrf.settings.default_config.get method and parse the JSON document to determine the value, or invoke the opensrf.settings.xpath.get method with the XPath /opensrf/default/share/user/opt_in argument to retrieve the value directly.

In practice, OpenSRF includes convenience libraries in all of its client language bindings to simplify access to configuration values. C offers osrfConfig.c, Perl offers OpenSRF::Utils::SettingsClient, Java offers org.opensrf.util.SettingsClient, and Python offers osrf.set. These libraries locally cache the configuration file to avoid network roundtrips for every request and enable the developer to request specific values without having to manually construct XPath expressions.

145.4. Getting under the covers with OpenSRF

Now that you have seen that it truly is easy to create an OpenSRF service, we can take a look at what is going on under the covers to make all of this work for you.

145.4.1. Get on the messaging bus - safely

One of the core innovations of OpenSRF was to use the Extensible Messaging and Presence Protocol (XMPP, more colloquially known as Jabber) as the messaging bus that ties OpenSRF services together across servers. XMPP is an "XML protocol for near-real-time messaging, presence, and request-response services" (http://www.ietf.org/rfc/rfc3920.txt) that OpenSRF relies on to handle most of the complexity of networked communications. OpenSRF achieves a measure of security for its services through the use of public and private XMPP domains; all OpenSRF services automatically register themselves with the private XMPP domain, but only those services that register themselves with the public XMPP domain can be invoked from public OpenSRF clients.

In a minimal OpenSRF deployment, two XMPP users named "router" connect to the XMPP server, with one connected to the private XMPP domain and one connected to the public XMPP domain. Similarly, two XMPP users named "opensrf" connect to the XMPP server via the private and public XMPP domains. When an OpenSRF service is started, it uses the "opensrf" XMPP user to advertise its availability with the corresponding router on that XMPP domain; the XMPP server automatically assigns a Jabber ID (JID) based on the client hostname to each service’s listener process and each connected drone process waiting to carry out requests. When an OpenSRF router receives a request to invoke a method on a given service, it connects the requester to the next available listener in the list of registered listeners for that service.

The opensrf and router user names, passwords, and domain names, along with the list of services that should be public, are contained in the opensrf_core.xml configuration file.

145.4.2. Message body format

OpenSRF was an early adopter of JavaScript Object Notation (JSON). While XMPP is an XML protocol, the Evergreen developers recognized that the compactness of the JSON format offered a significant reduction in bandwidth for the volume of messages that would be generated in an application of that size. In addition, the ability of languages such as JavaScript, Perl, and Python to generate native objects with minimal parsing offered an attractive advantage over invoking an XML parser for every message. Instead, the body of the XMPP message is a simple JSON structure. For a simple request, like the following example that simply reverses a string, it looks like a significant overhead: but we get the advantages of locale support and tracing the request from the requester through the listener and responder (drone).

A request for opensrf.simple-text.reverse("foobar"): 

<message from='router@private.localhost/opensrf.simple-text'
  to='opensrf@private.localhost/opensrf.simple-text_listener_at_localhost_6275'
  router_from='opensrf@private.localhost/_karmic_126678.3719_6288'
  router_to='' router_class='' router_command='' osrf_xid=''
>
  <thread>1266781414.366573.12667814146288</thread>
  <body>
[
  {"__c":"osrfMessage","__p":
    {"threadTrace":"1","locale":"en-US","type":"REQUEST","payload":
      {"__c":"osrfMethod","__p":
        {"method":"opensrf.simple-text.reverse","params":["foobar"]}
      }
    }
  }
]
  </body>
</message>

A response from opensrf.simple-text.reverse("foobar"). 

<message from='opensrf@private.localhost/opensrf.simple-text_drone_at_localhost_6285'
  to='opensrf@private.localhost/_karmic_126678.3719_6288'
  router_command='' router_class='' osrf_xid=''
>
  <thread>1266781414.366573.12667814146288</thread>
  <body>
[
  {"__c":"osrfMessage","__p":
    {"threadTrace":"1","payload":
      {"__c":"osrfResult","__p":
        {"status":"OK","content":"raboof","statusCode":200}
      } ,"type":"RESULT","locale":"en-US"}
  },
  {"__c":"osrfMessage","__p":
    {"threadTrace":"1","payload":
      {"__c":"osrfConnectStatus","__p":
        {"status":"Request Complete","statusCode":205}
      },"type":"STATUS","locale":"en-US"}
  }
]
  </body>
</message>

The content of the <body> element of the OpenSRF request and result should look familiar; they match the structure of the OpenSRF over HTTP examples that we previously dissected.

145.4.3. Registering OpenSRF methods in depth

Let’s explore the call to __PACKAGE__->register_method(); most of the elements of the hash are optional, and for the sake of brevity we omitted them in the previous example. As we have seen in the results of the introspection call, a verbose registration method call is recommended to better enable the internal documentation. So, for the sake of completeness here, is the set of elements that you should pass to __PACKAGE__->register_method():

method: the name of the procedure in this module that is being registered as an OpenSRF method

api_name: the invocable name of the OpenSRF method; by convention, the OpenSRF service name is used as the prefix

api_level: (optional) can be used for versioning the methods to allow the use of a deprecated API, but in practical use is always 1

argc: (optional) the minimal number of arguments that the method expects

stream: (optional) if this argument is set to any value, then the method supports returning multiple values from a single call to subsequent requests, and OpenSRF automatically creates a corresponding method with ".atomic" appended to its name that returns the complete set of results in a single request; streaming methods are useful if you are returning hundreds of records and want to act on the results as they return

signature: (optional) a hash describing the method’s purpose, arguments, and return value

desc: a description of the method’s purpose

params: an array of hashes, each of which describes one of the method arguments

name: the name of the argument

desc: a description of the argument’s purpose

type: the data type of the argument: for example, string, integer, boolean, number, array, or hash

return: a hash describing the return value of the method

desc: a description of the return value

type: the data type of the return value: for example, string, integer, boolean, number, array, or hash

145.5. Evergreen-specific OpenSRF services

Evergreen is currently the primary showcase for the use of OpenSRF as an application architecture. Evergreen 2.6.0 includes the following set of OpenSRF services:

open-ils.acq Supports tasks for managing the acquisitions process

open-ils.actor: Supports common tasks for working with user accounts and libraries.

open-ils.auth: Supports authentication of Evergreen users.

open-ils.auth_proxy: Support using external services such as LDAP directories to authenticate Evergreen users

open-ils.cat: Supports common cataloging tasks, such as creating, modifying, and merging bibliographic and authority records.

open-ils.circ: Supports circulation tasks such as checking out items and calculating due dates.

open-ils.collections: Supports tasks to assist collections services for contacting users with outstanding fines above a certain threshold.

open-ils.cstore: Supports unrestricted access to Evergreen fieldmapper objects. This is a private service.

open-ils.fielder

open-ils.justintime: Support tasks for determining if an action/trigger event is still valid

open-ils.pcrud: Supports access to Evergreen fieldmapper objects, restricted by staff user permissions. This is a private service. objects.

open-ils.permacrud: Supports access to Evergreen fieldmapper objects, restricted by staff user permissions. This is a private service.

open-ils.reporter: Supports the creation and scheduling of reports.

open-ils.reporter-store: Supports access to Evergreen fieldmapper objects for the reporting service. This is a private service.

open-ils.resolver Support tasks for integrating with an OpenURL resolver.

open-ils.search: Supports searching across bibliographic records, authority records, serial records, Z39.50 sources, and ZIP codes.

open-ils.serial: Support tasks for serials management

open-ils.storage: A deprecated method of providing access to Evergreen fieldmapper objects. Implemented in Perl, this service has largely been replaced by the much faster C-based open-ils.cstore service.

open-ils.supercat: Supports transforms of MARC records into other formats, such as MODS, as well as providing Atom and RSS feeds and SRU access.

open-ils.trigger: Supports event-based triggers for actions such as overdue and holds available notification emails.

open-ils.url_verify: Support tasks for validating URLs

open-ils.vandelay: Supports the import and export of batches of bibliographic and authority records.

opensrf.settings: Supports communicating opensrf.xml settings to other services.

Of some interest is that the open-ils.reporter-store and open-ils.cstore services have identical implementations. Surfacing them as separate services enables a deployer of Evergreen to ensure that the reporting service does not interfere with the performance-critical open-ils.cstore service. One can also direct the reporting service to a read-only database replica to, again, avoid interference with open-ils.cstore which must write to the master database.

There are only a few significant services that are not built on OpenSRF, such as the SIP and Z39.50 servers. These services implement different protocols and build on existing daemon architectures (Simple2ZOOM for Z39.50), but still rely on the other OpenSRF services to provide access to the Evergreen data. The non-OpenSRF services are reasonably self-contained and can be deployed on different servers to deliver the same sort of deployment flexibility as OpenSRF services, but have the disadvantage of not being integrated into the same configuration and control infrastructure as the OpenSRF services.

145.6. Evergreen after one year: reflections on OpenSRF

Project Conifer has been live on Evergreen for just over a year now, and as one of the primary technologists I have had to work closely with the OpenSRF infrastructure during that time. As such, I am in a position to identify some of the strengths and weaknesses of OpenSRF based on our experiences.

145.6.1. Strengths of OpenSRF

As a service infrastructure, OpenSRF has been remarkably reliable. We initially deployed Evergreen on an unreleased version of both OpenSRF and Evergreen due to our requirements for some functionality that had not been delivered in a stable release at that point in time, and despite this risky move we suffered very little unplanned downtime in the opening months. On July 27, 2009 we moved to a newer (but still unreleased) version of the OpenSRF and Evergreen code, and began formally tracking our downtime. Since then, we have achieved more than 99.9% availability - including scheduled downtime for maintenance. This compares quite favourably to the maximum of 75% availability that we were capable of achieving on our previous library system due to the nightly downtime that was required for our backup process. The OpenSRF "maximum request" configuration parameter for each service that kills off drone processes after they have served a given number of requests provides a nice failsafe for processes that might otherwise suffer from a memory leak or hung process. It also helps that when we need to apply an update to a Perl service that is running on multiple servers, we can apply the updated code, then restart the service on one server at a time to avoid any downtime.

As promised by the OpenSRF infrastructure, we have also been able to tune our cluster of servers to provide better performance. For example, we were able to change the number of maximum concurrent processes for our database services when we noticed that we seeing a performance bottleneck with database access. Making a configuration change go live simply requires you to restart the opensrf.setting service to pick up the configuration change, then restart the affected service on each of your servers. We were also able to turn off some of the less-used OpenSRF services, such as open-ils.collections, on one of our servers to devote more resources on that server to the more frequently used services and other performance-critical processes such as Apache.

The support for logging and caching that is built into OpenSRF has been particularly helpful with the development of a custom service for SFX holdings integration into our catalogue. Once I understood how OpenSRF works, most of the effort required to build that SFX integration service was spent on figuring out how to properly invoke the SFX API to display human-readable holdings. Adding a new OpenSRF service and registering several new methods for the service was relatively easy. The support for directing log messages to syslog in OpenSRF has also been a boon for both development and debugging when problems arise in a cluster of five servers; we direct all of our log messages to a single server where we can inspect the complete set of messages for the entire cluster in context, rather than trying to piece them together across servers.

145.6.2. Weaknesses

The primary weakness of OpenSRF is the lack of either formal or informal documentation for OpenSRF. There are many frequently asked questions on the Evergreen mailing lists and IRC channel that indicate that some of the people running Evergreen or trying to run Evergreen have not been able to find documentation to help them understand, even at a high level, how the OpenSRF Router and services work with XMPP and the Apache Web server to provide a working Evergreen system. Also, over the past few years several developers have indicated an interest in developing Ruby and PHP bindings for OpenSRF, but the efforts so far have resulted in no working code. Without a formal specification, clearly annotated examples, and unit tests for the major OpenSRF communication use cases that could be ported to the new language as a base set of expectations for a working binding, the hurdles for a developer new to OpenSRF are significant. As a result, Evergreen integration efforts with popular frameworks like Drupal, Blacklight, and VuFind result in the best practical option for a developer with limited time — database-level integration — which has the unfortunate side effect of being much more likely to break after an upgrade.

In conjunction with the lack of documentation that makes it hard to get started with the framework, a disincentive for new developers to contribute to OpenSRF itself is the lack of integrated unit tests. For a developer to contribute a significant, non-obvious patch to OpenSRF, they need to manually run through various (undocumented, again) use cases to try and ensure that the patch introduced no unanticipated side effects. The same problems hold for Evergreen itself, although the Constrictor stress-testing framework offers a way of performing some automated system testing and performance testing.

These weaknesses could be relatively easily overcome with the effort through contributions from people with the right skill sets. This article arguably offers a small set of clear examples at both the networking and application layer of OpenSRF. A technical writer who understands OpenSRF could contribute a formal specification to the project. With a formal specification at their disposal, a quality assurance expert could create an automated test harness and a basic set of unit tests that could be incrementally extended to provide more coverage over time. If one or more continual integration environments are set up to track the various OpenSRF branches of interest, then the OpenSRF community would have immediate feedback on build quality. Once a unit testing framework is in place, more developers might be willing to develop and contribute patches as they could sanity check their own code without an intense effort before exposing it to their peers.

145.7. Summary

In this article, I attempted to provide both a high-level and detailed overview of how OpenSRF works, how to build and deploy new OpenSRF services, how to make requests to OpenSRF method from OpenSRF clients or over HTTP, and why you should consider it a possible infrastructure for building your next high-performance system that requires the capability to scale out. In addition, I surveyed the Evergreen services built on OpenSRF and reflected on the strengths and weaknesses of the platform based on the experiences of Project Conifer after a year in production, with some thoughts about areas where the right application of skills could make a significant difference to the Evergreen and OpenSRF projects.

145.8. Appendix: Python client

Following is a Python client that makes the same OpenSRF calls as the Perl client:

#!/usr/bin/env python
"""OpenSRF client example in Python"""
import osrf.system
import osrf.ses

def osrf_substring(session, text, sub):
    """substring: Accepts a string and a number as input, returns a string"""
    request = session.request('opensrf.simple-text.substring', text, sub)

    # Retrieve the response from the method
    # The timeout parameter is optional
    response = request.recv(timeout=2)

    request.cleanup()
    # The results are accessible via content()
    return response.content()

def osrf_split(session, text, delim):
    """split: Accepts two strings as input, returns an array of strings"""
    request = session.request('opensrf.simple-text.split', text, delim)
    response = request.recv()
    request.cleanup()
    return response.content()

def osrf_statistics(session, strings):
    """statistics: Accepts an array of strings as input, returns a hash"""
    request = session.request('opensrf.simple-text.statistics', strings)
    response = request.recv()
    request.cleanup()
    return response.content()

if __name__ == "__main__":
    file = '/openils/conf/opensrf_core.xml'

    # Pull connection settings from <config><opensrf> section of opensrf_core.xml
    osrf.system.System.connect(config_file=file, config_context='config.opensrf')

    # Set up a connection to the opensrf.settings service
    session = osrf.ses.ClientSession('opensrf.simple-text')

    result = osrf_substring(session, "foobar", 3)
    print(result)
    print

    result = osrf_split(session, "This is a test", " ")
    print("Received %d elements: [" % len(result)),
    print(', '.join(result)), ']'

    many_strings = (
        "First I think I'll have breakfast",
        "Then I think that lunch would be nice",
        "And then seventy desserts to finish off the day"
    )
    result = osrf_statistics(session, many_strings)
    print("Length: %d" % result["length"])
    print("Word count: %d" % result["word_count"])

    # Cleanup connection resources
    session.cleanup()

Python’s dnspython module refuses to read /etc/resolv.conf, so to access hostnames that are not served up via DNS, such as the extremely common case of localhost, you may need to install a package like dnsmasq to act as a local DNS server for those hostnames.

Chapter 146. Updating translations using Launchpad

This document describes how to update the translations in an Evergreen branch by pulling them from Launchpad, as well as update the files to be translated in Launchpad by updating the POT files in the Evergreen master branch.

146.1. Prerequisites

You must install all of the Python prerequisites required for building translations, per http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-admin:customizations:i18n

polib

translate-toolkit

levenshtein

setuptools

simplejson

lxml

146.2. Updating the translations

Check out the latest translations from Launchpad by branching the Bazaar repository:

bzr branch lp:~denials/evergreen/translation-export

This creates a directory called "translation-export".

Ensure you have an updated Evergreen release branch.

Run the build/i18n/scripts/update_pofiles script to copy the translations into the right place and avoid any updates that are purely metadata (dates generated, etc).

Commit the lot! And backport to whatever release branches need the updates.

Build updated POT files:

cd build/i18n
make newpot

This will extract all of the strings from the latest version of the files in Evergreen.

(This part needs automation): Then, via the magic of git diff and git add, go through all of the changed files and determine which ones actually have string changes. Recommended approach is to re-run git diff after each git add.

Commit the updated POT files and backport to the pertinent release branches.

Part XV. Getting Data from Evergreen

Chapter 147. Introduction

You may be interested in re-using data from your Evergreen installation in another application. This part describes several methods to get the data you need.

Chapter 148. Using Supercat

148.1. Introduction

You can use SuperCat to get data about ISBNs, metarecords, bibliographic records, and authority records.

Throughout this section, replace <hostname> with the domain or subdomain of your Evergreen installation to try these examples on your own system.

148.2. ISBNs

Given one ISBN, Evergreen can return a list of related records and ISBNs, including alternate editions and translations. To use the Supercat oISBN tool, use http or https to access the following URL.

http://<hostname>/opac/extras/oisbn/<ISBN_to_query>

For example, the URL http://gapines.org/opac/extras/oisbn/0439136350 returns the following list of catalog record IDs and ISBNs:

<?xml version='1.0' encoding='UTF-8' ?>
<idlist metarecord='436139'>
  <isbn record='5652044'>9780606323475</isbn>
  <isbn record='5767568'>9780780673809</isbn>
  <isbn record='1350528'>9780807286029</isbn>
  <isbn record='5708164'>9780780669642</isbn>
  <isbn record='2372013'>043965548X</isbn>
  <isbn record='5804511'>8498386969</isbn>
  <isbn record='4132282'>9780786222742</isbn>
  <isbn record='1530458'>9788478885190</isbn>
  <isbn record='2003291'>0736650962</isbn>
  <isbn record='1993002'>8478885196</isbn>
  <isbn record='1187595'>9780439554923</isbn>
  <isbn record='4591175'>8478885196</isbn>
  <isbn record='5676282'>0807282324</isbn>
  <isbn record='2363352'>8478885196</isbn>
  <isbn record='2315122'>1480614998</isbn>
  <isbn record='2304130'>8478886559</isbn>
  <isbn record='2012565'>9780613371063</isbn>
  <isbn record='5763645'>9782070528189</isbn>
  <isbn record='2383286'>0786222743</isbn>
  <isbn record='2489670'>9780329232696</isbn>
  <isbn record='1681685'>9780807282311</isbn>
  <isbn record='2160095'>0807286028</isbn>
  <isbn record='2219885'>9789500421157</isbn>
  <isbn record='1934218'>9780613359580</isbn>
  <isbn record='5682871'>9781594130021</isbn>
  <isbn record='1281164'>0807283150</isbn>
  <isbn record='1666656'>0747542155</isbn>
  <isbn record='4717734'>8478886559</isbn>
</idlist>

148.3. Records

148.3.1. Record formats

First, determine which format you’d like to receive data in. To see the available formats for bibliographic records, visit

http://<hostname>/opac/extras/supercat/formats/record

Similarly, authority record formats can be found at http://libcat.linnbenton.edu/opac/extras/supercat/formats/authority and metarecord formats can be found at http://libcat.linnbenton.edu/opac/extras/supercat/formats/metarecord

For example, http://gapines.org/opac/extras/supercat/formats/authority shows that the Georgia Pines catalog can return authority records in the formats opac, marc21, marc21-full, and marc21-uris. Supercat also includes the MIME type of each format, and sometimes also refers to the documentation for a particular format.

<?xml version='1.0' encoding='UTF-8' ?>
<formats>
  <format>
    <name>opac</name>
    <type>text/html</type>
  </format>
  <format>
    <name>marc21</name>
    <type>application/xml</type>
    <docs>http://www.loc.gov/marc/</docs>
  </format>
  <format>
    <name>marc21-full</name>
    <type>application/xml</type>
    <docs>http://www.loc.gov/marc/</docs>
  </format>
  <format>
    <name>marc21-uris</name>
    <type>application/xml</type>
    <docs>http://www.loc.gov/marc/</docs>
  </format>
</formats>

atom-full is currently the only format that includes holdings and availability data for a given bibliographic record.

148.3.2. Retrieve records

You can retrieve records using URLs in the following format:

http://<hostname>/opac/extras/supercat/retrieve/<format>/<record-type>/<record-ID>

For example, http://gapines.org/opac/extras/supercat/retrieve/mods/record/33333 returns the following record.

<?xml version="1.0"?>
<modsCollection xmlns="http://www.loc.gov/mods/" xmlns:mods="http://www.loc.gov/mods/" version="3.0">
  <mods xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mods="http://www.loc.gov/mods/" xsi:schemaLocation="http://www.loc.gov/mods/ http://www.loc.gov/standards/mods/mods.xsd">
    <titleInfo>
      <title>Words and pictures /</title>
    </titleInfo>
    <name type="personal">
      <namePart xmlns:xlink="http://www.w3.org/TR/xlink">Dodd, Siobhan</namePart>
      <role>
        <text>creator</text>
      </role>
    </name>
    <typeOfResource xmlns:xlink="http://www.w3.org/TR/xlink">text</typeOfResource>
    <originInfo xmlns:xlink="http://www.w3.org/TR/xlink">
      <place>
        <code authority="marc">mau</code>
      </place>
      <place>
        <text>Cambridge, Mass</text>
      </place>
      <publisher>Candlewick Press</publisher>
      <dateIssued>1992</dateIssued>
      <edition>1st U.S. ed.</edition>
      <issuance>monographic</issuance>
    </originInfo>
    <language authority="iso639-2b">eng</language>
    <physicalDescription>
      <form authority="marcform">print</form>
      <extent>1 v. (unpaged) : col. ill. ; 26 cm.</extent>
    </physicalDescription>
    <abstract>Simple text with picture cues accompany illustrations depicting scenes of everyday life familiar to children, such as getting dressed, attending a party, playing in the park, and taking a bath.</abstract>
    <targetAudience>juvenile</targetAudience>
    <note type="statement of responsibility">Siobhan Dodds.</note>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcshac">
      <topic>Family life</topic>
      <topic>Fiction</topic>
    </subject>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
      <topic>Vocabulary</topic>
      <topic>Juvenile fiction</topic>
    </subject>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
      <topic>Rebuses</topic>
    </subject>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
      <topic>Picture puzzles</topic>
      <topic>Juvenile literature</topic>
    </subject>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
      <topic>Picture books for children</topic>
    </subject>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
      <topic>Picture dictionaries, English</topic>
      <topic>Juvenile literature</topic>
    </subject>
    <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
      <topic>Vocabulary</topic>
      <topic>Juvenile literature</topic>
    </subject>
    <classification authority="lcc">PZ7.D66275 Wo 1992</classification>
    <classification authority="lcc">PN6371.5 .D63 1992x</classification>
    <classification authority="ddc" edition="20">793.73</classification>
    <identifier type="isbn">1564020428 :</identifier>
    <identifier type="isbn">9781564020420</identifier>
    <identifier type="lccn">91071817</identifier>
    <recordInfo xmlns:xlink="http://www.w3.org/TR/xlink">
      <recordContentSource>DLC</recordContentSource>
      <recordCreationDate encoding="marc">920206</recordCreationDate>
      <recordChangeDate encoding="iso8601">20110608231047.0</recordChangeDate>
      <recordIdentifier source="GaAaGPL">33333</recordIdentifier>
    </recordInfo>
  </mods>
</modsCollection>

148.3.3. Recent records

SuperCat can return feeds of recently edited or created authority and bibliographic records:

http://<hostname>/opac/extras/feed/freshmeat/<feed-type>/<record-type>/<import-or-edit>/<limit>/<date>

Note the following features:

The limit records imported or edited following the supplied date will be returned. If you do not supply a date, then the most recent limit records will be returned.

If you do not supply a limit, then up to 10 records will be returned.

feed-type can be one of atom, html, htmlholdings, marcxml, mods, mods3, or rss2.

Example: http://gapines.org/opac/extras/feed/freshmeat/atom/biblio/import/10/2008-01-01

148.3.3.1. Filtering by Org Unit

You can generate a similar list, with the added ability to limit by Org Unit, using the item-age browse axis.

To produce an RSS feed by item date rather than bib date, and to restrict it to a particular system within a consortium:

Example: http://gapines.org/opac/extras/browse/atom/item-age/ARL-BOG/1/10

Note the following:

ARL-BOG should be the short name of the org unit you’re interested in

1 is the page (since you are browsing through pages of results)

10 is the number of results to return per page

Modifying the atom portion of the URL to atom-full will include catalog links in the results:

Example: http://gapines.org/opac/extras/browse/atom-full/item-age/ARL-BOG/1/10

Modifying the atom portion of the URL to html-full will produce an HTML page that is minimally formatted:

Example: http://gapines.org/opac/extras/browse/html-full/item-age/ARL-BOG/1/10

Chapter 149. Using UnAPI

Evergreen’s unAPI support includes access to many record types. For example, the following URL would fetch bib 267 in MODS32 along with holdings, volume, copy, and record attribute information:

https://example.org/opac/extras/unapi?id=tag::U2@bre/267{holdings_xml,acn,acp,mra}&format=mods32

To access the new unAPI features, the unAPI ID should have the following form:

tag::U2@

followed by class name, which may be

bre (bibs)

biblio_record_entry_feed (multiple bibs)

acl (copy locations)

acn (volumes)

acnp (call number prefixes)

acns (call number suffixes)

acp (copies)

acpn (copy notes)

aou (org units)

ascecm (copy stat cat entries)

auri (located URIs)

bmp (monographic parts)

cbs (bib sources)

ccs (copy statuses)

circ (loan checkout and due dates)

holdings_xml (holdings)

mmr (metarecords)

mmr_holdings_xml (metarecords with holdings)

mmr_mra (metarecords with record attributes)

mra (record attributes)

sbsum (serial basic summaries)

sdist (serial distributions)

siss (serial issues)

sisum (serial index summaries)

sitem (serial items)

sssum (serial supplement summaries)

sstr (serial streams)

ssub (serial subscriptions)

sunit (serial units)

followed by /

followed by a record identifier (or in the case of the biblio_record_entry_feed class, multiple IDs separated by commas)

followed, optionally, by limit and offset in square brackets

followed, optionally, by a comma-separated list of "includes" enclosed in curly brackets. The list of includes is the same as the list of classes with the following addition:

bre.extern (information from the non-MARC parts of a bib record)

followed, optionally, by / and org unit; "-" signifies the top of the org unit tree

followed, optionally, by / and org unit depth

followed, optionally, by / and a path. If the path is barcode and the class is acp, the record ID is taken to be a copy barcode rather than a copy ID; for example, in tag::U2@acp/ACQ140{acn,bre,mra}/-/0/barcode, ACQ140 is meant to be a copy barcode.

followed, optionally, by &format= and the format in which the record should be retrieved. If this part is omitted, the list of available formats will be retrieved.

Appendix A. Attributions

Copyright © 2009-2016 Evergreen DIG

Copyright © 2007-2016 Equinox

Copyright © 2007-2016 Dan Scott

Copyright © 2009-2016 BC Libraries Cooperative (SITKA)

Copyright © 2008-2016 King County Library System

Copyright © 2009-2016 Pioneer Library System

Copyright © 2009-2016 PALS

Copyright © 2009-2016 Georgia Public Library Service

Copyright © 2008-2016 Project Conifer

Copyright © 2009-2016 Bibliomation

Copyright © 2008-2016 Evergreen Indiana

Copyright © 2008-2016 SC LENDS

Current DIG Members

Hilary Caws-Elwitt, Susquehanna County Library

Karen Collier, Kent County Public Library

George Duimovich, NRCan Library

Lynn Floyd, Anderson County Library

Sally Fortin, Equinox Software

Wolf Halton, Lyrasis

Jennifer Pringle, SITKA

June Rayner, eiNetwork

Steve Sheppard

Ben Shum, Bibliomation

Roni Shwaish, eiNetwork

Robert Soulliere, Mohawk College

Remington Steed, Calvin College

Tim Spindler, C/W MARS

Jane Sandberg, Linn-Benton Community College

Lindsay Stratton, Pioneer Library System

Yamil Suarez, Berklee College of Music

Jenny Turner, PALS

Appendix B. Licensing

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

Appendix C. Admonitions

Note

warning

caution

tip

Index

A

account preferences, Account Preferences

account summary, Account Summary

accounts, Electronic Data Interchange

acquisitions

claiming, Claiming

currency types, Currency Types

distribution formulas

templates, Distribution Formulas

EDI

accounts, Electronic Data Interchange

messages, EDI Messages

exchange rates, Exchange Rates

funding sources, Funding Sources

funds, Funds

fiscal rollover, Perform fiscal year close-out operation

reports, Fund reporting

tags, Fund Tags

invoices, Invoice menus, Invoices

electronic, Electronic Invoicing

searching for lineitems, Search for line items from an invoice

line item

cancellation, Cancel/Delay reasons

line items, Line Item Features

lineitems

adding, Search for line items from an invoice

searching for, Search for line items from an invoice

MARC federated search, MARC Federated Search

permissions, Acquisitions Settings

purchase order

cancellation, Cancel/Delay reasons

Acquisitions

Library Settings Editor, Settings Overview

action triggers

event definitions

notifications, Notifications / Action Triggers

adding, Search for line items from an invoice

adding data sources, Adding Data Sources to Reporter

address alerts, Address Alert

advanced search

exclude electronic resources, Exclude Electronic Resources

expert search, Expert Search

limit to available, Limit to Available

numeric search, Search Filter Enhancements

search filters, Search Filter

search library, Search Library

sort results, Sort Results

Age Protection, Age hold protection

aggregate filters, Applying Filters

Alerts, Patron Alerts

AND operator, Boolean operators

Apache, Upgrade the Evergreen code

applying filters, Applying Filters

aggregate filters, Applying Filters

base filter, Applying Filters, Using Base Filters

audiobooks, Formats

authentication

LDAP, Authentication Proxy

proxy, Authentication Proxy

author, Basic Search

authors, Facets: Subjects, Authors, and Series

Automated Circulation System, SIP Server

Automated Material Handling, SIP Server

Automated Material Handling (AMH), 17/18 Item Information

availability, Availability

B

Barcode Completion

Lazy Circ, Barcode Completion

barring, Barring a Patron, Barred vs. Blocked

base filter, Applying Filters, Using Base Filters

bib call number, Basic Search

blocking, Barred vs. Blocked

Booking

Library Settings Editor, Settings Overview

books, Formats

boolean, Boolean operators

C

cancellation, Cancel/Delay reasons

Cataloging

Library Settings Editor, Settings Overview

checkout, Receipt Template Editor

choosing reports fields, Choosing Report Fields

Circulation

Library Settings Editor, Settings Overview

circulation

recalls

hold-driven, Hold-driven recalls

claiming, Claiming

cloning, Cloning Shared Templates

Closed Dates, Set closed dates using the Closed Dates Editor

Column Picker, Column Picker

configuration, Workstation Administration

configuration files

oils_sip.xml, Configuring the Server, Adding SIP Users

copy editor

shelving location, Copy Editor: Copy Location Name First

count, Field Transforms

creating, Creating Folders

creating templates, Creating Templates

choosing reports fields, Choosing Report Fields

Credit Card Processing

Library Settings Editor, Settings Overview

currency types, Currency Types

D

Data Types

Library Settings Editor, Data Types

data types, Data Types

database schema, Upgrade the Evergreen database schema, Create a PostgreSQL query, view, or table for your data source

Debian, Upgrade the Evergreen code

details, Details

distribution formulas

templates, Distribution Formulas

E

EDI

accounts, Electronic Data Interchange

messages, EDI Messages

electronic, Electronic Invoicing

event definitions

notifications, Notifications / Action Triggers

Excel, Viewing Report Output

exchange rates, Exchange Rates

exclude electronic resources, Exclude Electronic Resources

expert search, Expert Search

Exporting

Library Settings Editor, Exporting/Importing Library Settings

exporting templates, Exporting Report Templates Using phpPgAdmin

F

facets: subjects

authors, Facets: Subjects, Authors, and Series

field transform, Choosing Report Fields

field transforms, Field Transforms

count, Field Transforms

output type, Field Transforms

raw data, Field Transforms

raw distinct, Field Transforms

fieldmapper, Add a new class to fm_IDL.xml for your data source

Finances

Library Settings Editor, Settings Overview

fiscal rollover, Perform fiscal year close-out operation

fm_IDL.xml, Adding Data Sources to Reporter, Add a new class to fm_IDL.xml for your data source

folders, Folders

creating, Creating Folders

managing, Managing Folders

fonts

zooming, Font and Sound Settings

formats

audiobooks, Formats

books, Formats

music, Formats

video, Formats

funding sources, Funding Sources

funds, Funds, Fund reporting

fiscal rollover, Perform fiscal year close-out operation

reports, Fund reporting

tags, Fund Tags

G

generating, Generating Reports from Templates

Global

Library Settings Editor, Settings Overview

going back, Going back

Graphic User Interface

Library Settings Editor, Settings Overview

GUI

Library Settings Editor, Settings Overview

H

hold-driven, Hold-driven recalls

hold-driven recalls, Hold-driven recalls

Holds, Age hold protection

Age Protection, Age hold protection

Library Settings Editor, Settings Overview

holds, Holds

preferred pickup location, Account Preferences

holds receipt

layout, Print Holds Slip with Landscape Layout

hotkeys, Select Hotkeys

I

Importing

Library Settings Editor, Exporting/Importing Library Settings

includes, General Macros

invoices, Invoice menus, Invoices

electronic, Electronic Invoicing

searching for lineitems, Search for line items from an invoice

items checked out, Items Checked Out

J

journal title, Basic Search

K

keyword, Basic Search

L

layout, Print Holds Slip with Landscape Layout

Lazy Circ, Barcode Completion

LDAP, Authentication Proxy

Library

Library Settings Editor, Settings Overview

library cards

renewing, Renewing Library Cards

replacing, Lost Library Cards

Library Settings Editor, Library Settings Editor, Exporting/Importing Library Settings, Settings Overview, Data Types

limit to available, Limit to Available

line item

cancellation, Cancel/Delay reasons

line items, Line Item Features

lineitems

adding, Search for line items from an invoice

searching for, Search for line items from an invoice

Linux

Debian, Upgrade the Evergreen code

Ubuntu, Upgrade the Evergreen code

logging in, Basic Login,, Logging In

logging out, Logging Out

M

macros, Receipt Template Editor, General Macros

magnetic media, 09/10 Checkin

managing, Managing Folders

MARC federated search, MARC Federated Search

marc2are.pl, Importing Authority Records from Command Line

marc_export, marc_export: Exporting Bibliographic Records into MARC files

messages, EDI Messages, Staff-Generated Messages

music, Formats

my account

account preferences, Account Preferences

account summary, Account Summary

holds, Holds

items checked out, Items Checked Out

logging in, Logging In

password reset, Password Reset

N

NOT operator, Boolean operators

Notes, Patron Notes

notifications, Notifications / Action Triggers

numeric search, Search Filter Enhancements

O

Offline

Library Settings Editor, Settings Overview

oils_sip.xml, Configuring the Server, Adding SIP Users

OPAC, Basic Search

Library Settings Editor, Settings Overview

OR operator, Boolean operators

order of results, Order of Results

output, Viewing Report Output

Excel, Viewing Report Output

spreadsheet, Viewing Report Output

tabular, Viewing Report Output

output type, Field Transforms

P

password reset, Password Reset

passwords, Resetting Patron’s Password

Patron Registration Settings

Library Settings Editor, Settings Overview

patrons

Alerts, Patron Alerts

barring, Barring a Patron, Barred vs. Blocked

blocking, Barred vs. Blocked

messages, Staff-Generated Messages

Notes, Patron Notes

passwords, Resetting Patron’s Password

purchase requests, Placing purchase requests from a patron record

registering, Registering New Patrons

searching for, Searching Patrons

updating, Updating Patron Information

permissions, Acquisitions Settings

pg_loader.pl, Importing Authority Records from Command Line

placing holds, Placing Holds

Populate Address by ZIP Code

ZIP code, Patron Address City/State/County Pre-Populate by ZIP Code

PostgreSQL, Adding Data Sources to Reporter, Create a PostgreSQL query, view, or table for your data source

preferred pickup location, Account Preferences

printers, Configure Printers

Program

Library Settings Editor, Settings Overview

proxy, Authentication Proxy

purchase order

cancellation, Cancel/Delay reasons

purchase requests, Placing purchase requests from a patron record, Managing patron purchase requests

R

raw data, Field Transforms

raw distinct, Field Transforms

recalls

hold-driven, Hold-driven recalls

receipt template editor, Receipt Template Editor

checkout, Receipt Template Editor

holds receipt

layout, Print Holds Slip with Landscape Layout

includes, General Macros

macros, Receipt Template Editor, General Macros

Receipt Templates

Library Settings Editor, Settings Overview

recurring, Running Recurring Reports

registering, Registering New Patrons

registering a workstation, Registering a Workstation

renewing, Renewing Library Cards

replacing, Lost Library Cards

report sources, Add a new class to fm_IDL.xml for your data source

reporter

starting, Starting the Reporter Daemon

starting daemon, Starting and Stopping the Reporter Daemon

stopping daemon, Stopping the Reporter Daemon

reports, Fund reporting

adding data sources, Adding Data Sources to Reporter

applying filters, Applying Filters

aggregate filters, Applying Filters

base filter, Applying Filters, Using Base Filters

cloning, Cloning Shared Templates

creating templates, Creating Templates

choosing reports fields, Choosing Report Fields

data types, Data Types

exporting templates, Exporting Report Templates Using phpPgAdmin

field transform, Choosing Report Fields

field transforms, Field Transforms

count, Field Transforms

output type, Field Transforms

raw data, Field Transforms

raw distinct, Field Transforms

folders, Folders

creating, Creating Folders

managing, Managing Folders

funds, Fund reporting

generating, Generating Reports from Templates

output, Viewing Report Output

Excel, Viewing Report Output

spreadsheet, Viewing Report Output

tabular, Viewing Report Output

recurring, Running Recurring Reports

starting server application, Starting and Stopping the Reporter Daemon

stopping server application, Stopping the Reporter Daemon

S

search

AND operator, Boolean operators

author, Basic Search

bib call number, Basic Search

boolean, Boolean operators

journal title, Basic Search

keyword, Basic Search

NOT operator, Boolean operators

OR operator, Boolean operators

order of results, Order of Results

series, Basic Search

stemming, Stemming

stop words, Search Tips

subject, Basic Search

title, Basic Search

truncation, Search Tips

URL, Search URL

search box, Basic Search

search filters, Search Filter

search library, Search Library

search results, Search Results

availability, Availability

details, Details

facets: subjects

authors, Facets: Subjects, Authors, and Series

going back, Going back

placing holds, Placing Holds

viewing a record, Viewing a record

searching for, Search for line items from an invoice, Searching Patrons

searching for lineitems, Search for line items from an invoice

Security

Library Settings Editor, Settings Overview

Self Check

Library Settings Editor, Settings Overview

SelfCheck, SIP Server, 01 Block Patron

series, Basic Search

shelving location, Copy Editor: Copy Location Name First

SIP, Running the server, Syslog-NG, More Testing

SIP Communication, SIP Communication

SIP Server

SIP Communication, SIP Communication

SMS Settings

Library Settings Editor, Settings Overview

sort results, Sort Results

sounds, Font and Sound Settings

spreadsheet, Viewing Report Output

SQL, Adding Data Sources to Reporter

SSL certificate, Basic Login,

staff client

configuration, Workstation Administration

fonts

zooming, Font and Sound Settings

hotkeys, Select Hotkeys

logging in, Basic Login,

logging out, Logging Out

printers, Configure Printers

registering a workstation, Registering a Workstation

sounds, Font and Sound Settings

starting, Starting the Reporter Daemon

starting daemon, Starting and Stopping the Reporter Daemon

starting server application, Starting and Stopping the Reporter Daemon

stemming, Stemming

stop words, Search Tips

stopping daemon, Stopping the Reporter Daemon

stopping server application, Stopping the Reporter Daemon

subject, Basic Search

syslog, Syslog

syslog-NG, Syslog-NG

T

tabular, Viewing Report Output

tags, Fund Tags

templates, Distribution Formulas

Text Messaging

Library Settings Editor, Settings Overview

title, Basic Search

truncation, Search Tips

U

Ubuntu, Upgrade the Evergreen code

updating, Updating Patron Information

URL, Search URL

V

Vandelay

Library Settings Editor, Settings Overview

video, Formats

viewing a record, Viewing a record

W

workstation

configuration, Workstation Administration

Z

ZIP code, Patron Address City/State/County Pre-Populate by ZIP Code

zips.txt

Populate Address by ZIP Code

ZIP code, Patron Address City/State/County Pre-Populate by ZIP Code

zooming, Font and Sound Settings