This commit renames all AsciiDoc files to have the ".adoc" extension.
Also, this commit updates all "include::" references in the root.adoc
file.
RATIONALE: Some editing tools, including GitHub, will auto-generate an
HTML preview for AsciiDoc files if they have the filename extension
".adoc" or ".asciidoc". The community agreed to this change in 2015 (see
http://markmail.org/thread/z2s7xnxavpjzirwx).
NOTE: The docs build script will need to change the reference from
"root.txt" to "root.adoc".
Signed-off-by: Remington Steed <rjs7@calvin.edu>
--- /dev/null
+QueryParser Changes
+
+Quick notes for doc writers.
+
+New columns:
+
+config.metabib_class: Note: This gets a new config interface to expose this and other information. It intentionally has no buttons for adding or removing entries.
+ a_weight
+ b_weight
+ c_weight
+ d_weight
+
+These are the FTS weights used for ranking for the four FTS weight classes. By default "A" is the exact match indexing and "C" is the stemmed version. They default to the PostgreSQL defaults that are used when otherwise unspecified.
+
+
+New tables:
+
+config.ts_config_list: Note: No editing interface exists for this, intentionally. It should be added to when DB-level FTS configs are added.
+ id - Actual DB level text search config name
+ name - Human readable description
+
+This lists the valid FTS configs for use with the following two tables, with more human friendly names.
+
+config.metabib_class_ts_map: Editable from the Server Admin menu
+ id - Primary key for editor benefit
+ field_class - Reference to config.metabib_class
+ ts_config - Which Text Search config to use
+ active - Is this config active. If false will not be used for searching or indexing.
+ index_weight - The FTS index weight to use for this FTS config. Should be A, B, C, or D, defaults to C.
+ index_lang - If set what language the record should be set to in order for this FTS config to be used for indexing
+ search_lang - If set what preferred language search should be using in order for this FTS config to be used for searching
+ always - If true use this config even when searching a specific field (author|personal, for example) even if that field has config as well
+
+This maps broad search classes and text search configs. Multiple can exist for a given search class. Setting index_lang or search_lang to 'NONE' will effectively disable the config for that purpose as they check against a three character field like 'eng' or 'fre'.
+
+config.metabib_field_ts_map: Editable from the Server Admin menu
+ id - Primary key for editor benefit
+ metabib_field - Reference to config.metabib_field
+ ts_config - Which Text Search config to use
+ active - Is this config active. If false will not be used for searching or indexing.
+ index_weight - The FTS index weight to use for this FTS config. Should be A, B, C, or D, defaults to C.
+ index_lang - If set what language the record should be set to in order for this FTS config to be used for indexing
+ search_lang - If set what preferred language search should be using in order for this FTS config to be used for searching
+
+This maps individual indexes and text search configs. Multiple can exist for a given index. Setting index_lang or search_lang to 'NONE' will effectively disable the config for that purpose as they check against a three character field like 'eng' or 'fre'. Note that anything from the broader configs will be used if none exist for the specified field and the "always" ones from the broader configs will be used even if field specific ones do exist.
+
+New non-configuration tables exist for combined search indexes, but they are, IMO, more implementation details than things to be documented for end users.
+++ /dev/null
-QueryParser Changes
-
-Quick notes for doc writers.
-
-New columns:
-
-config.metabib_class: Note: This gets a new config interface to expose this and other information. It intentionally has no buttons for adding or removing entries.
- a_weight
- b_weight
- c_weight
- d_weight
-
-These are the FTS weights used for ranking for the four FTS weight classes. By default "A" is the exact match indexing and "C" is the stemmed version. They default to the PostgreSQL defaults that are used when otherwise unspecified.
-
-
-New tables:
-
-config.ts_config_list: Note: No editing interface exists for this, intentionally. It should be added to when DB-level FTS configs are added.
- id - Actual DB level text search config name
- name - Human readable description
-
-This lists the valid FTS configs for use with the following two tables, with more human friendly names.
-
-config.metabib_class_ts_map: Editable from the Server Admin menu
- id - Primary key for editor benefit
- field_class - Reference to config.metabib_class
- ts_config - Which Text Search config to use
- active - Is this config active. If false will not be used for searching or indexing.
- index_weight - The FTS index weight to use for this FTS config. Should be A, B, C, or D, defaults to C.
- index_lang - If set what language the record should be set to in order for this FTS config to be used for indexing
- search_lang - If set what preferred language search should be using in order for this FTS config to be used for searching
- always - If true use this config even when searching a specific field (author|personal, for example) even if that field has config as well
-
-This maps broad search classes and text search configs. Multiple can exist for a given search class. Setting index_lang or search_lang to 'NONE' will effectively disable the config for that purpose as they check against a three character field like 'eng' or 'fre'.
-
-config.metabib_field_ts_map: Editable from the Server Admin menu
- id - Primary key for editor benefit
- metabib_field - Reference to config.metabib_field
- ts_config - Which Text Search config to use
- active - Is this config active. If false will not be used for searching or indexing.
- index_weight - The FTS index weight to use for this FTS config. Should be A, B, C, or D, defaults to C.
- index_lang - If set what language the record should be set to in order for this FTS config to be used for indexing
- search_lang - If set what preferred language search should be using in order for this FTS config to be used for searching
-
-This maps individual indexes and text search configs. Multiple can exist for a given index. Setting index_lang or search_lang to 'NONE' will effectively disable the config for that purpose as they check against a three character field like 'eng' or 'fre'. Note that anything from the broader configs will be used if none exist for the specified field and the "always" ones from the broader configs will be used even if field specific ones do exist.
-
-New non-configuration tables exist for combined search indexes, but they are, IMO, more implementation details than things to be documented for end users.
--- /dev/null
+Release notes
+=============
+:toc:
+:numbered:
+
+Upgrade notes
+-------------
+
+Z39.50 Server Definitions
+~~~~~~~~~~~~~~~~~~~~~~~
+Z39.50 server target definitions have been removed from the sample
+`opensrf.xml.example` file. To migrate existing settings from your
+`opensrf.xml` configuration file to the database, perform the
+following steps:
+
+ 1. First, set up your custom Z39.50 sources in the database. For
+ each entry in `z3950/services`, map the following XML paths to the
+ corresponding `config.z3950_source` table column as follows:
++
+ ** `z3950/services/<entry>` = name
+ ** `//<entry>/name` = label
+ ** `//<entry>/host` = host
+ ** `//<entry>/port` = port
+ ** `//<entry>/db` = db
+ ** `//<entry>/record_format` = record_format
+ ** `//<entry>/transmission_format` = transmission_format
++
+ 2. Then, for each attribute defined in the `<attrs>` element for
+ a given service, map the following XML paths to the corresponding
+ `config.z3950_attr` table column as follows:
++
+ ** `z3950/services/<entry>` = source
+ ** `//<entry>/attrs/<attr>` = name
+ ** `//<entry>/attrs/<attr>/code` = code
+ ** `//<entry>/attrs/<attr>/format` = format
++
+ 3. After adding the new Z39.50 sources and corresponding attributes,
+ you will need to log out of the staff client and log back into the
+ staff client to retrieve the new entry values. If a given Z39.50
+ server does not work for a given attribute, pay attention to the
+ `truncation` column for the attribute.
+
+
+New features
+------------
+
+Administration
+~~~~~~~~~~~~
+
+Custom Org Unit Trees
+^^^^^^^^^^^^^^^^^^^^^
+Evergreen enables you to create an organizational tree that describes the
+systems, branches, or other units that comprise your organization. By default,
+the org unit tree that appears to patrons in the OPAC is identical to the one
+that appears to users of the staff client. Using this feature, you can condense
+or re-order the organizational tree into a simpler structure for patrons using
+the OPAC while maintaining the complex organizational tree that is available to
+users of the staff client.
+
+As a further enhancement, you can hide a parental org unit yet still make its
+child org units visible in the OPAC. In previous versions of Evergreen, child
+org units inherited the visibility setting of their parents.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Fine Accrual on Closed Dates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+By default, fines accrue only on dates that the library is open. This feature
+enables you to charge patrons fines on dates the library is closed. Fines
+accrue during scheduled closings as well as during normal weekly closed dates.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Target Copies for Holds at Closed Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+By default, when a patron places a hold on a title, the hold targeter will
+search for copies to fill the hold only at circulating libraries that are open.
+Copies at closed libraries are not targeted to fill holds. When turned on, this
+feature enables Evergreen to target copies that have closed circulating
+libraries to fill holds. Two new org unit settings control this feature.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+OPAC
+~~~~
+
+Template Toolkit OPAC (_TPAC_)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The basic catalog has been replaced by the Template Toolkit OPAC (_TPAC_).
+Compared to the traditional catalog (_JSPAC_), TPAC uses far fewer network
+calls for each page, resulting in faster loading pages. TPAC is built on the
+http://template-toolkit.org[Template Toolkit] language to enable simple but
+powerful customization, and supports integrated `gettext`-based translation
+for strings--including placeholders and quantities--for better
+internationalization support.
+
+The next feature release of Evergreen will make TPAC the primary catalog
+and deprecate the use of the JSPAC.
+
+Auto Suggest in Catalog Search
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The
+http://docs.evergreen-ils.org/2.2/_auto_suggest_in_catalog_search_2.html[auto
+suggest feature] suggests the completion of search terms as the user enters his
+query. By default, the user will see ten suggestions although this
+number 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.
+
+Copy Location Groups
+^^^^^^^^^^^^^^^^^^^^
+This feature allows staff to create and name sets of copy locations to use as
+a search filter in the catalog. OPAC-visible groups will display within the
+library selector in the template toolkit OPAC. When a user selects a group
+and performs a search, the set of results will be limited to records that have
+copies in one of the copy locations within the group. Groups can live at any
+level of the library hierarchy and may include copy locations from any parent
+org unit or child org unit.
+
+For advanced users, this change includes a new Query Parser filter called
+location_groups().
+
+My Lists
+^^^^^^^^
+The My Lists feature replaces the bookbag feature that was available in
+versions prior to 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.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+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.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+New Patron Preferences
+^^^^^^^^^^^^^^^^^^^^^^^
+Users will now have the ability to designate the following preferences in the
+Template Toolkit catalog (_TPAC_):
+
+* A preferred search location. Unlike the default search library in JSPAC, this
+ setting will also control which copies display first in search results and
+ record detail screens.
+* A preferred pickup location.
+* The ability to keep a history of checked out items.
+* The ability to keep a history of holds.
+
+Credit Card Payment via Public Catalog
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Patrons can now use credit cards to pay fines and bills in *My Account* of the
+TPAC.
+
+Record Detail Print and E-mail Actions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Implements Print and Email actions as links below the *Add to List* link
+in the TPAC record detail page.
+
+Identify Previously-Checked-Out Items in Search Results
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When a user is logged into the TPAC and performs a search, this feature
+indicates in the results set when any of the result items were ever checked
+out by the logged-in user. Items will only be tagged when the related org
+setting is enabled and the user has opted in to circ history tracking.
+
+Patron Management
+~~~~~~~~~~~~~~~~~
+
+Patron Statistical Category Enhancements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following enhancements have been added to patron statistical categories:
+
+ * categories can be marked as 'required' (must be filled out when a patron is
+ registered)
+ * categories can be marked to allow or disallow user-created entries
+ * an entry for a given category and org unit can be marked as the default
+ entry. It will be automatically selected in the new patron registration
+ screen.
+
+User Settings Available from Patron Editor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Staff can now access and update user settings, like notification preferences
+and default pickup library, in the patron editor.
+
+Mark Patron E-mail or Phone as Invalid
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Staff can mark a patron's email address or phone number as invalid in the
+patron editor. The system will clear the email (or phone) field from
+`actor.usr`, and [both optionally, per OU setting]:
+
+ . create a corresponding standing penalty against the user, for staff to
+ notice next time they bring up said patron in the staff client;
+ . create a patron note. Related penalties (but not notes) will be cleared
+ whenever that patron's email address or phone number is updated again.
+
+Address Alert in Patron Registration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Support for comparing user addresses to alert addresses. When an address is
+found, the address in question is styled (the header row turns red) and the
+configured alert message is shown along the top-right, where other warnings
+appear.
+
+Circulation
+~~~~~~~~~~~
+
+Telephony Improvements
+^^^^^^^^^^^^^^^^^^^^^^
+Enhancements to notifications by telephony, including:
+
+* A feature that allows an Evergreen system to roll over failed notifications
+ into new ones with a different notification method.
+* Holiday awareness. System administrators can, via `cron`, schedule the
+ `set_pbx_holidays` script on an Evergreen system to periodically update
+ the PBX's table of holidays, based on a given org unit's closed date ranges.
+* Smart retry. In certain situations, if you put too many callfiles into
+ Asterisk's spool at once, Asterisk will try to make too many calls at
+ once, and all such calls just fail. That is what the allocator is meant to
+ prevent. Smart retry is about moving calls that have been tried once, and will
+ be retried again later due to resulting in a busy signal or other problem, out
+ of the spool to make room for other calls that could be made in the meantime.
+
+Circulation Limit Groups & Limit Sets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The new *Circulation Limit Groups* interface found in the *Server
+administration* menu can be thought of as _tags_ the system places on
+circulations so that it can find them later. The *Limit Sets* interface found
+in the *Local administration* menu defines rules for limiting the number of
+active circulations a patron may have based on Circulation Modifiers and Limit
+Groups. These new features support the following options:
+
+* Setting circ limits for circulations that have no circ modifiers. This is
+ useful for systems with circulation rules based on something other than
+ circulation modifiers (for example, *MARC type*) or for grouping items
+ that may have different circulation modifiers so that, for example, you
+ can count every video, regardless of circulation modifiers.
+* The ability to set limits for a single library's items, regardless of
+ the checkout library.
+
+New Checkin Modifiers
+^^^^^^^^^^^^^^^^^^^^^
+The following modifiers have been added to the check-in interface:
+
+* *Clear Shelf-Expired Holds*. When checking in something on the hold shelf,
+ run a 'Clear Shelf Process' for the specific copy ID at that library to
+ auto-clear any Shelf-Expired holds.
+* *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-cataloged 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 '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. Possible use cases include Automated
+ Materials Handling (AMH) checkins, in which items may be sitting in a bin for a
+ while before landing on the holds shelf, and checkins done on closed days.
+
+Copy Location Alerts
+^^^^^^^^^^^^^^^^^^^^
+This enhancement adds a new 'checkin_alert' column to copy locations. If true
+(defaults to false), then a routing alert is generated at reshelving time for
+the location. This is intended for special locations, such as 'Display', that
+may require special handling, or that temporarily contain items that are not
+normally in that location.
+
+Age Hold Protection Based on a Copy's Active Date
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Adds a 'Sets copy active' column to the 'Copy Statuses' interface to identify
+ statuses that indicate a copy is active and ready for checkout. The first
+ time a copy is set to one of these statuses, the system adds an 'active date'
+ for the copy, which can be used for reporting.
+* Provides a new library setting for age hold protection to be based on the
+ copy's active date instead of its create date.
+
+Option to Place Holds on Age Protected Items
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Allow choice of placing hold despite age protection. This alters the backend to
+watch when so much as one copy failed only due to age protection. In JSPAC, an
+alternate confirm message is shown. In TPAC, the failure message is changed
+and override is always allowed for the hold in question.
+
+Force and Cataloging Recall Holds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creates two new types of copy-level holds, *Force* and *Cataloging Recall*,
+that cut in front of all other holds and ignore hold rules. For cataloging
+recall holds, the copy's status changes to 'cataloging' when it reaches its
+destination.
+
+Archiving Statistical Categories and Circulation-Time Copy Locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Circulation-time copy locations are now archived with circulations (aged or active).
+
+Using the *Statistical Categories Editor*, staff can also designate statistical
+categories (patron and copy) to archive with circulations.
+
+Browse Holds Shelf Interface Displays Canceled Holds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Holds that are canceled after they are placed on the holds shelf will continue
+to display in this interface and will also display in the 'shelf-expired holds'
+view.
+
+Acquisitions
+~~~~~~~~~~~~
+
+Vandelay Integration into Acquisitions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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. The Vandelay interface enables you to create specific match points
+between incoming MARC records and existing catalog records. Combining these
+two features enables you to track on order MARC records through the
+Acquisitions interface and to utilize the record matching mechanisms available
+in Vandelay when importing acquisitions records.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+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.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Lineitem and Copy Actions Accessible from More Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Users can now access lineitem actions (for example, receive, unreceive, update
+barcodes, new invoice) from the acquisitions lineitem search results and
+selection list interfaces. Also available on these interfaces is a link to copy
+details where users can take receive actions (receive, unreceive, cancel) on
+individual copies.
+
+Improved Displays for Provider and Fund Administration Pages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This enhancement provides improved support for viewing the provider and fund
+administration pages. It also allows staff to use filters to find providers and
+funds.
+
+Cataloging
+~~~~~~~~~~
+
+Authority Control Sets
+^^^^^^^^^^^^^^^^^^^^^^
+The tags and subfields that display in authority records in Evergreen are
+defined by control sets. The Library of Congress control set is the default
+control set in all versions of Evergreen. However, in Evergreen release 2.2,
+you can create customized control sets for authority records, and you can
+define thesauri and authority fields for these control sets.
+
+Patrons and staff can browse authorities in the JSPAC. The following fields are
+browsable by default: author, series, subject, title, and topic. You can add
+custom browse axes in addition to these default fields.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Batch Importing MARC Records
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The MARC Batch Import interface features improved matching of records and
+managing of your import queue. In version 2.2, you can specify match points
+between incoming and existing records to better detect matching records and
+prevent record duplication. You can also create quality controls to ensure that
+incoming matching records are superior in quality to existing catalog records.
+
+You also have new options for managing your queue. You can apply filters to
+your queue, and you can generate a list of import errors. You can also print
+your queue, email your queue, or export your queue as a CSV file.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Hide Fields in Copy Editor
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can customize the *Copy Editor* for staff by hiding fields in the *Copy
+Editor* that are not relevant for workflows at particular org units. Descendant
+org units inherit the settings of their parents.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Prevent Bibliographic Records from Having Attached Copies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To enable libraries to designate specific sets of records as only for use as
+electronic resources, it is possible to configure a bibliographic source such
+that physical copies or MFHD records may not be attached to records from that
+source. The `config.bib_source` table now includes a new Boolean column,
+`can_have_copies`, that controls this behavior. If `can_have_copies` for a
+given bibliographic source is `TRUE`, then the staff client will prevent a
+cataloger from adding volumes or MFHD records to records belonging to that
+source.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Overlay Existing Catalog Record via Z39.50 Import
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can replace an existing catalog record with a record obtained through a
+Z39.50 search. No new permissions or administrative settings are needed to use
+this feature.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Restrict Z39.50 Sources by Permission Group
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+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.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Switch Copy Location Name and Library Short Name in Copy Editor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+By default, the copy editor shows the library shortname ('BR1' or 'CONS')
+followed by the copy location name ('Stacks', 'Reference'). A new workstation
+setting, under *Admin -> Workstation Administration -> Copy Editor: Copy
+Location Name First*, enables staff to change the display so that the copy
+location name is displayed first, followed by the library shortname. This may
+be particularly useful for libraries that have defined one set of copy
+locations at the consortial level and want to enable quick keyboard navigation
+to copy locations by typing just the first letters of the copy location.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+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. Currently, this feature only tracks user authentication.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Authentication Proxy
+~~~~~~~~~~~~~~~~~~
+To support integration of Evergreen with organizational authentication systems,
+and to reduce the proliferation of user names and passwords, Evergreen offers
+a new 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 against any authentication system,
+the user account must first be defined within the Evergreen system, and
+authentication will be based on the user name as it exists in Evergreen.
+
+A sample authentication mechanism for LDAP is provided in
+`Open-ILS::Application::AuthProxy::LDAP_AUTH`, and corresponding sample
+attributes can be found in `opensrf.xml.example`.
+
+Auditor Tables
+~~~~~~~~~~~~~~
+This enhancement adds user and workstation IDs to the auditor tables. It also
+adds/changes auditor functions to allow for setting, getting, and clearing
+auditor information, as well as adding a couple of utility functions for
+updating auditors after changes to their origin columns.
+
+Reports
+~~~~~~~
+
+New Views for Reporting Sources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To support the creation of collection development reports, the following
+reporting sources have been added:
+
+ * 'Last Circulation or Creation Date' is a source that offers the copy ID,
+ the last circulation date or creation date, and the last circulation date
+ * 'Hold/Copy Ratio per Bib and Pickup Library' is a source that calculates
+ the number of holds per copy per bibliographic record, with granularity
+ by pickup library.
+
+
+Staff Client Navigation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+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 add buttons that will enable quick access to a variety of features.
+You can create toolbars for specific org unit(s), workstation(s), or login(s).
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Double Clicking in the Staff Client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can search for a patron's record, and double click on a result to access
+that record. You can double click on an item in the *Holdings Maintenance*
+screen to access copy information. The item is linked to the *Volume/Copy
+Creator*, if you turned it on in the staff client's org unit settings. If you
+did not turn on the *Volume/Copy Creator*, then the item links to the *Item
+Attributes*.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Recent Staff Searches
+^^^^^^^^^^^^^^^^^^^^^
+You can view your recent searches as you perform them in the staff client. By
+default, staff can view their recent searches, although the number is
+configurable. This feature is only available through the staff client; it is
+not available to patrons in the OPAC.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Return to Search Results from MARC Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This feature enables you to return to your title search results directly from
+any view of the MARC record, including the *OPAC View*, *MARC Record*, *MARC
+Edit*, and *Holdings Maintenance* views. You can use this feature to page
+through records in the *MARC Record View* or *Edit* interfaces. You do not have
+to return to the *OPAC View* to access title results.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Sorting Columns
+^^^^^^^^^^^^^^^
+This feature enables you to sort by multiple display columns so that you can
+find easily the information that you need on a screen. You can sort display
+columns on any screen that is built on a grid, such as the *Check In* screen or
+the *On Shelf Pull List*.
+
+You can also sort the columns on the following *Administration* screens:
+
+ * Circulation Policies
+ * Hold Policies
+ * Circulation Limit Sets
+ * Barcode Completion
+ * Acquisitions User Request List
+ * Vandelay Import Errors
+
+You can sort items in an ascending or descending order, and you can prioritize
+the order in which columns will sort.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Tab Button
+^^^^^^^^^^
+This feature enables you to add a new tab to the Evergreen staff client by
+clicking the *+* sign adjacent to the tab that you currently have opened. As in
+previous versions, you can also add new tabs by clicking *File -> New Tab*, or
+use the hotkey, *Ctrl+T*.
+
+Documentation for this feature is available in the Book of Evergreen at
+http://docs.evergreen-ils.org/2.2/
+
+Close All Tabs Shortcut
+^^^^^^^^^^^^^^^^^^^^^^^
+You can use *CTRL+Click* on the close tab (*X*) button to close all tabs.
+
+Independent Column Configurations and Receipt Templates for Different Hold List Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Previously, all hold list interfaces shared the same column picker settings and
+receipt templates. This enhancement creates independent settings for the
+following interfaces:
+
+* Actions for this Record -> View Holds
+* Patron Display -> Holds
+* Circulation -> Browse Hold Shelf
+* Circulation -> Pull List for Hold Requests
+
+Line Number Columns
+^^^^^^^^^^^^^^^^^^^
+List displays in the staff client now have a non-sortable line number column
+which displays the ordinal position of each row in the list. The first row in
+such a list will always have a value of 1 in the ordinal column, no matter how
+the list is sorted. There is no special handling for paged interfaces; the
+first row on any given page still gets an ordinal value of 1.
+
+Auto-Login
+^^^^^^^^^^
+Supports auto-login in the staff client by adding three new command line
+parameters:
+
+* `-ILSuser`: user name to log in with
+* `-ILSpassword`: password to use
+* `-ILShost`: hostname to use
+
+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.
\ No newline at end of file
+++ /dev/null
-Release notes
-=============
-:toc:
-:numbered:
-
-Upgrade notes
--------------
-
-Z39.50 Server Definitions
-~~~~~~~~~~~~~~~~~~~~~~~
-Z39.50 server target definitions have been removed from the sample
-`opensrf.xml.example` file. To migrate existing settings from your
-`opensrf.xml` configuration file to the database, perform the
-following steps:
-
- 1. First, set up your custom Z39.50 sources in the database. For
- each entry in `z3950/services`, map the following XML paths to the
- corresponding `config.z3950_source` table column as follows:
-+
- ** `z3950/services/<entry>` = name
- ** `//<entry>/name` = label
- ** `//<entry>/host` = host
- ** `//<entry>/port` = port
- ** `//<entry>/db` = db
- ** `//<entry>/record_format` = record_format
- ** `//<entry>/transmission_format` = transmission_format
-+
- 2. Then, for each attribute defined in the `<attrs>` element for
- a given service, map the following XML paths to the corresponding
- `config.z3950_attr` table column as follows:
-+
- ** `z3950/services/<entry>` = source
- ** `//<entry>/attrs/<attr>` = name
- ** `//<entry>/attrs/<attr>/code` = code
- ** `//<entry>/attrs/<attr>/format` = format
-+
- 3. After adding the new Z39.50 sources and corresponding attributes,
- you will need to log out of the staff client and log back into the
- staff client to retrieve the new entry values. If a given Z39.50
- server does not work for a given attribute, pay attention to the
- `truncation` column for the attribute.
-
-
-New features
-------------
-
-Administration
-~~~~~~~~~~~~
-
-Custom Org Unit Trees
-^^^^^^^^^^^^^^^^^^^^^
-Evergreen enables you to create an organizational tree that describes the
-systems, branches, or other units that comprise your organization. By default,
-the org unit tree that appears to patrons in the OPAC is identical to the one
-that appears to users of the staff client. Using this feature, you can condense
-or re-order the organizational tree into a simpler structure for patrons using
-the OPAC while maintaining the complex organizational tree that is available to
-users of the staff client.
-
-As a further enhancement, you can hide a parental org unit yet still make its
-child org units visible in the OPAC. In previous versions of Evergreen, child
-org units inherited the visibility setting of their parents.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Fine Accrual on Closed Dates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default, fines accrue only on dates that the library is open. This feature
-enables you to charge patrons fines on dates the library is closed. Fines
-accrue during scheduled closings as well as during normal weekly closed dates.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Target Copies for Holds at Closed Libraries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default, when a patron places a hold on a title, the hold targeter will
-search for copies to fill the hold only at circulating libraries that are open.
-Copies at closed libraries are not targeted to fill holds. When turned on, this
-feature enables Evergreen to target copies that have closed circulating
-libraries to fill holds. Two new org unit settings control this feature.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-OPAC
-~~~~
-
-Template Toolkit OPAC (_TPAC_)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The basic catalog has been replaced by the Template Toolkit OPAC (_TPAC_).
-Compared to the traditional catalog (_JSPAC_), TPAC uses far fewer network
-calls for each page, resulting in faster loading pages. TPAC is built on the
-http://template-toolkit.org[Template Toolkit] language to enable simple but
-powerful customization, and supports integrated `gettext`-based translation
-for strings--including placeholders and quantities--for better
-internationalization support.
-
-The next feature release of Evergreen will make TPAC the primary catalog
-and deprecate the use of the JSPAC.
-
-Auto Suggest in Catalog Search
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The
-http://docs.evergreen-ils.org/2.2/_auto_suggest_in_catalog_search_2.html[auto
-suggest feature] suggests the completion of search terms as the user enters his
-query. By default, the user will see ten suggestions although this
-number 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.
-
-Copy Location Groups
-^^^^^^^^^^^^^^^^^^^^
-This feature allows staff to create and name sets of copy locations to use as
-a search filter in the catalog. OPAC-visible groups will display within the
-library selector in the template toolkit OPAC. When a user selects a group
-and performs a search, the set of results will be limited to records that have
-copies in one of the copy locations within the group. Groups can live at any
-level of the library hierarchy and may include copy locations from any parent
-org unit or child org unit.
-
-For advanced users, this change includes a new Query Parser filter called
-location_groups().
-
-My Lists
-^^^^^^^^
-The My Lists feature replaces the bookbag feature that was available in
-versions prior to 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.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-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.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-New Patron Preferences
-^^^^^^^^^^^^^^^^^^^^^^^
-Users will now have the ability to designate the following preferences in the
-Template Toolkit catalog (_TPAC_):
-
-* A preferred search location. Unlike the default search library in JSPAC, this
- setting will also control which copies display first in search results and
- record detail screens.
-* A preferred pickup location.
-* The ability to keep a history of checked out items.
-* The ability to keep a history of holds.
-
-Credit Card Payment via Public Catalog
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Patrons can now use credit cards to pay fines and bills in *My Account* of the
-TPAC.
-
-Record Detail Print and E-mail Actions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Implements Print and Email actions as links below the *Add to List* link
-in the TPAC record detail page.
-
-Identify Previously-Checked-Out Items in Search Results
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When a user is logged into the TPAC and performs a search, this feature
-indicates in the results set when any of the result items were ever checked
-out by the logged-in user. Items will only be tagged when the related org
-setting is enabled and the user has opted in to circ history tracking.
-
-Patron Management
-~~~~~~~~~~~~~~~~~
-
-Patron Statistical Category Enhancements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The following enhancements have been added to patron statistical categories:
-
- * categories can be marked as 'required' (must be filled out when a patron is
- registered)
- * categories can be marked to allow or disallow user-created entries
- * an entry for a given category and org unit can be marked as the default
- entry. It will be automatically selected in the new patron registration
- screen.
-
-User Settings Available from Patron Editor
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Staff can now access and update user settings, like notification preferences
-and default pickup library, in the patron editor.
-
-Mark Patron E-mail or Phone as Invalid
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Staff can mark a patron's email address or phone number as invalid in the
-patron editor. The system will clear the email (or phone) field from
-`actor.usr`, and [both optionally, per OU setting]:
-
- . create a corresponding standing penalty against the user, for staff to
- notice next time they bring up said patron in the staff client;
- . create a patron note. Related penalties (but not notes) will be cleared
- whenever that patron's email address or phone number is updated again.
-
-Address Alert in Patron Registration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Support for comparing user addresses to alert addresses. When an address is
-found, the address in question is styled (the header row turns red) and the
-configured alert message is shown along the top-right, where other warnings
-appear.
-
-Circulation
-~~~~~~~~~~~
-
-Telephony Improvements
-^^^^^^^^^^^^^^^^^^^^^^
-Enhancements to notifications by telephony, including:
-
-* A feature that allows an Evergreen system to roll over failed notifications
- into new ones with a different notification method.
-* Holiday awareness. System administrators can, via `cron`, schedule the
- `set_pbx_holidays` script on an Evergreen system to periodically update
- the PBX's table of holidays, based on a given org unit's closed date ranges.
-* Smart retry. In certain situations, if you put too many callfiles into
- Asterisk's spool at once, Asterisk will try to make too many calls at
- once, and all such calls just fail. That is what the allocator is meant to
- prevent. Smart retry is about moving calls that have been tried once, and will
- be retried again later due to resulting in a busy signal or other problem, out
- of the spool to make room for other calls that could be made in the meantime.
-
-Circulation Limit Groups & Limit Sets
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The new *Circulation Limit Groups* interface found in the *Server
-administration* menu can be thought of as _tags_ the system places on
-circulations so that it can find them later. The *Limit Sets* interface found
-in the *Local administration* menu defines rules for limiting the number of
-active circulations a patron may have based on Circulation Modifiers and Limit
-Groups. These new features support the following options:
-
-* Setting circ limits for circulations that have no circ modifiers. This is
- useful for systems with circulation rules based on something other than
- circulation modifiers (for example, *MARC type*) or for grouping items
- that may have different circulation modifiers so that, for example, you
- can count every video, regardless of circulation modifiers.
-* The ability to set limits for a single library's items, regardless of
- the checkout library.
-
-New Checkin Modifiers
-^^^^^^^^^^^^^^^^^^^^^
-The following modifiers have been added to the check-in interface:
-
-* *Clear Shelf-Expired Holds*. When checking in something on the hold shelf,
- run a 'Clear Shelf Process' for the specific copy ID at that library to
- auto-clear any Shelf-Expired holds.
-* *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-cataloged 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 '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. Possible use cases include Automated
- Materials Handling (AMH) checkins, in which items may be sitting in a bin for a
- while before landing on the holds shelf, and checkins done on closed days.
-
-Copy Location Alerts
-^^^^^^^^^^^^^^^^^^^^
-This enhancement adds a new 'checkin_alert' column to copy locations. If true
-(defaults to false), then a routing alert is generated at reshelving time for
-the location. This is intended for special locations, such as 'Display', that
-may require special handling, or that temporarily contain items that are not
-normally in that location.
-
-Age Hold Protection Based on a Copy's Active Date
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* Adds a 'Sets copy active' column to the 'Copy Statuses' interface to identify
- statuses that indicate a copy is active and ready for checkout. The first
- time a copy is set to one of these statuses, the system adds an 'active date'
- for the copy, which can be used for reporting.
-* Provides a new library setting for age hold protection to be based on the
- copy's active date instead of its create date.
-
-Option to Place Holds on Age Protected Items
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Allow choice of placing hold despite age protection. This alters the backend to
-watch when so much as one copy failed only due to age protection. In JSPAC, an
-alternate confirm message is shown. In TPAC, the failure message is changed
-and override is always allowed for the hold in question.
-
-Force and Cataloging Recall Holds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Creates two new types of copy-level holds, *Force* and *Cataloging Recall*,
-that cut in front of all other holds and ignore hold rules. For cataloging
-recall holds, the copy's status changes to 'cataloging' when it reaches its
-destination.
-
-Archiving Statistical Categories and Circulation-Time Copy Locations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Circulation-time copy locations are now archived with circulations (aged or active).
-
-Using the *Statistical Categories Editor*, staff can also designate statistical
-categories (patron and copy) to archive with circulations.
-
-Browse Holds Shelf Interface Displays Canceled Holds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Holds that are canceled after they are placed on the holds shelf will continue
-to display in this interface and will also display in the 'shelf-expired holds'
-view.
-
-Acquisitions
-~~~~~~~~~~~~
-
-Vandelay Integration into Acquisitions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-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. The Vandelay interface enables you to create specific match points
-between incoming MARC records and existing catalog records. Combining these
-two features enables you to track on order MARC records through the
-Acquisitions interface and to utilize the record matching mechanisms available
-in Vandelay when importing acquisitions records.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-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.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Lineitem and Copy Actions Accessible from More Interfaces
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Users can now access lineitem actions (for example, receive, unreceive, update
-barcodes, new invoice) from the acquisitions lineitem search results and
-selection list interfaces. Also available on these interfaces is a link to copy
-details where users can take receive actions (receive, unreceive, cancel) on
-individual copies.
-
-Improved Displays for Provider and Fund Administration Pages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This enhancement provides improved support for viewing the provider and fund
-administration pages. It also allows staff to use filters to find providers and
-funds.
-
-Cataloging
-~~~~~~~~~~
-
-Authority Control Sets
-^^^^^^^^^^^^^^^^^^^^^^
-The tags and subfields that display in authority records in Evergreen are
-defined by control sets. The Library of Congress control set is the default
-control set in all versions of Evergreen. However, in Evergreen release 2.2,
-you can create customized control sets for authority records, and you can
-define thesauri and authority fields for these control sets.
-
-Patrons and staff can browse authorities in the JSPAC. The following fields are
-browsable by default: author, series, subject, title, and topic. You can add
-custom browse axes in addition to these default fields.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Batch Importing MARC Records
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The MARC Batch Import interface features improved matching of records and
-managing of your import queue. In version 2.2, you can specify match points
-between incoming and existing records to better detect matching records and
-prevent record duplication. You can also create quality controls to ensure that
-incoming matching records are superior in quality to existing catalog records.
-
-You also have new options for managing your queue. You can apply filters to
-your queue, and you can generate a list of import errors. You can also print
-your queue, email your queue, or export your queue as a CSV file.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Hide Fields in Copy Editor
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can customize the *Copy Editor* for staff by hiding fields in the *Copy
-Editor* that are not relevant for workflows at particular org units. Descendant
-org units inherit the settings of their parents.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Prevent Bibliographic Records from Having Attached Copies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To enable libraries to designate specific sets of records as only for use as
-electronic resources, it is possible to configure a bibliographic source such
-that physical copies or MFHD records may not be attached to records from that
-source. The `config.bib_source` table now includes a new Boolean column,
-`can_have_copies`, that controls this behavior. If `can_have_copies` for a
-given bibliographic source is `TRUE`, then the staff client will prevent a
-cataloger from adding volumes or MFHD records to records belonging to that
-source.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Overlay Existing Catalog Record via Z39.50 Import
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can replace an existing catalog record with a record obtained through a
-Z39.50 search. No new permissions or administrative settings are needed to use
-this feature.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Restrict Z39.50 Sources by Permission Group
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-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.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Switch Copy Location Name and Library Short Name in Copy Editor
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default, the copy editor shows the library shortname ('BR1' or 'CONS')
-followed by the copy location name ('Stacks', 'Reference'). A new workstation
-setting, under *Admin -> Workstation Administration -> Copy Editor: Copy
-Location Name First*, enables staff to change the display so that the copy
-location name is displayed first, followed by the library shortname. This may
-be particularly useful for libraries that have defined one set of copy
-locations at the consortial level and want to enable quick keyboard navigation
-to copy locations by typing just the first letters of the copy location.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-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. Currently, this feature only tracks user authentication.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Authentication Proxy
-~~~~~~~~~~~~~~~~~~
-To support integration of Evergreen with organizational authentication systems,
-and to reduce the proliferation of user names and passwords, Evergreen offers
-a new 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 against any authentication system,
-the user account must first be defined within the Evergreen system, and
-authentication will be based on the user name as it exists in Evergreen.
-
-A sample authentication mechanism for LDAP is provided in
-`Open-ILS::Application::AuthProxy::LDAP_AUTH`, and corresponding sample
-attributes can be found in `opensrf.xml.example`.
-
-Auditor Tables
-~~~~~~~~~~~~~~
-This enhancement adds user and workstation IDs to the auditor tables. It also
-adds/changes auditor functions to allow for setting, getting, and clearing
-auditor information, as well as adding a couple of utility functions for
-updating auditors after changes to their origin columns.
-
-Reports
-~~~~~~~
-
-New Views for Reporting Sources
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To support the creation of collection development reports, the following
-reporting sources have been added:
-
- * 'Last Circulation or Creation Date' is a source that offers the copy ID,
- the last circulation date or creation date, and the last circulation date
- * 'Hold/Copy Ratio per Bib and Pickup Library' is a source that calculates
- the number of holds per copy per bibliographic record, with granularity
- by pickup library.
-
-
-Staff Client Navigation
-~~~~~~~~~~~~~~~~~~~~~~~
-
-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 add buttons that will enable quick access to a variety of features.
-You can create toolbars for specific org unit(s), workstation(s), or login(s).
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Double Clicking in the Staff Client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can search for a patron's record, and double click on a result to access
-that record. You can double click on an item in the *Holdings Maintenance*
-screen to access copy information. The item is linked to the *Volume/Copy
-Creator*, if you turned it on in the staff client's org unit settings. If you
-did not turn on the *Volume/Copy Creator*, then the item links to the *Item
-Attributes*.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Recent Staff Searches
-^^^^^^^^^^^^^^^^^^^^^
-You can view your recent searches as you perform them in the staff client. By
-default, staff can view their recent searches, although the number is
-configurable. This feature is only available through the staff client; it is
-not available to patrons in the OPAC.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Return to Search Results from MARC Record
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This feature enables you to return to your title search results directly from
-any view of the MARC record, including the *OPAC View*, *MARC Record*, *MARC
-Edit*, and *Holdings Maintenance* views. You can use this feature to page
-through records in the *MARC Record View* or *Edit* interfaces. You do not have
-to return to the *OPAC View* to access title results.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Sorting Columns
-^^^^^^^^^^^^^^^
-This feature enables you to sort by multiple display columns so that you can
-find easily the information that you need on a screen. You can sort display
-columns on any screen that is built on a grid, such as the *Check In* screen or
-the *On Shelf Pull List*.
-
-You can also sort the columns on the following *Administration* screens:
-
- * Circulation Policies
- * Hold Policies
- * Circulation Limit Sets
- * Barcode Completion
- * Acquisitions User Request List
- * Vandelay Import Errors
-
-You can sort items in an ascending or descending order, and you can prioritize
-the order in which columns will sort.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Tab Button
-^^^^^^^^^^
-This feature enables you to add a new tab to the Evergreen staff client by
-clicking the *+* sign adjacent to the tab that you currently have opened. As in
-previous versions, you can also add new tabs by clicking *File -> New Tab*, or
-use the hotkey, *Ctrl+T*.
-
-Documentation for this feature is available in the Book of Evergreen at
-http://docs.evergreen-ils.org/2.2/
-
-Close All Tabs Shortcut
-^^^^^^^^^^^^^^^^^^^^^^^
-You can use *CTRL+Click* on the close tab (*X*) button to close all tabs.
-
-Independent Column Configurations and Receipt Templates for Different Hold List Interfaces
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Previously, all hold list interfaces shared the same column picker settings and
-receipt templates. This enhancement creates independent settings for the
-following interfaces:
-
-* Actions for this Record -> View Holds
-* Patron Display -> Holds
-* Circulation -> Browse Hold Shelf
-* Circulation -> Pull List for Hold Requests
-
-Line Number Columns
-^^^^^^^^^^^^^^^^^^^
-List displays in the staff client now have a non-sortable line number column
-which displays the ordinal position of each row in the list. The first row in
-such a list will always have a value of 1 in the ordinal column, no matter how
-the list is sorted. There is no special handling for paged interfaces; the
-first row on any given page still gets an ordinal value of 1.
-
-Auto-Login
-^^^^^^^^^^
-Supports auto-login in the staff client by adding three new command line
-parameters:
-
-* `-ILSuser`: user name to log in with
-* `-ILSpassword`: password to use
-* `-ILShost`: hostname to use
-
-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.
\ No newline at end of file
--- /dev/null
+Release Notes for Evergreen 2.2.1
+=================================
+
+This release contains many bugfixes improving on Evergreen 2.2.0.
+Significant changes since 2.2.0 are mentioned below, roughly grouped by area
+affected. For more information on a given change, see the
+http://open-ils.org/downloads/ChangeLog-2.2.0-2.2.1[technical changelog].
+
+All releases starting with this one are going to be much larger than they
+used to be now that the Evergreen documentation is stored in the same
+repository as the source code. Cheers to Robert Soulliere and to so many
+more contributors from our Documentation Interest Group.
+
+We also have some new folks contributing code, as well as continuing
+contributions from all the old folks (har). Thanks all!
+
+Changes
+-------
+ * ACQ: Vendor Invoice Won't Save
+ * ACQ: Cache propagated funds in fund rollover action
+ * ACQ: Add constraint to PO state value
+ * Documentation: Fix typo in upgrade instructions
+ * Documentation: remove those darn Windows carriage returns
+ * Documentation: Migrate reports documentation from 2.1
+ * Documentation: Format text to limit line length to 80 characters
+ * Documentation: Fix various issues causing errors during processing
+ * Documentation: Add Patron Bills section to Patron Management chapter
+ * Documentation: Add Circulation, Patron management Chapter
+ * Documentation: Add Group Serials Issues Chapter
+ * Documentation: Update EG upgrade instructions to reflect 2.2.0 release
+ * Documentation: Remove antiquated 1.6 directory from docs folder
+ * Documentation: Improve Fedora prereqs and instructions
+ * Documentation: Bump OpenSRF prerequisite to 2.1 for Evergreen 2.2+
+ * Documentation: link README to server install docs
+ * Documentation: Merge the Evergreen docs into the code repository
+ * Documentation: Fix typo in upgrade instructions
+ * Documentation: Add line breaks in authorities chapter to fix
+ * Documentation: Wording improvement for 2.2 release notes
+ * JSPAC: Point to TPAC from <noscript> section
+ * TPAC: Decode translated strings into UTF8
+ * TPAC: Implement a locale picker
+ * TPAC: Allow user to change activation options for suspended holds
+ * TPAC: Fix recognition of logged-in users via HTTP
+ * TPAC: repair editions statement display
+ * TPAC: Set autofocus appropriately for different contexts
+ * TPAC: Use % font size + bold to highlight login failure
+ * TPAC: CSS change for login failure message
+ * TPAC: Physical description, now with spaces
+ * TPAC: Fix glitch returning from viewing ready-for-pickup to all holds
+ * TPAC: Disable caching for auth-required pages
+ * TPAC: Fix titles/tabs in Account Preferences subpages
+ * TPAC: Handle multiple matches for an XPath expression
+ * TPAC: Add paging to My Lists
+ * TPAC: Add record detail navigation to page bottom
+ * TPAC: Search wrapper spacing
+ * Staff client: increase default width for the XUL list line number column
+ * Staff client: Patron name border color for Notes
+ * Staff client: Add component to force external browser use
+ * Staff client: Allow opening of links in default browser
+ * Staff client: Move Prefix field ahead of Names in patron editor
+ * Staff client: Show in Catalog not working in bills interface
+ * Repair PCrudFilter localeStrings variable collisions
+ * Repaired typo in example rsyslog config file
+ * Fix version numbers in 2.1 -> 2.2 upgrade script
+ * Avoid problem with 2.1 -> 2.2 upgrade script issuing error about thesauri
+ * 2.2 upgrade missing vandelay.authority_match.quality column
+ * Teach the autosuggest web service to cache suggestions where appropriate
+ * Add new columns to CDBI table definitions
+ * Switch to a PLPERLU maintain_901() trigger function
+ * Add evergreen.get_locale_name() function to base schema
+ * Squelch uninitialized var warning from hold_copy_targeter
+ * Silence undef string concatenation warning in AutoSuggest
+++ /dev/null
-Release Notes for Evergreen 2.2.1
-=================================
-
-This release contains many bugfixes improving on Evergreen 2.2.0.
-Significant changes since 2.2.0 are mentioned below, roughly grouped by area
-affected. For more information on a given change, see the
-http://open-ils.org/downloads/ChangeLog-2.2.0-2.2.1[technical changelog].
-
-All releases starting with this one are going to be much larger than they
-used to be now that the Evergreen documentation is stored in the same
-repository as the source code. Cheers to Robert Soulliere and to so many
-more contributors from our Documentation Interest Group.
-
-We also have some new folks contributing code, as well as continuing
-contributions from all the old folks (har). Thanks all!
-
-Changes
--------
- * ACQ: Vendor Invoice Won't Save
- * ACQ: Cache propagated funds in fund rollover action
- * ACQ: Add constraint to PO state value
- * Documentation: Fix typo in upgrade instructions
- * Documentation: remove those darn Windows carriage returns
- * Documentation: Migrate reports documentation from 2.1
- * Documentation: Format text to limit line length to 80 characters
- * Documentation: Fix various issues causing errors during processing
- * Documentation: Add Patron Bills section to Patron Management chapter
- * Documentation: Add Circulation, Patron management Chapter
- * Documentation: Add Group Serials Issues Chapter
- * Documentation: Update EG upgrade instructions to reflect 2.2.0 release
- * Documentation: Remove antiquated 1.6 directory from docs folder
- * Documentation: Improve Fedora prereqs and instructions
- * Documentation: Bump OpenSRF prerequisite to 2.1 for Evergreen 2.2+
- * Documentation: link README to server install docs
- * Documentation: Merge the Evergreen docs into the code repository
- * Documentation: Fix typo in upgrade instructions
- * Documentation: Add line breaks in authorities chapter to fix
- * Documentation: Wording improvement for 2.2 release notes
- * JSPAC: Point to TPAC from <noscript> section
- * TPAC: Decode translated strings into UTF8
- * TPAC: Implement a locale picker
- * TPAC: Allow user to change activation options for suspended holds
- * TPAC: Fix recognition of logged-in users via HTTP
- * TPAC: repair editions statement display
- * TPAC: Set autofocus appropriately for different contexts
- * TPAC: Use % font size + bold to highlight login failure
- * TPAC: CSS change for login failure message
- * TPAC: Physical description, now with spaces
- * TPAC: Fix glitch returning from viewing ready-for-pickup to all holds
- * TPAC: Disable caching for auth-required pages
- * TPAC: Fix titles/tabs in Account Preferences subpages
- * TPAC: Handle multiple matches for an XPath expression
- * TPAC: Add paging to My Lists
- * TPAC: Add record detail navigation to page bottom
- * TPAC: Search wrapper spacing
- * Staff client: increase default width for the XUL list line number column
- * Staff client: Patron name border color for Notes
- * Staff client: Add component to force external browser use
- * Staff client: Allow opening of links in default browser
- * Staff client: Move Prefix field ahead of Names in patron editor
- * Staff client: Show in Catalog not working in bills interface
- * Repair PCrudFilter localeStrings variable collisions
- * Repaired typo in example rsyslog config file
- * Fix version numbers in 2.1 -> 2.2 upgrade script
- * Avoid problem with 2.1 -> 2.2 upgrade script issuing error about thesauri
- * 2.2 upgrade missing vandelay.authority_match.quality column
- * Teach the autosuggest web service to cache suggestions where appropriate
- * Add new columns to CDBI table definitions
- * Switch to a PLPERLU maintain_901() trigger function
- * Add evergreen.get_locale_name() function to base schema
- * Squelch uninitialized var warning from hold_copy_targeter
- * Silence undef string concatenation warning in AutoSuggest
--- /dev/null
+Release notes
+=============
+:toc:
+:numbered:
+
+Upgrade notes
+-------------
+
+Log Protect (redaction)
+~~~~~~~~~~~~~~~~~~~~~~~
+To prevent sensitive information such as passwords from being logged
+in general activity logs, add the following XML chunk to the bottom of
+`opensrf_core.xml`, just inside the `<config>` section:
+
+[source, xml]
+----------------------------------------------------------------
+ ...
+ </routers>
+ <shared> <!-- new block starts here -->
+ <log_protect>
+ <match_string>open-ils.auth.authenticate.verify</match_string>
+ <match_string>open-ils.auth.authenticate.complete</match_string>
+ <match_string>open-ils.auth_proxy.login</match_string>
+ <match_string>open-ils.actor.patron.password_reset.commit</match_string>
+ <match_string>open-ils.actor.user.password</match_string>
+ <match_string>open-ils.actor.user.username</match_string>
+ <match_string>open-ils.actor.user.email</match_string>
+ <match_string>open-ils.actor.patron.update</match_string>
+ <match_string>open-ils.cstore.direct.actor.user.create</match_string>
+ <match_string>open-ils.cstore.direct.actor.user.update</match_string>
+ <match_string>open-ils.cstore.direct.actor.user.delete</match_string>
+ </log_protect>
+ </shared> <!-- new block ends here -->
+</config>
+----------------------------------------------------------------
+
+EDI Order Template Updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+An updated EDI order template is now part of the stock data. To avoid
+clobbering potentially functional EDI templates, no upgrade script was
+included to automatically upgrade existing templates. To upgrade to the
+newest template:
+
+[source, sql]
+----------------------------------------------------------------
+UPDATE action_trigger.event_definition SET template =
+$$
+...
+$$ WHERE id = 23;
+
+/*
+Use the template value for event definition 23 (line 7995) in
+950.data.seed-values.sql as the contents (...) of the above command.
+*/
+----------------------------------------------------------------
+
+New features
+------------
+
+Acquisitions
+~~~~~~~~~~~~
+
+ACQ Invoice Inline Lineitem Search and Add
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Invoice UI is now composed of two tabs, the main invoice tab and a new
+Search tab. The search tab consists of a subset of the Acquisitions unified
+search interface. The goal is to allow users to search for lineitems to
+invoice. Search results may be added directly to the growing invoice. A number of small usability features are included.
+
+Features
+++++++++
+
+ * Option (default) to limit searches to invoiceable items.
+ ** These are lineitems that are not cancelled, have at least one invoiceable copy, linked to a PO whose provider matches that of the current invoice, and are not already linked to the current invoice.
+ * Search defaults to last-run search (on workstation).
+ * New Lineitem Detail filter options
+ * Sort searches by lineitem number (default) and title.
+ * There is a new Expected Cost field which includes both the total invoiced cost plus the anticipated cost of lineitems as they are added.
+ * New Price per Copy field
+ * Lineitem count field
+ * Show / Hide Invoice details button. Details are displayed by default, but hidden when the user enters the search tab. From there it remains hidden until manually shown (or a new invoice is opened).
+ * A new "Save & Clear" button which saves the current invoice then clears the invoice display to create a new invoice.
+ * Provider, shipper, and receiver fields are auto-populated from the first-added invoice data (when not already set).
+ * Totals are now read-only, since they are derived from existing data (and are informational only).
+
+
+EDI Invoices
+^^^^^^^^^^^^
+
+The same setup that is required today for retrieving and reacting to EDI Order
+Response messages (ORDRSP) will also react to Invoices (INVOIC).
+
+This essentially means you must have a Provider (acq.provider) configured with
+an EDI Account (acq.edi_account) containing login credentials for a vendor, you must have the edi_webrick service running (EDI translator), and you must have
+the edi_pusher script run periodically by cron.
+
+An open Evergreen invoice will be created for a each EDI Invoice message.
+Evergreen invoice entries will be created for each lineitem detected in the
+EDI message if that lineitem can be linked to a known Evergreen lineitem in
+your system. An Evergreen invoice item will be created for a whole-invoice
+tax.
+
+Enriched EDI
+^^^^^^^^^^^^
+
+Support for Enriched EDI with copy-level data via EDI in ORDER messages.
+
+Encumbrance-only Rollover
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new Library Setting allows the year-end close-out operation to roll over
+encumbrances while dumping any unspent money.
+
+Fund Report
+^^^^^^^^^^^
+
+A new IDL reporter view that provides summary information for funds for
+reporting. The resulting table looks like a fund with four additional fields:
+allocated_total, spent_total, encumbrance_total, and combined_balance.
+
+EDI Fetching and Parsing Enhancements / Repairs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This release includes various improvements to how Evergreen processes
+vendor EDI responses, including order responses and invoices. Changes
+include architectural improvements as well as new features.
+
+Bug Fixes
++++++++++
+
+* Improved order response handling for cancelled items.
+* Deleting fund debits (encumbrances) for cancelled items.
+* Extracting invoice date
+* Invoices include quantity and amount paid (in addition to billed) to reduce
+ manual staff data entry
+* Proper handling of previously-cancelled (e.g. back-ordered) invoiced items.
+
+Architectural improvements
+++++++++++++++++++++++++++
+
+For EDI parsing, the Ruby libraries, Ruby HTTP gateway, and Business::EDI Perl
+modules are no longer needed. They have been replaced with a single Perl
+module which handles EDI parsing.
+
+This reduces the complexity of the fetching and parsing layer. Though the Ruby
+libraries and Ruby HTTP gateway are still needed for outbound EDI (for now),
+the Perl Business::EDI modules are no longer needed at all, so they are no
+longer installed.
+
+EDI order template improvements (no SQL upgrade script!)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Improved template for EDI purchase orders. This theoretically just
+works better where the old template worked. Corrections made for
+interactions with ULS, Midwest Tape, Baker & Taylor, and Recorded Books
+especially. GIR segments in the right place.
+
+And also the template is just more maintainable now.
+
+**THERE IS NO UPGRADE SCRIPT INCLUDED**. Sites using EDI may not
+necessarily want to mess with what they already have working.
+
+If you want the changes, and maybe you do, especially if you're doing
+enriched ordering and/or ordering from the vendors listed above, you can
+extract the template changes easily enough yourself from the
+950.data.seed-values.sql file. See Upgrade Notes above.
+
+OPAC
+~~~~
+
+TPAC: Simplified CSS Color Customization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+CSS colors are now defined as a pair of Template::Toolkit files,
+`Open-ILS/src/templates/opac/css/styles.css.tt2` and
+`Open-ILS/src/templates/opac/parts/css/colors.tt2`. Evergreen administrators
+can customize the color scheme for a given skin by copying `colors.tt2` into a
+template override directory and adjusting the colors as desired.
+
+Change required to eg_vhost.conf
+++++++++++++++++++++++++++++++++
+To enable Apache to pass the CSS file to the Template::Toolkit handler, you
+must remove `.css` from the list of file extensions that should not be passed
+to a handler in `eg_vhost.conf` as follows:
+
+.From
+------------------------------------------------------------------------------
+<LocationMatch ^/eg/.*(\.js|\.css|\.html|\.xhtml|\.xml|\.jpg|\.png|\.gif)$>
+ SetHandler None
+</LocationMatch>
+------------------------------------------------------------------------------
+
+.To
+------------------------------------------------------------------------------
+<LocationMatch ^/eg/.*(\.js|\.html|\.xhtml|\.xml|\.jpg|\.png|\.gif)$>
+ SetHandler None
+</LocationMatch>
+------------------------------------------------------------------------------
+
+After making this change, restart Apache to make the change take effect.
+
+
+Add to Permanent Bookbag
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+TPAC was modified to allow a logged-in user to add records from search
+results and record summary screens to their permanent bookbags rather
+than to a temporary bookbag that goes away when logged out.
+
+Bookbag Selection Menu
+++++++++++++++++++++++
+
+The search results and record summary screens were modified so that
+the "Add to my list" will show a menu when moused over by a logged-in
+user. This menu will display the option to add to a temporary
+bookbag, the user's default list (if any), up to ten of the user's
+other bookbags, a "See all" option to allow the user to choose one of
+the bags not on the menu, and to create a new list and add the record
+to it.
+
+Choosing the temporary list from the menu will add the record to the
+temporary my list as TPAC does before the addition of this feature.
+
+Choosing a named list will add the record to the chosen list.
+
+Choosing "See all" or "Add to new list" will take the user to their My
+Lists page. (The only difference being that "See all" will actually
+list all of the user's bookbags if they have more than the current
+limit.) The My Lists page will have a new button "Add to this list"
+next to each of their existing lists. In addition, if the user
+creates a new list on this screen, the selected record will
+automatically be added to this new list.
+
+You can tell all of the above is working if you are redirected to your
+search results or record summary after adding to a list. If there was
+a problem, you will get either an error page or will see your My Lists
+page.
+
+Designating a Default Bookbag/list
+++++++++++++++++++++++++++++++++++
+
+The user's My List screen has had a 'Make Default List' button added
+for each list. Clicking the button will cause that list to be
+registered as the user's default list. This is the list that will be
+added to when a user chooses the Default List option on the Add to my
+list menu in search or record summary.
+
+The current default list has a 'Remove Default List' button next to
+it. Clicking this button will unset the default status of the list
+and return to a state of having no default list.
+
+One handy way that users may want to use this feature is to create a
+new list, and then designate it as the default. This list could then
+be used to add records from searches based on a current topic of
+interest. Changing the default list is so easy that users may want to
+do so when changing search topics in order to keep their results
+better organized.
+
+A Note on CSS Styles
+++++++++++++++++++++
+
+If a user has a bookbag with an overly long name, the end of it will
+jut out past the right margin of the menu in Firefox and several other
+browsers. To change this behavior, you may want to edit the `.popmenu
+li:hover li a` css entry in `web/css/skin/default/opac/style.css` by
+adding an `overflow` property. If you desire to have the longer names
+clipped to the size of the menu then add `overflow: hidden`. If you
+prefer to have a scroll bar for oversized entries, then add `overflow:
+auto`.
+
+
+Warn When Adding to a Temporary Bookbag
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+TPAC has been modified so that a user will see a warning before adding
+a record to a temporary bookbag. This message serves to inform the
+user that they are adding to a temporary list that will disappear when
+their session ends.
+
+A new org. unit setting has been added,
+opac.patron.temporary_list_warn, that will enable this warning when
+set. Sites may choose not to display this warning.
+
+The user may also set a preference in their search preferences to
+disable this warning. The setting only works when a user is logged
+in, of course.
+
+Kid's 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.
+
+
+Locale picker
+^^^^^^^^^^^^^
+
+In situations in which more than a single locale is configured, the TPAC header
+will display a locale picker based on the registered locales.
+
+Hidden Place Hold Links
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The title-level 'Place Hold' link in TPAC will be hidden on the search result
+and record summary screens when there are no holdable copies on the bib. This
+is based on the copy, status and location holdable flags.
+
+When enabled in config.tt2, the 'Place Holds' link in TPAC will also be hidden
+if copies are available in the search location.
+
+Library Selectors in Advanced Searches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The library selector is now available on the numeric and expert search pages.
+
+Journal Title Search
+^^^^^^^^^^^^^^^^^^^^
+
+A journal title search is now available as a stock TPAC filter.
+
+Public Patron Notes
+^^^^^^^^^^^^^^^^^^^
+
+Public patron notes are now visible in the 'Account Summary' box of 'My
+Account'.
+
+Auto-Override Permissible Patron Hold Fail Events
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new Library Setting is available that tells TPAC to automatically override
+hold placement failure events in cases where the patron has the permission to
+do so. The goal is to skip the confirmation step previously required by patrons
+when overriding a TPAC hold.
+
+Cataloging
+~~~~~~~~~~
+
+Z39.50 Source Attributes Management Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is a new interface for managing Z39.50 attributes on a Z39.50
+source. The interface is linked from each source name in the Z39.50
+Source administrative interface.
+
+Cloning
++++++++
+
+In addition to attribute creation, deletion, and editing, it's also
+possible to clone a set of attributes from one source into another.
+When cloning, any attributes present in the cloned source that are
+not present in the destination source are copied into the destination
+source.
+
+Vandelay (MARC Import/Export) Copy Overlay
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Vandelay Item Attributes (Cataloging -> MARC Import /
+Export -> Import Item Attribute Definitions) contains
+a new field called "Overlay Match ID". The presence of data
+in this field extracted from an import-item copy indicates
+to the Vandelay import process that a copy overlay is requested
+instead of new copy creation. The value for the field is the
+copy id for bib record queues and the ACQ lineitem_detail ID for
+Acquisitions Queues. For either type of queue, however, overlay
+occurs against a real copy (asset.copy). In the ACQ queue case,
+we use the lineitem_detail ID because this is the data ACQ
+providers and sub-systems will have access to.
+
+When a match point ID value is a set and a matching copy is found,
+the values extracted from the inbound copy data are used to replace
+values on the existing found copy, including the call-number label.
+Any fields on the inbound copy that are empty are ignored.
+
+One use case for this feature are shelf-ready items produced by a
+3rd-party (e.g. ACQ provider) and delivered to the library via MARC
+file for upload. The file might contain improved MARC bibliographic
+data as well as real barcodes (i.e. not temporary ACQ generated
+barcodes) for the copies already purchased through the vendor.
+
+Permission
+++++++++++
+
+This adds a new permission called IMPORT_OVERLAY_COPY which is
+required to perform the copy overlay step.
+
+Regardless of permission, it is not possible to overlay values on
+a copy unless the imported bib record links (creates/overlays/merges)
+to/with the owning bib record for the copy to be overlaid. This is
+both for security and removal of a potent foot-gun.
+
+Circulation
+~~~~~~~~~~~
+
+Simplified Hold Pull List
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is a new hold pull list interface based on the Flattener service that's
+designed to perform faster than existing pull list interfaces, both in staff
+client display and printing.
+
+Sorting
++++++++
+
+You can sort on any one column by clicking on it. Click again to reverse
+direction. This is typical of similar interfaces.
+
+Now you can also sort by multiple columns. Right click the column headers of
+the grid in the pull list interface to get a dialog that allows you to sort
+by multiple columns, in any order.
+
+Column Picking
+++++++++++++++
+
+The same dialog that allows you to choose multiple sort columns (accessed by
+right clicking any column header) also allows you to toggle the display of any
+column available to the pull list on or off.
+
+Persistence
++++++++++++
+
+Once saved, your changes in this dialog persist for your user account. Column
+display, display order, and `sorting choices affect printing as well as
+displayed output.
+
+Administration
+~~~~~~~~~~~~~~
+
+Search Filter Groups
+^^^^^^^^^^^^^^^^^^^^
+
+Search filter groups support the collection of free-form search queries into
+named groups of named filters which can be applied to searches. The purpose
+is to allow systems to fine tune filters in the catalog.
+
+Editing the groups and their entries is done in the staff client at
+Admin -> Local Administration -> Search Filter Groups.
+
+Example
++++++++
+
+Consider a new filter called "reading_level". It uses a combination of
+MARC audience and shelving location to differentiate items. It might have
+entries that look like this:
+
+Children's Materials => audience(a,b,c) locations(1,2,3,4,5,6,7)
+
+Young Adult => audience(j,d) locations(5,6,7,8,9,10)
+
+Adult => audience(e,f,g, ) -locations(1,2,3,4,5,6,7,8,9)
+
+Using the filter in a template
+++++++++++++++++++++++++++++++
+
+[source, html]
+---------------------------------------------------
+<span>[% ctx.filter_groups.reading_level.label %]</span>
+<span>
+[%
+ INCLUDE 'opac/parts/filter_group_selector.tt2'
+ filter_group='reading_level'
+ none_ok=1
+ none_label=l('All')
+%]
+</span>
+---------------------------------------------------
+
+Standing Penalty CAPTURE and FULFILL Blocks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This feature adds two additional types of standing penalty blocks to manage
+holds.
+
+When a user has a standing penalty containing 'CAPTURE' in the block list, the
+user can place holds (pending no 'HOLD' block), but no holds for the user will
+be captured. This is effectively a policy-based freeze of the hold.
+
+Users that have penalties with 'FULFILL' in the block list will be able to
+place holds and have their holds captured (i.e. delivered) but will not be able
+to check out the captured holds. This is basically a way to get patrons in to
+pay outstanding balances.
+
+Copy Location Additions to Circulation Policies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Similar to circulation modifiers, circ policies can now be based on copy
+location. This also adds copy location to the circ matrix weights and to circ
+limit sets.
+
+Staff Client
+~~~~~~~~~~~~
+
+XULRunner / Firefox
+^^^^^^^^^^^^^^^^^^^
+Support for later versions of XULRunner is included, which means that later
+improvements to XULRunner can be taken advantage of. This also means that the
+Firefox extension mode works in Firefox 3.6+, though some frequent tweaking
+will be needed due to the rapid Firefox major release schedule.
+
+The majority of the actual changes are backend changes, but there are some
+significant things to note for local customizations.
+
+Remote XUL
+++++++++++
+Remote XUL no longer works in XULRunner/Firefox 4+, but to work around it a
+custom extension now creates an oils:// wrapper. Within the staff client that
+wrapper contains a "remote" host, from which server-side XUL can be loaded.
+
+Custom XUL pages stored on the server will need to reference the new wrapper
+to function.
+
+As a note: The new wrapper is used for all OPAC access and only talks SSL.
+
+enablePrivilege
++++++++++++++++
+The enablePrivilege command that would allow code to access various protected
+functionality is no longer available. Any code that depended upon it will need
+to be adjusted to use the oils:// wrapper created for Remote XUL.
+
+Cookies
++++++++
+Unfortunately, the oils:// wrapper has one less than useful effect. Any
+JavaScript loaded via it loses access to cookies. This is most notable when you
+are dealing with authtoken cookies. This only applies to JavaScript, however,
+and the server can still see the cookies when it gets requests.
+
+As a workaround you can load the data stash and fetch authtokens via it instead.
+This should always work when using the oils:// wrapper due to the elevated
+permission set it gets (nearly, if not equal to, local XUL).
+
+url_prefix
+++++++++++
+Finally, as a useful feature, the url_prefix function is now slightly easier to
+use. Instead of needing to reference urls.SOMETHING you can instead just put the
+SOMETHING at the start of the url to prefix:
+
+url_prefix('SOMETHING/stuff.html')
+
+In this case SOMETHING can be terminated by the end of the string or up to the
+first instance of a slash (/), question mark (?), or pipe (|). The pipe is a
+special case and is removed during the replacement.
+
+For example, if urls.REPLACE were set to 'oils://remote/replace':
+
+url_prefix('REPLACE/stuff') becomes 'oils://remote/replace/stuff'
+url_prefix('REPLACE?query') becomes 'oils://remote/replace?query'
+url_prefix('REPLACE|ment') becomes 'oils://remote/replacement'
+
+The pipe is intended for cases where the urls entry may or may not already
+contain a query string, say for differences between OPACs where one requires
+that something be passed into the query string, but the other uses a path
+component instead.
+
+New Operator Change Features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The operator change dialog has a new dropdown allowing the selection of a
+Temporary, Staff, or Permanent authtoken. The first option provides a temporary
+operator change as has typically been done through this menu item. 'Staff' uses
+a normal staff login authtoken for a multi-hour timeout. 'Permanent' is a staff
+change that disregards the previous login instead of allowing it to be
+recovered by using the menu item again.
+
+Additional Work Log Entries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Entries for bill payment and hold placement are now available in the 'Work Log'.
+
+SIP
+~~~
+
+Support for credit card payment type and fine items details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Support is now available to create a credit card payment type in the SIP Fee
+Paid message. There is also now support for SIP clients to retrieve and
+display a detailed/itemized list of billings to the patron.
+
+Staff Client Initial Hostname
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For fresh installs of the staff client a common issue is people remembering
+what hostname to specify. If you are building your own staff clients you can
+now fill this in automatically.
+
+You can specify this when configuring Evergreen with a new configure option:
+
+--with-initialhost=example.org
+
+It is also possible to specify when building the staff client itself using the
+INITIAL_HOST variable:
+
+make INITIAL_HOST=example.org build
+++ /dev/null
-Release notes
-=============
-:toc:
-:numbered:
-
-Upgrade notes
--------------
-
-Log Protect (redaction)
-~~~~~~~~~~~~~~~~~~~~~~~
-To prevent sensitive information such as passwords from being logged
-in general activity logs, add the following XML chunk to the bottom of
-`opensrf_core.xml`, just inside the `<config>` section:
-
-[source, xml]
-----------------------------------------------------------------
- ...
- </routers>
- <shared> <!-- new block starts here -->
- <log_protect>
- <match_string>open-ils.auth.authenticate.verify</match_string>
- <match_string>open-ils.auth.authenticate.complete</match_string>
- <match_string>open-ils.auth_proxy.login</match_string>
- <match_string>open-ils.actor.patron.password_reset.commit</match_string>
- <match_string>open-ils.actor.user.password</match_string>
- <match_string>open-ils.actor.user.username</match_string>
- <match_string>open-ils.actor.user.email</match_string>
- <match_string>open-ils.actor.patron.update</match_string>
- <match_string>open-ils.cstore.direct.actor.user.create</match_string>
- <match_string>open-ils.cstore.direct.actor.user.update</match_string>
- <match_string>open-ils.cstore.direct.actor.user.delete</match_string>
- </log_protect>
- </shared> <!-- new block ends here -->
-</config>
-----------------------------------------------------------------
-
-EDI Order Template Updates
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-An updated EDI order template is now part of the stock data. To avoid
-clobbering potentially functional EDI templates, no upgrade script was
-included to automatically upgrade existing templates. To upgrade to the
-newest template:
-
-[source, sql]
-----------------------------------------------------------------
-UPDATE action_trigger.event_definition SET template =
-$$
-...
-$$ WHERE id = 23;
-
-/*
-Use the template value for event definition 23 (line 7995) in
-950.data.seed-values.sql as the contents (...) of the above command.
-*/
-----------------------------------------------------------------
-
-New features
-------------
-
-Acquisitions
-~~~~~~~~~~~~
-
-ACQ Invoice Inline Lineitem Search and Add
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Invoice UI is now composed of two tabs, the main invoice tab and a new
-Search tab. The search tab consists of a subset of the Acquisitions unified
-search interface. The goal is to allow users to search for lineitems to
-invoice. Search results may be added directly to the growing invoice. A number of small usability features are included.
-
-Features
-++++++++
-
- * Option (default) to limit searches to invoiceable items.
- ** These are lineitems that are not cancelled, have at least one invoiceable copy, linked to a PO whose provider matches that of the current invoice, and are not already linked to the current invoice.
- * Search defaults to last-run search (on workstation).
- * New Lineitem Detail filter options
- * Sort searches by lineitem number (default) and title.
- * There is a new Expected Cost field which includes both the total invoiced cost plus the anticipated cost of lineitems as they are added.
- * New Price per Copy field
- * Lineitem count field
- * Show / Hide Invoice details button. Details are displayed by default, but hidden when the user enters the search tab. From there it remains hidden until manually shown (or a new invoice is opened).
- * A new "Save & Clear" button which saves the current invoice then clears the invoice display to create a new invoice.
- * Provider, shipper, and receiver fields are auto-populated from the first-added invoice data (when not already set).
- * Totals are now read-only, since they are derived from existing data (and are informational only).
-
-
-EDI Invoices
-^^^^^^^^^^^^
-
-The same setup that is required today for retrieving and reacting to EDI Order
-Response messages (ORDRSP) will also react to Invoices (INVOIC).
-
-This essentially means you must have a Provider (acq.provider) configured with
-an EDI Account (acq.edi_account) containing login credentials for a vendor, you must have the edi_webrick service running (EDI translator), and you must have
-the edi_pusher script run periodically by cron.
-
-An open Evergreen invoice will be created for a each EDI Invoice message.
-Evergreen invoice entries will be created for each lineitem detected in the
-EDI message if that lineitem can be linked to a known Evergreen lineitem in
-your system. An Evergreen invoice item will be created for a whole-invoice
-tax.
-
-Enriched EDI
-^^^^^^^^^^^^
-
-Support for Enriched EDI with copy-level data via EDI in ORDER messages.
-
-Encumbrance-only Rollover
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A new Library Setting allows the year-end close-out operation to roll over
-encumbrances while dumping any unspent money.
-
-Fund Report
-^^^^^^^^^^^
-
-A new IDL reporter view that provides summary information for funds for
-reporting. The resulting table looks like a fund with four additional fields:
-allocated_total, spent_total, encumbrance_total, and combined_balance.
-
-EDI Fetching and Parsing Enhancements / Repairs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This release includes various improvements to how Evergreen processes
-vendor EDI responses, including order responses and invoices. Changes
-include architectural improvements as well as new features.
-
-Bug Fixes
-+++++++++
-
-* Improved order response handling for cancelled items.
-* Deleting fund debits (encumbrances) for cancelled items.
-* Extracting invoice date
-* Invoices include quantity and amount paid (in addition to billed) to reduce
- manual staff data entry
-* Proper handling of previously-cancelled (e.g. back-ordered) invoiced items.
-
-Architectural improvements
-++++++++++++++++++++++++++
-
-For EDI parsing, the Ruby libraries, Ruby HTTP gateway, and Business::EDI Perl
-modules are no longer needed. They have been replaced with a single Perl
-module which handles EDI parsing.
-
-This reduces the complexity of the fetching and parsing layer. Though the Ruby
-libraries and Ruby HTTP gateway are still needed for outbound EDI (for now),
-the Perl Business::EDI modules are no longer needed at all, so they are no
-longer installed.
-
-EDI order template improvements (no SQL upgrade script!)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Improved template for EDI purchase orders. This theoretically just
-works better where the old template worked. Corrections made for
-interactions with ULS, Midwest Tape, Baker & Taylor, and Recorded Books
-especially. GIR segments in the right place.
-
-And also the template is just more maintainable now.
-
-**THERE IS NO UPGRADE SCRIPT INCLUDED**. Sites using EDI may not
-necessarily want to mess with what they already have working.
-
-If you want the changes, and maybe you do, especially if you're doing
-enriched ordering and/or ordering from the vendors listed above, you can
-extract the template changes easily enough yourself from the
-950.data.seed-values.sql file. See Upgrade Notes above.
-
-OPAC
-~~~~
-
-TPAC: Simplified CSS Color Customization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-CSS colors are now defined as a pair of Template::Toolkit files,
-`Open-ILS/src/templates/opac/css/styles.css.tt2` and
-`Open-ILS/src/templates/opac/parts/css/colors.tt2`. Evergreen administrators
-can customize the color scheme for a given skin by copying `colors.tt2` into a
-template override directory and adjusting the colors as desired.
-
-Change required to eg_vhost.conf
-++++++++++++++++++++++++++++++++
-To enable Apache to pass the CSS file to the Template::Toolkit handler, you
-must remove `.css` from the list of file extensions that should not be passed
-to a handler in `eg_vhost.conf` as follows:
-
-.From
-------------------------------------------------------------------------------
-<LocationMatch ^/eg/.*(\.js|\.css|\.html|\.xhtml|\.xml|\.jpg|\.png|\.gif)$>
- SetHandler None
-</LocationMatch>
-------------------------------------------------------------------------------
-
-.To
-------------------------------------------------------------------------------
-<LocationMatch ^/eg/.*(\.js|\.html|\.xhtml|\.xml|\.jpg|\.png|\.gif)$>
- SetHandler None
-</LocationMatch>
-------------------------------------------------------------------------------
-
-After making this change, restart Apache to make the change take effect.
-
-
-Add to Permanent Bookbag
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-TPAC was modified to allow a logged-in user to add records from search
-results and record summary screens to their permanent bookbags rather
-than to a temporary bookbag that goes away when logged out.
-
-Bookbag Selection Menu
-++++++++++++++++++++++
-
-The search results and record summary screens were modified so that
-the "Add to my list" will show a menu when moused over by a logged-in
-user. This menu will display the option to add to a temporary
-bookbag, the user's default list (if any), up to ten of the user's
-other bookbags, a "See all" option to allow the user to choose one of
-the bags not on the menu, and to create a new list and add the record
-to it.
-
-Choosing the temporary list from the menu will add the record to the
-temporary my list as TPAC does before the addition of this feature.
-
-Choosing a named list will add the record to the chosen list.
-
-Choosing "See all" or "Add to new list" will take the user to their My
-Lists page. (The only difference being that "See all" will actually
-list all of the user's bookbags if they have more than the current
-limit.) The My Lists page will have a new button "Add to this list"
-next to each of their existing lists. In addition, if the user
-creates a new list on this screen, the selected record will
-automatically be added to this new list.
-
-You can tell all of the above is working if you are redirected to your
-search results or record summary after adding to a list. If there was
-a problem, you will get either an error page or will see your My Lists
-page.
-
-Designating a Default Bookbag/list
-++++++++++++++++++++++++++++++++++
-
-The user's My List screen has had a 'Make Default List' button added
-for each list. Clicking the button will cause that list to be
-registered as the user's default list. This is the list that will be
-added to when a user chooses the Default List option on the Add to my
-list menu in search or record summary.
-
-The current default list has a 'Remove Default List' button next to
-it. Clicking this button will unset the default status of the list
-and return to a state of having no default list.
-
-One handy way that users may want to use this feature is to create a
-new list, and then designate it as the default. This list could then
-be used to add records from searches based on a current topic of
-interest. Changing the default list is so easy that users may want to
-do so when changing search topics in order to keep their results
-better organized.
-
-A Note on CSS Styles
-++++++++++++++++++++
-
-If a user has a bookbag with an overly long name, the end of it will
-jut out past the right margin of the menu in Firefox and several other
-browsers. To change this behavior, you may want to edit the `.popmenu
-li:hover li a` css entry in `web/css/skin/default/opac/style.css` by
-adding an `overflow` property. If you desire to have the longer names
-clipped to the size of the menu then add `overflow: hidden`. If you
-prefer to have a scroll bar for oversized entries, then add `overflow:
-auto`.
-
-
-Warn When Adding to a Temporary Bookbag
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-TPAC has been modified so that a user will see a warning before adding
-a record to a temporary bookbag. This message serves to inform the
-user that they are adding to a temporary list that will disappear when
-their session ends.
-
-A new org. unit setting has been added,
-opac.patron.temporary_list_warn, that will enable this warning when
-set. Sites may choose not to display this warning.
-
-The user may also set a preference in their search preferences to
-disable this warning. The setting only works when a user is logged
-in, of course.
-
-Kid's 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.
-
-
-Locale picker
-^^^^^^^^^^^^^
-
-In situations in which more than a single locale is configured, the TPAC header
-will display a locale picker based on the registered locales.
-
-Hidden Place Hold Links
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The title-level 'Place Hold' link in TPAC will be hidden on the search result
-and record summary screens when there are no holdable copies on the bib. This
-is based on the copy, status and location holdable flags.
-
-When enabled in config.tt2, the 'Place Holds' link in TPAC will also be hidden
-if copies are available in the search location.
-
-Library Selectors in Advanced Searches
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The library selector is now available on the numeric and expert search pages.
-
-Journal Title Search
-^^^^^^^^^^^^^^^^^^^^
-
-A journal title search is now available as a stock TPAC filter.
-
-Public Patron Notes
-^^^^^^^^^^^^^^^^^^^
-
-Public patron notes are now visible in the 'Account Summary' box of 'My
-Account'.
-
-Auto-Override Permissible Patron Hold Fail Events
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A new Library Setting is available that tells TPAC to automatically override
-hold placement failure events in cases where the patron has the permission to
-do so. The goal is to skip the confirmation step previously required by patrons
-when overriding a TPAC hold.
-
-Cataloging
-~~~~~~~~~~
-
-Z39.50 Source Attributes Management Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There is a new interface for managing Z39.50 attributes on a Z39.50
-source. The interface is linked from each source name in the Z39.50
-Source administrative interface.
-
-Cloning
-+++++++
-
-In addition to attribute creation, deletion, and editing, it's also
-possible to clone a set of attributes from one source into another.
-When cloning, any attributes present in the cloned source that are
-not present in the destination source are copied into the destination
-source.
-
-Vandelay (MARC Import/Export) Copy Overlay
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Vandelay Item Attributes (Cataloging -> MARC Import /
-Export -> Import Item Attribute Definitions) contains
-a new field called "Overlay Match ID". The presence of data
-in this field extracted from an import-item copy indicates
-to the Vandelay import process that a copy overlay is requested
-instead of new copy creation. The value for the field is the
-copy id for bib record queues and the ACQ lineitem_detail ID for
-Acquisitions Queues. For either type of queue, however, overlay
-occurs against a real copy (asset.copy). In the ACQ queue case,
-we use the lineitem_detail ID because this is the data ACQ
-providers and sub-systems will have access to.
-
-When a match point ID value is a set and a matching copy is found,
-the values extracted from the inbound copy data are used to replace
-values on the existing found copy, including the call-number label.
-Any fields on the inbound copy that are empty are ignored.
-
-One use case for this feature are shelf-ready items produced by a
-3rd-party (e.g. ACQ provider) and delivered to the library via MARC
-file for upload. The file might contain improved MARC bibliographic
-data as well as real barcodes (i.e. not temporary ACQ generated
-barcodes) for the copies already purchased through the vendor.
-
-Permission
-++++++++++
-
-This adds a new permission called IMPORT_OVERLAY_COPY which is
-required to perform the copy overlay step.
-
-Regardless of permission, it is not possible to overlay values on
-a copy unless the imported bib record links (creates/overlays/merges)
-to/with the owning bib record for the copy to be overlaid. This is
-both for security and removal of a potent foot-gun.
-
-Circulation
-~~~~~~~~~~~
-
-Simplified Hold Pull List
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There is a new hold pull list interface based on the Flattener service that's
-designed to perform faster than existing pull list interfaces, both in staff
-client display and printing.
-
-Sorting
-+++++++
-
-You can sort on any one column by clicking on it. Click again to reverse
-direction. This is typical of similar interfaces.
-
-Now you can also sort by multiple columns. Right click the column headers of
-the grid in the pull list interface to get a dialog that allows you to sort
-by multiple columns, in any order.
-
-Column Picking
-++++++++++++++
-
-The same dialog that allows you to choose multiple sort columns (accessed by
-right clicking any column header) also allows you to toggle the display of any
-column available to the pull list on or off.
-
-Persistence
-+++++++++++
-
-Once saved, your changes in this dialog persist for your user account. Column
-display, display order, and `sorting choices affect printing as well as
-displayed output.
-
-Administration
-~~~~~~~~~~~~~~
-
-Search Filter Groups
-^^^^^^^^^^^^^^^^^^^^
-
-Search filter groups support the collection of free-form search queries into
-named groups of named filters which can be applied to searches. The purpose
-is to allow systems to fine tune filters in the catalog.
-
-Editing the groups and their entries is done in the staff client at
-Admin -> Local Administration -> Search Filter Groups.
-
-Example
-+++++++
-
-Consider a new filter called "reading_level". It uses a combination of
-MARC audience and shelving location to differentiate items. It might have
-entries that look like this:
-
-Children's Materials => audience(a,b,c) locations(1,2,3,4,5,6,7)
-
-Young Adult => audience(j,d) locations(5,6,7,8,9,10)
-
-Adult => audience(e,f,g, ) -locations(1,2,3,4,5,6,7,8,9)
-
-Using the filter in a template
-++++++++++++++++++++++++++++++
-
-[source, html]
----------------------------------------------------
-<span>[% ctx.filter_groups.reading_level.label %]</span>
-<span>
-[%
- INCLUDE 'opac/parts/filter_group_selector.tt2'
- filter_group='reading_level'
- none_ok=1
- none_label=l('All')
-%]
-</span>
----------------------------------------------------
-
-Standing Penalty CAPTURE and FULFILL Blocks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This feature adds two additional types of standing penalty blocks to manage
-holds.
-
-When a user has a standing penalty containing 'CAPTURE' in the block list, the
-user can place holds (pending no 'HOLD' block), but no holds for the user will
-be captured. This is effectively a policy-based freeze of the hold.
-
-Users that have penalties with 'FULFILL' in the block list will be able to
-place holds and have their holds captured (i.e. delivered) but will not be able
-to check out the captured holds. This is basically a way to get patrons in to
-pay outstanding balances.
-
-Copy Location Additions to Circulation Policies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Similar to circulation modifiers, circ policies can now be based on copy
-location. This also adds copy location to the circ matrix weights and to circ
-limit sets.
-
-Staff Client
-~~~~~~~~~~~~
-
-XULRunner / Firefox
-^^^^^^^^^^^^^^^^^^^
-Support for later versions of XULRunner is included, which means that later
-improvements to XULRunner can be taken advantage of. This also means that the
-Firefox extension mode works in Firefox 3.6+, though some frequent tweaking
-will be needed due to the rapid Firefox major release schedule.
-
-The majority of the actual changes are backend changes, but there are some
-significant things to note for local customizations.
-
-Remote XUL
-++++++++++
-Remote XUL no longer works in XULRunner/Firefox 4+, but to work around it a
-custom extension now creates an oils:// wrapper. Within the staff client that
-wrapper contains a "remote" host, from which server-side XUL can be loaded.
-
-Custom XUL pages stored on the server will need to reference the new wrapper
-to function.
-
-As a note: The new wrapper is used for all OPAC access and only talks SSL.
-
-enablePrivilege
-+++++++++++++++
-The enablePrivilege command that would allow code to access various protected
-functionality is no longer available. Any code that depended upon it will need
-to be adjusted to use the oils:// wrapper created for Remote XUL.
-
-Cookies
-+++++++
-Unfortunately, the oils:// wrapper has one less than useful effect. Any
-JavaScript loaded via it loses access to cookies. This is most notable when you
-are dealing with authtoken cookies. This only applies to JavaScript, however,
-and the server can still see the cookies when it gets requests.
-
-As a workaround you can load the data stash and fetch authtokens via it instead.
-This should always work when using the oils:// wrapper due to the elevated
-permission set it gets (nearly, if not equal to, local XUL).
-
-url_prefix
-++++++++++
-Finally, as a useful feature, the url_prefix function is now slightly easier to
-use. Instead of needing to reference urls.SOMETHING you can instead just put the
-SOMETHING at the start of the url to prefix:
-
-url_prefix('SOMETHING/stuff.html')
-
-In this case SOMETHING can be terminated by the end of the string or up to the
-first instance of a slash (/), question mark (?), or pipe (|). The pipe is a
-special case and is removed during the replacement.
-
-For example, if urls.REPLACE were set to 'oils://remote/replace':
-
-url_prefix('REPLACE/stuff') becomes 'oils://remote/replace/stuff'
-url_prefix('REPLACE?query') becomes 'oils://remote/replace?query'
-url_prefix('REPLACE|ment') becomes 'oils://remote/replacement'
-
-The pipe is intended for cases where the urls entry may or may not already
-contain a query string, say for differences between OPACs where one requires
-that something be passed into the query string, but the other uses a path
-component instead.
-
-New Operator Change Features
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The operator change dialog has a new dropdown allowing the selection of a
-Temporary, Staff, or Permanent authtoken. The first option provides a temporary
-operator change as has typically been done through this menu item. 'Staff' uses
-a normal staff login authtoken for a multi-hour timeout. 'Permanent' is a staff
-change that disregards the previous login instead of allowing it to be
-recovered by using the menu item again.
-
-Additional Work Log Entries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Entries for bill payment and hold placement are now available in the 'Work Log'.
-
-SIP
-~~~
-
-Support for credit card payment type and fine items details
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Support is now available to create a credit card payment type in the SIP Fee
-Paid message. There is also now support for SIP clients to retrieve and
-display a detailed/itemized list of billings to the patron.
-
-Staff Client Initial Hostname
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For fresh installs of the staff client a common issue is people remembering
-what hostname to specify. If you are building your own staff clients you can
-now fill this in automatically.
-
-You can specify this when configuring Evergreen with a new configure option:
-
---with-initialhost=example.org
-
-It is also possible to specify when building the staff client itself using the
-INITIAL_HOST variable:
-
-make INITIAL_HOST=example.org build
--- /dev/null
+Evergreen 2.4.0 Release Notes
+=============================
+:toc:
+:numbered:
+
+Upgrade notes
+-------------
+
+Custom Toolbar Permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+With the addition of more granular permissions for configuring a custom
+toolbars, the ADMIN_TOOLBAR permission alone will not allow users to
+configure a custom toolbar. This permission must now be used in conjunction
+with one or more of the following permissions:
+
+* ADMIN_TOOLBAR_FOR_ORG
+* ADMIN_TOOLBAR_FOR_USER
+* ADMIN_TOOLBAR_FOR_WORKSTATION
+
+New features
+------------
+
+Acquisitions
+~~~~~~~~~~~~
+
+Acquisitions Inline Item Detail View
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Acquisitions selection lists and purchase order interfaces contain a new link
+beside each lineitem which, when clicked, creates an inline grid of copies
+linked to the lineitem. The grid contains the same information that displays
+in the full copy edit grid (from clicking on the Copies(n) link). However,
+the inline grid is read-only, so it displays much faster and does not require
+the user to change visual contexts.
+
+Included along the top of the lineitem table is a new 'Expand All' link which,
+when clicked, expands or collapses the inline grid for all visible lineitems.
+
+Acquisitions Lineitem Order Identifiers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Staff now have the ability to specify the identifier value to use for
+lineitems when communicating order information to vendors. This is
+particularly important when a lineitem has, for example, multiple ISBNs.
+Determining which ISBN is to act as the "order identifier" allows staff
+to provide the most accurate order information to vendors.
+
+Supported identifier types include ISBN, ISSN, and UPC. Order identifier
+values are relayed to vendors via EDI and print PO.
+
+Permissions
++++++++++++++
+Two new permissions are added for this feature:
+
+ * ACQ_SET_LINEITEM_IDENTIFIER
+ ** Allows staff to apply order identifiers to lineitems
+ * ACQ_ADD_LINEITEM_IDENTIFIER
+ ** Implies that new identifiers shall be added to linked bib records,
+ when a linkage exists.
+
+Acquisitions Purchase Order and other Interface Improvements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Feature Summary
++++++++++++++++
+
+The following features, which primarily affect the user interface layer,
+improve Acquisitions work flows.
+
+ * Avoid double-activation of POs
+ * Disable invoice and cancel options for pending POs
+ * Disable zero-copy checkbox for activated POs
+ * Disable new charges for activated POs
+ * Replace "Shelving Location" with Copy Location
+
+ * Rearranging "actions" drop-down
+ ** More consistency in actions applying to selected lineitems specifically
+ ** Things moved from the per-lineitem dropdown to the main one when
+ sensible.
+ ** Add to PO dialog added
+ ** You can no longer add lineitems to a PO if they're already on one.
+ ** Actions in dropdown now enabled/disabled differently depending on
+ the interface where it appears (PO vs Selection List vs Acq Search etc.)
+
+ * Batch update for line items
+ ** Apply updates to all copies of all selected line items at once
+ ** Relies on a middle layer method that streams back information that
+ would suit a more asynchronous display in the future (rather than
+ simply reloading the page upon success, which it does now)
+ ** For failure cases, specific information about which line item cannot
+ be updated, and why, is available to the client, although taking
+ best advantage of this information for user-friendly display is left
+ to the future.
+ * Add optional fund, circ modifier and collection code fields to distribution
+ formulas.
+ * The invoices interface auto-populates "# Invoiced" column with number of
+ invoiceable copies, and copies the "billed cost" column to the "amount paid"
+ column if the latter doesn't have anything in it yet.
+
+Acquisitions MARC Upload Form Persistence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Adds a two-layer persistence mechanism for the acquisitions MARC file upload
+interface. A set of org unit settings now exist for managing default values
+for the interface. Additionally, for each field where no org unit setting
+value is configured, the last-used value will be persisted locally and re-
+used with subsequent loads of the interface.
+
+Default Number of Acquisitions Copies to Order
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Acquisitions providers have a new "Default # Copies" field. When the value
+is set, this number of copies will be automatically added to each lineitem
+added to a purchase order for the provider. This takes place during PO
+creation from a selection list or existing bib record and when a lineitem is
+added to an existing purchase order. If a lineitem already has copies
+attached, no default copies are added.
+
+OPAC
+~~~~
+
+Removal of JSPAC
+^^^^^^^^^^^^^^^^
+TPAC is now the default catalog in Evergreen. The default apache configuration
+now points to TPAC, staff client OPAC options now point to TPAC, and the JSPAC
+to TPAC toggle has been removed from the portal page.
+
+Display alternate graphic (880) fields
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, Evergreen displays alternate graphic fields, if any, for
+contributors (1xx / 7xx), titles (245), edition statements (250), imprints
+(260), notes (5xx), subjects (6xx), and series (4xx / 8xx) in search results and record details
+per the Library of Congress MARC21 specifications:
+
+* http://www.loc.gov/marc/bibliographic/bd880.html
+* http://www.loc.gov/marc/bibliographic/ecbdcntf.html
+* http://www.loc.gov/marc/bibliographic/ecbdmulti.html (Model A)
+
+Default display
++++++++++++++++
+In general, alternate graphic fields display below the corresponding
+primary field. One exception is the attribution summary on the record details
+page, in which the alternate graphic field contents display between the
+primary field content and the attribution statement. To support CSS
+customizations, HTML elements for the graphic fields have the class attribute
+value `graphic880`.
+
+MARC21 Feeds from OpenSearch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In addition to the already supported formats, you can now get raw MARC21 from
+OpenSearch feeds, à la:
+
+ http://<host>/opac/extras/opensearch/1.1/-/marc21?searchTerms=piano
+
+
+Options to Hide Some User Preferences
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The config.tt2 file now provides options to disable phone notification options, password changes, and e-mail address changes in TPAC. These options are useful
+for libraries that do not do phone notifications and for those that use
+centralized authentication.
+
+Note the ability to disable user name changes is already available through the
+Library Settings editor.
+
+Public Copy Notes
+^^^^^^^^^^^^^^^^^
+Public copy notes are now visible in TPAC.
+
+Search Changes
+^^^^^^^^^^^^^^
+A number of changes have been made to search to allow more control and improve
+performance. These changes and their associated configurations are global to
+the entire system and can not be configured on a per-library basis.
+
+Amongst other things the new search code fixes:
+
+* Invalid queries being generated from advanced searches
+* Some timeouts from backend code taking too long to perform a search
+* Some filters being one-use only
+* Negations not working properly where multiple indexes are involved
+
+Improvements include:
+
+* Exact matches on input should be more likely to float to the top of results
+* Non-English stemming can be used, alongside or instead of English stemming
+* Entered search terms can be found across multiple indexes
+
+Default configuration is geared towards English but is easily changed. In a
+production environment changes will likely require re-indexing, however.
+
+The upgrade script could be pre-tweaked to install desired configuration before
+it builds and/or re-builds many of the indexes.
+
+Permissions
++++++++++++
+One new permission is added for this feature:
+
+ * ADMIN_INDEX_NORMALIZER
+
+Searching for deleted records
++++++++++++++++++++++++++++++
+Evergreen now supports searching for deleted records via the '#deleted'
+QP modifier.
+
+In order to support this, sites must enable the
+'ingest.metarecord_mapping.preserve_on_delete' internal flag. It is off by
+default since the ability to search for deleted records requires keeping
+metarecord mappings around when bibs are deleted, which may not be desirable
+for the typical site.
+
+Two new QP filters: create_date and edit_date
++++++++++++++++++++++++++++++++++++++++++++++
+These filter on the fields of the same name in biblio.record_entry.
+
+e.g.
+
+ * create_date(,2013-02-01) => records created before 2013-02-01
+ * create_date(2013-02-01) => records created since 2013-02-01
+ * create_date(2013-02-01,2013-02-28) => records created in Feb 2013
+ * create_date(yesterday) => records since created yesterday
+
+Show local call number in TPAC My Lists display
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If an opac-visible call number exists that is owned by an org unit
+relevant to the patron, show the most relevant call number label
+and owning branch name in the My Lists display for each record in
+the list. Call number is displayed in both saved and temporary lists.
+
+A call number is considered relevant if its owner is one of:
+
+physical location library
+preferred library (plib, home, etc.)
+search library
+
+If no relevant call number is found, no call number is displayed.
+
+TPAC Google Books preview
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Setting `ctx.google_books_preview` to `1` in the TPAC `config.tt2`
+configuration file will cause the TPAC to check to see, as part of the record
+details view, if Google Books has an online preview available. If it does,
+then a preview button will be displayed in the book cover image location.
+If the user then clicks the preview button, the preview will load below the
+title of the book in the record details page.
+
+By default, this functionality is disabled to protect the privacy of users
+who might not want to share their browsing behavior with Google.
+
+TPAC Novelist Select Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The URL for Novelist Select integration with TPAC has changed, and so
+has the manner in which it is configured in `eg_vhost.conf.` You will
+find a section like the following in `eg_vhost.conf:`
+
+-------------------------------------------------------------------------------
+ # Novelist
+ # SetEnv OILS_NOVELIST_URL http://imageserver.ebscohost.com/novelistselect/ns2init.js
+ # SetEnv OILS_NOVELIST_PROFILE <profile>
+ # SetEnv OILS_NOVELIST_PASSWORD <password>
+-------------------------------------------------------------------------------
+
+You will want to remove the hash marks on the three lines that have
+`SetEnv` in them. You will also want to replace `<profile>` and
+`<password>` with your Novelist Select profile and password provided
+to you by EBSCO.
+
+TPAC Org Unit Hiding
+^^^^^^^^^^^^^^^^^^^^
+Adds support for the opac.org_unit_hiding.depth org unit setting to
+TPAC, which makes out-of-scope org units disappear (except when
+explicitly requested).
+
+Org unit hiding is based on the physical_loc (Physical Location) param /
+cookie, which is the closest analog to 'ol' (original location), from
+which it was based in the JSPAC.
+
+UI Changes
+++++++++++
+
+ * All search org unit selectors
+ * Holds pickup lib selector
+ * Copy summary in search results page
+ * Copy list in search results page
+ * Copy summary in record detail page (which controls the copy grid).
+ * Hold summary in record detail page
+
+Cataloging
+~~~~~~~~~~
+
+MARC Import Tag Stripping
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Administrators can configure MARC tags which are removed from MARC records
+imported via Z39.50 and the Vandelay MARC Import/Export UI (ACQ and non-ACQ).
+Tags are organized into groups. Groups can be marked as optional or required.
+For each tag, every instance of the tag (including all subfields) are removed
+from the record.
+
+MARC fields which are contained within required ('always_apply') tag groups
+are always removed from inbound records. No action is needed. Tag groups
+which are optional will appear in MARC import interfaces (see below) allowing
+staff to select which groups of tags to strip from incoming records at import
+time.
+
+Interfaces Affected
++++++++++++++++++++
+
+ * Admin UI
+ ** Admin => Server Administration => MARC Import Remove Fields
+ * Z39.50 Import
+ ** Cataloging => Import Record from Z39.50
+ ** Optional groups appear with the other import options
+ * Vandelay
+ ** Cataloging => MARC Import/Export (Vandelay)
+ ** Acquisitions => Load Order Records
+ ** Optional groups appear with the other import options
+
+Permissions
++++++++++++
+Three new permissions are added for this feature:
+
+ * CREATE_IMPORT_TRASH_FIELD
+ * UPDATE_IMPORT_TRASH_FIELD
+ * DELETE_IMPORT_TRASH_FIELD
+
+Vandelay Default Match Set
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new org unit setting to specify a default Record Match Set when
+importing MARC records through the MARC Batch Import/Export interface. It does
+not affect the default match set selected in acquisitions. If this
+is set, it will not be possible to leave the Record Match Set field blank;
+it may be necessary to define a default match set that replicates the current
+default behavior.
+
+A new "Vandelay" org unit settings group is also created.
+
+Direct access to Item Attribute Editor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can now access the item attribute editor via Admin -> Local Admin -> Item
+Attribute Editor. No copy record is loaded into the editor, but it is available to without first finding an item and loading it into the editor:
+
+ * Configure copy templates.
+ * Hide fields in the copy editor.
+
+Circulation
+~~~~~~~~~~~
+
+Clickable Patron Indicators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When retrieving a patron record, staff can now click on the indicators listed
+beneath the patron's name and launch the related tabs.
+
+For example, clicking on (See Notes) will open the associated patron's notes.
+
+"Warn patrons when their account is about to expire"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To give staff the ability to warn patrons when their account is about to
+expire, the staff client can display an alert message on the patron information
+window. A new library setting, `Warn patrons when their account is about to
+expire` in the *Circulation* section of the *Library Settings Editor*,
+determines how many days in advance of a patron's account expiry date the alert
+should be displayed. By default, warnings about upcoming patron account expiry
+dates are not displayed.
+
+Show Hold Patron Name in TPAC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When looking up patron information for hold placement via the staff client in
+TPac, the hold patron name is now shown next to the entered barcode. In the
+event that the barcode is not found, a notice is displayed and the submit
+button is disabled until a valid barcode is entered or the staff member is
+switched to.
+
+Show Holds On Bib Menu Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Add direct "Show holds on bibs" menu option from item checkin, item status,
+and patron hold interfaces. This gives staff a quicker way of viewing who
+else has holds on an item instead of having to click an option to view the
+bib record, then clicking into the menus to view holds.
+
+Administration
+~~~~~~~~~~~~~~
+
+Calculated Proximity Adjustments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Allows customization to the way that Evergreen measures the distance between
+org units for the purposes of 1) determining what copy at what org unit is best
+suited for targeting a title-level hold, and 2) determining what hold is best
+suited for fulfillment by a copy-in-hand at capture (checkin) time. The
+customization is based on a table 'actor.org_unit_proximity_adjustment', with
+certain matching criteria that the system compares to properties of the holds
+and copies in question.
+
+Permissions
++++++++++++
+One new permission is added for this feature:
+
+ * ADMIN_PROXIMITY_ADJUSTMENT
+ ** Allows staff to administer the proximity adjustments
+
+
+Custom best-hold selection sort order
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ranking algorithm that chooses the best hold to target a copy in
+hand at a capture time used to be fairly simple. It had two modes, FIFO
+and not-FIFO, and that was it.
+
+This change allows full configuration of that algorithm. In other
+words, when the system captures a copy and sets out to evaluate what
+hold, if any, that copy might best fulfill, site staff of sufficient
+permission level are now empowered to choose exactly which comparisons
+the systems makes in what order. This gives said staff much greater
+flexibility than they have today over holds policy.
+
+For more information, see the included tech spec documents.
+
+Permissions
++++++++++++
+One new permission is added for this feature:
+
+ * ADMIN_HOLD_CAPTURE_SORT
+ ** Allows staff to administer the custom best-hold selection sort order.
+
+Generic CSV Notification Generator/Receiver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+New Action/Trigger template and sample event definitions for creating a CSV
+export file for various patron actions, primarily for the purpose of creating
+patron notices via external notification mechanisms.
+
+The reference implementation for this development is the TalkingTech iTiva
+product, which consumes CSV files for generating phone/text notifications and
+produces CSV results files for informing the ILS of notification statuses.
+The template and send/receive scripts, however, should be generic enough to
+create CSV for any type of 3rd-party notification product.
+
+For more information, see the included tech spec documents.
+
+Storing Z39.50 Server Credentials
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the Z39.50 configuration interface, staff now have the option to apply
+z39.50 login credentials to each Z39.50 server at different levels of the
+org unit hierarchy (similar to org unit settings). When credentials are set
+for a Z39 server, searches against the z39 server will used the stored
+credentials, unless other credentials are provided by the caller, in which
+case the caller credentials are used.
+
+For security purposes, passwords may not be retrieved or reported on by staff.
+Staff can only apply new values for credentials or clear existing ones.
+
+URL Verification
+^^^^^^^^^^^^^^^^
+In order to support verification of URLs, Evergreen now has several new
+capabilities, and extensions to some existing features.
+
+A wizard-style interface that walks a staff member through the process of collecting records and URLs to verify, verifying and reviewing the URLs.
+
+URL validation sessions are built as a whole to support immediate and
+future review of any URLs. Each session carries a name, an owner, a set
+of record search criteria, a set of tag and subfield combinations describing
+the location of URLs to validate, a record container for tracking individual
+records to verify, and a set of state and data tables for managing the
+processing of individual URLs.
+
+A set of middle-layer methods provide the business logic required to collect
+records, extract, parse and test the validity of the URLs.
+
+For more information, see the included tech spec documents.
+
+Permissions
++++++++++++
+One new permission is added for this feature:
+
+ * URL_VERIFY
+
+Serials
+~~~~~~~
+
+Serial Control: Embed Alternate Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+As another step toward a unified interface, the serial control subscription
+editor now consists of an embedded version of the alternate control. This
+reduces duplication of both code and documentation, and smooths the eventual
+transition to a single interface.
+
+In order to not lose any essential features, the following additions were made
+to the new combination editor:
+
+* note editors on subscriptions and distributions
+* labeled dropdown for distribution summary options ("Add to record entry", "Use record entry only", etc.)
+* legacy record entry linkage setup (Allows one to tie a distribution's information to a particular serial record entry (i.e. a MFHD record))
+
+Serial Control: Set Special Statuses
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The Serial Control interface prevents direct editing of serial item statuses
+for data integrity reasons. As an alternative to direct control, the interface
+now offers new menu options for setting items to 'claimed', 'not held', and
+'not published'. Note that these statuses are still currently useful for
+reporting and display purposes only.
+
+Staff Client
+~~~~~~~~~~~~
+
+Staff client search preferences
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Staff can now set workstation-level search preferences through Admin ->
+Workstation Administration -> Set Search Preferences.
+
+ * Default Search Library sets the library that is searched by default from
+ the advanced search page and the portal page.
+ * Preferred library is used to identify copies that should display first.
+ * Advanced search default pane allows staff to set the numeric or expert
+ searches as the default search tab.
+
+The option to change the preferred search library from the search results page
+is no longer available when logged into the staff client.
+
+add "about:about" to developer menu in staff client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+about:about gives access to various XULRunner diagnostic tools.
+Useful ones include:
+
+about:buildconfig::
+ Get information about how the staff client is built.
+about:config::
+ Tweak XULRunner settings.
+about:memory::
+ Get detailed information about the memory usage of the staff
+ client.
+
+
+Miscellaneous
+-------------
+
+Loading Sample Data
+~~~~~~~~~~~~~~~~~~~
+One common need for people evaluating Evergreen, as well as for developers,
+writers, and testers, is a set of sample data that can be easily loaded into
+the Evergreen database and provide a consistent set of results for testing
+and training purposes.
+
+This release features sets of sample data consisting of:
+
+* 100 bibliographic records retrievable via a "concerto" keyword search
+* 100 French bibliographic records
+* Associated call numbers, copies, parts, and conjoined items
+* Patron accounts, including some recently expired patrons
+* Circulation transactions, including some holds and some overdue items
+
+To load the sample data into a freshly installed Evergreen database, you can
+pass the following arguments to the `eg_db_config` script (either when you are
+creating the initial database schema, or as a separate call after creating the
+database schema):
+
+* `--load-all-sample`: Loads all sample data, including bibliographic records,
+ call numbers, copies, users, and transactions.
+* `--load-concerto-sample`: Loads a subset of sample data that includes just
+ 100 bibliographic records, and associated call numbers and copies.
+++ /dev/null
-Evergreen 2.4.0 Release Notes
-=============================
-:toc:
-:numbered:
-
-Upgrade notes
--------------
-
-Custom Toolbar Permissions
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-With the addition of more granular permissions for configuring a custom
-toolbars, the ADMIN_TOOLBAR permission alone will not allow users to
-configure a custom toolbar. This permission must now be used in conjunction
-with one or more of the following permissions:
-
-* ADMIN_TOOLBAR_FOR_ORG
-* ADMIN_TOOLBAR_FOR_USER
-* ADMIN_TOOLBAR_FOR_WORKSTATION
-
-New features
-------------
-
-Acquisitions
-~~~~~~~~~~~~
-
-Acquisitions Inline Item Detail View
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Acquisitions selection lists and purchase order interfaces contain a new link
-beside each lineitem which, when clicked, creates an inline grid of copies
-linked to the lineitem. The grid contains the same information that displays
-in the full copy edit grid (from clicking on the Copies(n) link). However,
-the inline grid is read-only, so it displays much faster and does not require
-the user to change visual contexts.
-
-Included along the top of the lineitem table is a new 'Expand All' link which,
-when clicked, expands or collapses the inline grid for all visible lineitems.
-
-Acquisitions Lineitem Order Identifiers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Staff now have the ability to specify the identifier value to use for
-lineitems when communicating order information to vendors. This is
-particularly important when a lineitem has, for example, multiple ISBNs.
-Determining which ISBN is to act as the "order identifier" allows staff
-to provide the most accurate order information to vendors.
-
-Supported identifier types include ISBN, ISSN, and UPC. Order identifier
-values are relayed to vendors via EDI and print PO.
-
-Permissions
-+++++++++++++
-Two new permissions are added for this feature:
-
- * ACQ_SET_LINEITEM_IDENTIFIER
- ** Allows staff to apply order identifiers to lineitems
- * ACQ_ADD_LINEITEM_IDENTIFIER
- ** Implies that new identifiers shall be added to linked bib records,
- when a linkage exists.
-
-Acquisitions Purchase Order and other Interface Improvements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Feature Summary
-+++++++++++++++
-
-The following features, which primarily affect the user interface layer,
-improve Acquisitions work flows.
-
- * Avoid double-activation of POs
- * Disable invoice and cancel options for pending POs
- * Disable zero-copy checkbox for activated POs
- * Disable new charges for activated POs
- * Replace "Shelving Location" with Copy Location
-
- * Rearranging "actions" drop-down
- ** More consistency in actions applying to selected lineitems specifically
- ** Things moved from the per-lineitem dropdown to the main one when
- sensible.
- ** Add to PO dialog added
- ** You can no longer add lineitems to a PO if they're already on one.
- ** Actions in dropdown now enabled/disabled differently depending on
- the interface where it appears (PO vs Selection List vs Acq Search etc.)
-
- * Batch update for line items
- ** Apply updates to all copies of all selected line items at once
- ** Relies on a middle layer method that streams back information that
- would suit a more asynchronous display in the future (rather than
- simply reloading the page upon success, which it does now)
- ** For failure cases, specific information about which line item cannot
- be updated, and why, is available to the client, although taking
- best advantage of this information for user-friendly display is left
- to the future.
- * Add optional fund, circ modifier and collection code fields to distribution
- formulas.
- * The invoices interface auto-populates "# Invoiced" column with number of
- invoiceable copies, and copies the "billed cost" column to the "amount paid"
- column if the latter doesn't have anything in it yet.
-
-Acquisitions MARC Upload Form Persistence
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Adds a two-layer persistence mechanism for the acquisitions MARC file upload
-interface. A set of org unit settings now exist for managing default values
-for the interface. Additionally, for each field where no org unit setting
-value is configured, the last-used value will be persisted locally and re-
-used with subsequent loads of the interface.
-
-Default Number of Acquisitions Copies to Order
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Acquisitions providers have a new "Default # Copies" field. When the value
-is set, this number of copies will be automatically added to each lineitem
-added to a purchase order for the provider. This takes place during PO
-creation from a selection list or existing bib record and when a lineitem is
-added to an existing purchase order. If a lineitem already has copies
-attached, no default copies are added.
-
-OPAC
-~~~~
-
-Removal of JSPAC
-^^^^^^^^^^^^^^^^
-TPAC is now the default catalog in Evergreen. The default apache configuration
-now points to TPAC, staff client OPAC options now point to TPAC, and the JSPAC
-to TPAC toggle has been removed from the portal page.
-
-Display alternate graphic (880) fields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, Evergreen displays alternate graphic fields, if any, for
-contributors (1xx / 7xx), titles (245), edition statements (250), imprints
-(260), notes (5xx), subjects (6xx), and series (4xx / 8xx) in search results and record details
-per the Library of Congress MARC21 specifications:
-
-* http://www.loc.gov/marc/bibliographic/bd880.html
-* http://www.loc.gov/marc/bibliographic/ecbdcntf.html
-* http://www.loc.gov/marc/bibliographic/ecbdmulti.html (Model A)
-
-Default display
-+++++++++++++++
-In general, alternate graphic fields display below the corresponding
-primary field. One exception is the attribution summary on the record details
-page, in which the alternate graphic field contents display between the
-primary field content and the attribution statement. To support CSS
-customizations, HTML elements for the graphic fields have the class attribute
-value `graphic880`.
-
-MARC21 Feeds from OpenSearch
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In addition to the already supported formats, you can now get raw MARC21 from
-OpenSearch feeds, à la:
-
- http://<host>/opac/extras/opensearch/1.1/-/marc21?searchTerms=piano
-
-
-Options to Hide Some User Preferences
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The config.tt2 file now provides options to disable phone notification options, password changes, and e-mail address changes in TPAC. These options are useful
-for libraries that do not do phone notifications and for those that use
-centralized authentication.
-
-Note the ability to disable user name changes is already available through the
-Library Settings editor.
-
-Public Copy Notes
-^^^^^^^^^^^^^^^^^
-Public copy notes are now visible in TPAC.
-
-Search Changes
-^^^^^^^^^^^^^^
-A number of changes have been made to search to allow more control and improve
-performance. These changes and their associated configurations are global to
-the entire system and can not be configured on a per-library basis.
-
-Amongst other things the new search code fixes:
-
-* Invalid queries being generated from advanced searches
-* Some timeouts from backend code taking too long to perform a search
-* Some filters being one-use only
-* Negations not working properly where multiple indexes are involved
-
-Improvements include:
-
-* Exact matches on input should be more likely to float to the top of results
-* Non-English stemming can be used, alongside or instead of English stemming
-* Entered search terms can be found across multiple indexes
-
-Default configuration is geared towards English but is easily changed. In a
-production environment changes will likely require re-indexing, however.
-
-The upgrade script could be pre-tweaked to install desired configuration before
-it builds and/or re-builds many of the indexes.
-
-Permissions
-+++++++++++
-One new permission is added for this feature:
-
- * ADMIN_INDEX_NORMALIZER
-
-Searching for deleted records
-+++++++++++++++++++++++++++++
-Evergreen now supports searching for deleted records via the '#deleted'
-QP modifier.
-
-In order to support this, sites must enable the
-'ingest.metarecord_mapping.preserve_on_delete' internal flag. It is off by
-default since the ability to search for deleted records requires keeping
-metarecord mappings around when bibs are deleted, which may not be desirable
-for the typical site.
-
-Two new QP filters: create_date and edit_date
-+++++++++++++++++++++++++++++++++++++++++++++
-These filter on the fields of the same name in biblio.record_entry.
-
-e.g.
-
- * create_date(,2013-02-01) => records created before 2013-02-01
- * create_date(2013-02-01) => records created since 2013-02-01
- * create_date(2013-02-01,2013-02-28) => records created in Feb 2013
- * create_date(yesterday) => records since created yesterday
-
-Show local call number in TPAC My Lists display
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If an opac-visible call number exists that is owned by an org unit
-relevant to the patron, show the most relevant call number label
-and owning branch name in the My Lists display for each record in
-the list. Call number is displayed in both saved and temporary lists.
-
-A call number is considered relevant if its owner is one of:
-
-physical location library
-preferred library (plib, home, etc.)
-search library
-
-If no relevant call number is found, no call number is displayed.
-
-TPAC Google Books preview
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Setting `ctx.google_books_preview` to `1` in the TPAC `config.tt2`
-configuration file will cause the TPAC to check to see, as part of the record
-details view, if Google Books has an online preview available. If it does,
-then a preview button will be displayed in the book cover image location.
-If the user then clicks the preview button, the preview will load below the
-title of the book in the record details page.
-
-By default, this functionality is disabled to protect the privacy of users
-who might not want to share their browsing behavior with Google.
-
-TPAC Novelist Select Integration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The URL for Novelist Select integration with TPAC has changed, and so
-has the manner in which it is configured in `eg_vhost.conf.` You will
-find a section like the following in `eg_vhost.conf:`
-
--------------------------------------------------------------------------------
- # Novelist
- # SetEnv OILS_NOVELIST_URL http://imageserver.ebscohost.com/novelistselect/ns2init.js
- # SetEnv OILS_NOVELIST_PROFILE <profile>
- # SetEnv OILS_NOVELIST_PASSWORD <password>
--------------------------------------------------------------------------------
-
-You will want to remove the hash marks on the three lines that have
-`SetEnv` in them. You will also want to replace `<profile>` and
-`<password>` with your Novelist Select profile and password provided
-to you by EBSCO.
-
-TPAC Org Unit Hiding
-^^^^^^^^^^^^^^^^^^^^
-Adds support for the opac.org_unit_hiding.depth org unit setting to
-TPAC, which makes out-of-scope org units disappear (except when
-explicitly requested).
-
-Org unit hiding is based on the physical_loc (Physical Location) param /
-cookie, which is the closest analog to 'ol' (original location), from
-which it was based in the JSPAC.
-
-UI Changes
-++++++++++
-
- * All search org unit selectors
- * Holds pickup lib selector
- * Copy summary in search results page
- * Copy list in search results page
- * Copy summary in record detail page (which controls the copy grid).
- * Hold summary in record detail page
-
-Cataloging
-~~~~~~~~~~
-
-MARC Import Tag Stripping
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Administrators can configure MARC tags which are removed from MARC records
-imported via Z39.50 and the Vandelay MARC Import/Export UI (ACQ and non-ACQ).
-Tags are organized into groups. Groups can be marked as optional or required.
-For each tag, every instance of the tag (including all subfields) are removed
-from the record.
-
-MARC fields which are contained within required ('always_apply') tag groups
-are always removed from inbound records. No action is needed. Tag groups
-which are optional will appear in MARC import interfaces (see below) allowing
-staff to select which groups of tags to strip from incoming records at import
-time.
-
-Interfaces Affected
-+++++++++++++++++++
-
- * Admin UI
- ** Admin => Server Administration => MARC Import Remove Fields
- * Z39.50 Import
- ** Cataloging => Import Record from Z39.50
- ** Optional groups appear with the other import options
- * Vandelay
- ** Cataloging => MARC Import/Export (Vandelay)
- ** Acquisitions => Load Order Records
- ** Optional groups appear with the other import options
-
-Permissions
-+++++++++++
-Three new permissions are added for this feature:
-
- * CREATE_IMPORT_TRASH_FIELD
- * UPDATE_IMPORT_TRASH_FIELD
- * DELETE_IMPORT_TRASH_FIELD
-
-Vandelay Default Match Set
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new org unit setting to specify a default Record Match Set when
-importing MARC records through the MARC Batch Import/Export interface. It does
-not affect the default match set selected in acquisitions. If this
-is set, it will not be possible to leave the Record Match Set field blank;
-it may be necessary to define a default match set that replicates the current
-default behavior.
-
-A new "Vandelay" org unit settings group is also created.
-
-Direct access to Item Attribute Editor
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can now access the item attribute editor via Admin -> Local Admin -> Item
-Attribute Editor. No copy record is loaded into the editor, but it is available to without first finding an item and loading it into the editor:
-
- * Configure copy templates.
- * Hide fields in the copy editor.
-
-Circulation
-~~~~~~~~~~~
-
-Clickable Patron Indicators
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When retrieving a patron record, staff can now click on the indicators listed
-beneath the patron's name and launch the related tabs.
-
-For example, clicking on (See Notes) will open the associated patron's notes.
-
-"Warn patrons when their account is about to expire"
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To give staff the ability to warn patrons when their account is about to
-expire, the staff client can display an alert message on the patron information
-window. A new library setting, `Warn patrons when their account is about to
-expire` in the *Circulation* section of the *Library Settings Editor*,
-determines how many days in advance of a patron's account expiry date the alert
-should be displayed. By default, warnings about upcoming patron account expiry
-dates are not displayed.
-
-Show Hold Patron Name in TPAC
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When looking up patron information for hold placement via the staff client in
-TPac, the hold patron name is now shown next to the entered barcode. In the
-event that the barcode is not found, a notice is displayed and the submit
-button is disabled until a valid barcode is entered or the staff member is
-switched to.
-
-Show Holds On Bib Menu Option
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Add direct "Show holds on bibs" menu option from item checkin, item status,
-and patron hold interfaces. This gives staff a quicker way of viewing who
-else has holds on an item instead of having to click an option to view the
-bib record, then clicking into the menus to view holds.
-
-Administration
-~~~~~~~~~~~~~~
-
-Calculated Proximity Adjustments
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Allows customization to the way that Evergreen measures the distance between
-org units for the purposes of 1) determining what copy at what org unit is best
-suited for targeting a title-level hold, and 2) determining what hold is best
-suited for fulfillment by a copy-in-hand at capture (checkin) time. The
-customization is based on a table 'actor.org_unit_proximity_adjustment', with
-certain matching criteria that the system compares to properties of the holds
-and copies in question.
-
-Permissions
-+++++++++++
-One new permission is added for this feature:
-
- * ADMIN_PROXIMITY_ADJUSTMENT
- ** Allows staff to administer the proximity adjustments
-
-
-Custom best-hold selection sort order
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ranking algorithm that chooses the best hold to target a copy in
-hand at a capture time used to be fairly simple. It had two modes, FIFO
-and not-FIFO, and that was it.
-
-This change allows full configuration of that algorithm. In other
-words, when the system captures a copy and sets out to evaluate what
-hold, if any, that copy might best fulfill, site staff of sufficient
-permission level are now empowered to choose exactly which comparisons
-the systems makes in what order. This gives said staff much greater
-flexibility than they have today over holds policy.
-
-For more information, see the included tech spec documents.
-
-Permissions
-+++++++++++
-One new permission is added for this feature:
-
- * ADMIN_HOLD_CAPTURE_SORT
- ** Allows staff to administer the custom best-hold selection sort order.
-
-Generic CSV Notification Generator/Receiver
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-New Action/Trigger template and sample event definitions for creating a CSV
-export file for various patron actions, primarily for the purpose of creating
-patron notices via external notification mechanisms.
-
-The reference implementation for this development is the TalkingTech iTiva
-product, which consumes CSV files for generating phone/text notifications and
-produces CSV results files for informing the ILS of notification statuses.
-The template and send/receive scripts, however, should be generic enough to
-create CSV for any type of 3rd-party notification product.
-
-For more information, see the included tech spec documents.
-
-Storing Z39.50 Server Credentials
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In the Z39.50 configuration interface, staff now have the option to apply
-z39.50 login credentials to each Z39.50 server at different levels of the
-org unit hierarchy (similar to org unit settings). When credentials are set
-for a Z39 server, searches against the z39 server will used the stored
-credentials, unless other credentials are provided by the caller, in which
-case the caller credentials are used.
-
-For security purposes, passwords may not be retrieved or reported on by staff.
-Staff can only apply new values for credentials or clear existing ones.
-
-URL Verification
-^^^^^^^^^^^^^^^^
-In order to support verification of URLs, Evergreen now has several new
-capabilities, and extensions to some existing features.
-
-A wizard-style interface that walks a staff member through the process of collecting records and URLs to verify, verifying and reviewing the URLs.
-
-URL validation sessions are built as a whole to support immediate and
-future review of any URLs. Each session carries a name, an owner, a set
-of record search criteria, a set of tag and subfield combinations describing
-the location of URLs to validate, a record container for tracking individual
-records to verify, and a set of state and data tables for managing the
-processing of individual URLs.
-
-A set of middle-layer methods provide the business logic required to collect
-records, extract, parse and test the validity of the URLs.
-
-For more information, see the included tech spec documents.
-
-Permissions
-+++++++++++
-One new permission is added for this feature:
-
- * URL_VERIFY
-
-Serials
-~~~~~~~
-
-Serial Control: Embed Alternate Interfaces
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-As another step toward a unified interface, the serial control subscription
-editor now consists of an embedded version of the alternate control. This
-reduces duplication of both code and documentation, and smooths the eventual
-transition to a single interface.
-
-In order to not lose any essential features, the following additions were made
-to the new combination editor:
-
-* note editors on subscriptions and distributions
-* labeled dropdown for distribution summary options ("Add to record entry", "Use record entry only", etc.)
-* legacy record entry linkage setup (Allows one to tie a distribution's information to a particular serial record entry (i.e. a MFHD record))
-
-Serial Control: Set Special Statuses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Serial Control interface prevents direct editing of serial item statuses
-for data integrity reasons. As an alternative to direct control, the interface
-now offers new menu options for setting items to 'claimed', 'not held', and
-'not published'. Note that these statuses are still currently useful for
-reporting and display purposes only.
-
-Staff Client
-~~~~~~~~~~~~
-
-Staff client search preferences
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Staff can now set workstation-level search preferences through Admin ->
-Workstation Administration -> Set Search Preferences.
-
- * Default Search Library sets the library that is searched by default from
- the advanced search page and the portal page.
- * Preferred library is used to identify copies that should display first.
- * Advanced search default pane allows staff to set the numeric or expert
- searches as the default search tab.
-
-The option to change the preferred search library from the search results page
-is no longer available when logged into the staff client.
-
-add "about:about" to developer menu in staff client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-about:about gives access to various XULRunner diagnostic tools.
-Useful ones include:
-
-about:buildconfig::
- Get information about how the staff client is built.
-about:config::
- Tweak XULRunner settings.
-about:memory::
- Get detailed information about the memory usage of the staff
- client.
-
-
-Miscellaneous
--------------
-
-Loading Sample Data
-~~~~~~~~~~~~~~~~~~~
-One common need for people evaluating Evergreen, as well as for developers,
-writers, and testers, is a set of sample data that can be easily loaded into
-the Evergreen database and provide a consistent set of results for testing
-and training purposes.
-
-This release features sets of sample data consisting of:
-
-* 100 bibliographic records retrievable via a "concerto" keyword search
-* 100 French bibliographic records
-* Associated call numbers, copies, parts, and conjoined items
-* Patron accounts, including some recently expired patrons
-* Circulation transactions, including some holds and some overdue items
-
-To load the sample data into a freshly installed Evergreen database, you can
-pass the following arguments to the `eg_db_config` script (either when you are
-creating the initial database schema, or as a separate call after creating the
-database schema):
-
-* `--load-all-sample`: Loads all sample data, including bibliographic records,
- call numbers, copies, users, and transactions.
-* `--load-concerto-sample`: Loads a subset of sample data that includes just
- 100 bibliographic records, and associated call numbers and copies.
--- /dev/null
+Evergreen 2.5 Release Notes
+===========================
+:toc:
+:numbered:
+
+Upgrade Notes
+-------------
+
+Circulation
+~~~~~~~~~~~
+
+Long Overdue Circulations Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If you are using a custom version of the
+'/openils/conf/action_trigger_filters.json.example' file, you will need to
+merge the changes made by this feature into your file. The change in
+question alters the 'checkout.due' hook such that LONGOVERDUE circulations
+are no longer treated as regular overdue items.
+
+OPAC
+~~~~
+
+Web-Based Patron Self-Registration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * If a value is set for the _Patron Self-Reg Expire Interval_
+ (opac.pending_user_expire_interval) for any org units, the new
+ /openils/bin/purge_pending_users.srfsh script should also be added to the
+ opensrf user's crontab. Running the script once per day should suffice.
+
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+Log Redaction Config Change
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The previous log protect redaction instructions missed a method used
+by the patron initiated password reset system. In order to fill this
+gap, you need to find the <log_protect> portion of your
+opensrf_core.xml file and add the following line:
+
+ <match_string>open-ils.actor.patron.password_reset.commit</match_string>
+
+You should see a number of similar lines already there in between
+<log_protect> and </log_protect>.
+
+Server Add-ons
+^^^^^^^^^^^^^^
+This adds a "Server Add-ons" menu entry under Admin -> Workstation
+Administration in the staff client. Choosing this allows you to edit or set a
+list of identifiers that correspond to JSAN-style modules found in
+/server/addons/, and is meant mainly for activating 3rd party modules within the
+staff client on a per-workstation basis. You need the
+ADMIN_SERVER_ADDON_FOR_WORKSTATION permission to use it.
+
+Configuration options for activated add-ons may also show up in this interface.
+
+
+
+
+New Features
+------------
+
+
+Acquisitions
+~~~~~~~~~~~~
+
+
+
+Support PO activation without requiring items
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new _Activate PO Without Loading Items_ option in the PO allows staff to
+activate the PO without loading copies into the catalog.
+
+
+
+
+Differentiate between cancelled and "delayed" lineitems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In the ACQ user interface, it is now more clear to users when a lineitem has
+been fully cancelled or if it has been cancelled temporarily (e.g.
+back-ordered).
+
+When a lineitem is cancelled, but "keep_debits" is true on the cancel reason,
+the lineitem is in effect delayed instead of truly cancelled. This is now
+more obvious in the interface with different row styling for cancelled vs
+delayed lineitems. We also always show the lineitem cancel reason (label)
+next to the non-title attributes in the lineitem list display.
+
+
+
+
+Opportunistic Acquisitions In-Process Copy Overlay
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Improves existing acquisitions copy overlay code (which matches and overlays
+using specified IDs) by adding broader matching criteria. By selecting the new
+option, _Auto Overlay In-process Acquisitions Copies_, the system will
+potentially overlay copies which:
+
+* 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_.
+
+
+
+
+
+
+Printing PO Names on Purchase Orders
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The _Print Purchase Order_ option now prints the PO Name in addition to the PO
+ID.
+
+
+
+
+Administration
+~~~~~~~~~~~~~~
+
+
+
+Default filter option for configuration screens
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, most admin configuration screens in the staff client will now
+include filters allowing staff to display just those items matching a certain
+criteria.
+
+
+
+
+Upgrade Notes : IDL2js Locale Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following Apache configuration changes are required to support the
+locale-aware IDL2js module.
+
+// note: there's no Apache conf highlighting. 'bash' works well enough.
+[source, bash]
+-----------------------------------------------------------------
+# file: eg_vhost.conf
+
+# this is the new part
+# capture locale CGI param for /reports/fm_IDL.xml
+RewriteCond %{REQUEST_URI} ^/reports/fm_IDL.xml
+RewriteCond %{QUERY_STRING} locale=([^&;]*)
+RewriteRule . - [E=locale:%1]
+
+# it should be placed just above this existing config section
+<LocationMatch /reports/fm_IDL.xml>
+ IDLChunkStripPI "yes"
+ IDLChunkEscapeScript "no"
+ IDLChunkStripComments "yes"
+ IDLChunkStripDoctype "yes"
+ IDLChunkContentType "application/xml; charset=utf-8"
+ AddOutputFilter INCLUDES;IDLCHUNK .xml
+</LocationMatch>
+-----------------------------------------------------------------
+
+Inter-authority linking script
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adds a script called authority_authority_linker.pl in support-scripts that,
+when run, will link authority reference headings to authority records that
+contain the same main entry using a subfield 0. This causes triggers to fill
+up the authority-authority linking table and allows more information to appear
+in the bib/authority browse when a displayed heading comes from an authority
+record that has linked _See Also_ references.
+
+
+
+
+New Updates Tools
+^^^^^^^^^^^^^^^^^
+
+Source code for tools to generate the staff clients updates tools were
+added to Open-ILS/xul/staff_client/external/libmar. These tools
+replace the downloadable tools from Mozilla.org that were previously
+used to generate the staff client updates files.
+
+They come with their own configuration script and are configured
+automatically as a subpackage when you configure Evergreen for
+installation. They are also built and ready for use when you make
+Evergreen during the installation or upgrade process.
+
+The make_updates.sh script that is run when you tell Evergreen to make
+the staff client updates has been modified to use the new tools.
+
+These tools introduce a dependency on libbz2. This is often only
+available when installing the libbz2-dev or libbz2-devel packages.
+Thus this branch introduces a new dependency on the development packages
+for libbz2 in Evergreen.
+
+Nothing in the user facing behavior of building updates changes with
+these tools. They are drop-in replacements for the previous tools and
+other than the new dependency on libbz2, you don't even need to know
+that they are there.
+
+These tools were added to Evergreen to be an aid in portability to
+operating systems other than Linux. They also remove a dependency on
+a third-party tool, that is typically downloaded as a binary.
+
+
+
+Phonelist.pm Module
+^^^^^^^^^^^^^^^^^^^
+
+PhoneList.pm is a mod_perl module for Apache that works with Evergreen
+to generate callings lists for patron holds. 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.
+
+.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.
+
+
+
+
+"Purge Holds"
+^^^^^^^^^^^^^
+Similar to purging circulations one may wish to purge old (filled or canceled) hold information. This feature adds a database function and settings for doing so.
+
+Purged holds are moved to the action.aged_hold_request table with patron identifying information scrubbed, much like circulations are moved to action.aged_circulation.
+
+The settings allow for a default retention age as well as distinct retention
+ages for holds filled, holds canceled, and holds canceled by specific cancel
+causes. The most specific one wins unless a patron is retaining their hold history. In the latter case the patron's holds are retained either way.
+
+Note that the function still needs to be called, which could be set up as a cron job or done more manually, say after statistics collection. A new script, purge_holds.srfsh, is added that can be used to purge holds from cron.
+
+
+
+
+Action Trigger Event Repeatability
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Action Trigger Event Definitions have a new field, "Event Repeatability
+Delay". This feature allows events to be repeated after the designated
+delay interval. An example of this is sending a notification email when a
+patron's library card expires. If the library extends the expiration date
+on that card, we then need a way to send another notification email when
+that same card expires again. Before, the Action Trigger processor only
+created a new event if the event definition for that target had never
+been run before. But now it allows repeating of the event after the delay
+interval, if present.
+
+
+
+
+Cataloging
+~~~~~~~~~~
+
+
+Vandelay Item Import Defaults
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Via the Library Settings Editor (Org Unit Settings), support auto-generation of
+call numbers and barcodes for items imported via the staff client's MARC Batch
+Import interface (a.k.a. Vandelay). Support settings for applying a local
+prefix string to auto-generated call numbers and barcodes. For both, the
+prefix defaults to "VAN".
+
+Similarly, support default copy location and circ modifiers.
+
+New Library Settings
++++++++++++++++++++++
+
+ * Vandelay Generate Default Barcodes (vandelay.item.barcode.auto)
+ * Vandelay Default Barcode Prefix (vandelay.item.barcode.prefix)
+ * Vandelay General Default Call Numbers (vandelay.item.call_number.auto)
+ * Vandelay Default Call Number Prefix (vandelay.item.call_number.prefix)
+ * Vandelay Default Copy Location (vandelay.item.copy_location.default)
+ * Vandelay Default Circulation Modifier (vandelay.item.circ_modifier.default)
+
+Z39.50 Batch Search and Queue
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Staff Work Flow
++++++++++++++++
+
+ * Staff add records to bib record buckets
+ * Staff select the new "Locate Z39.50 Matches" action for a selected bucket.
+ * Staff choose which Z39.50 sources and indexes to search and the destination
+ queue.
+ * Submitting the search fires a series of parallel Z39.50 searches across
+ all selected Z39.50 sources.
+ * Matches are added to the selected (Vandelay) queue.
+ * Matched records may be manually or automatically overlaid to existing
+ catalog records using the existing Vandelay import/merge/overlay features.
+
+Vandelay Limit to Bucket
+++++++++++++++++++++++++
+
+As a side effect of this feature, Vandelay now has a new option in the
+interface which allows staff to limit which catalog records to which an
+inbound record matches to bib records within a record bucket. When a record
+bucket and match set are chosen, only the records in the bucket can act as
+merge/overlay targets for the inbound Vandelay records.
+
+Server Admin Settings
++++++++++++++++++++++
+
+_Z39.50 Index Field Maps_ can be used to map bib record
+indexes (Metabib Fields and Record Attributes) to Z39.50
+search attributes. The purpose of the mapping is to allow the server to
+determine which values to use for the automated Z39.50 searches. For example,
+if the Z39.50 "title" attribute is mapped to the "Uniform Title" Metabib Field,
+the extracted value for "Uniform Title" for each record in the bucket will be
+used as the "title" value in the Z39.50 search.
+
+Mappings can be applied to specific Z39.50 attributes, which define an attribute
+type and a Z39.50 source, or to generic attribute types (e.g. "title"). When
+a specific attribute is used, the mapping will only be applied to searches
+directed at the Z39.50 source linked to the attribute.
+
+The management interface can be found in the staff client under
+
+Admin => Server Administration => Z39.50 Index Field Maps
+
+Metabib Field Additions
++++++++++++++++++++++++
+
+Stock config.metabib_field entries for author include additional author-
+related data, like dates. For example, a value for Personal Author might
+look like this:
+
+'girdlestone cuthbert morton 1895 1975 creator'
+
+In the context of searching Z39.50 servers, the extraneous data can be
+detrimental. Creating a separate field definition without the extra data
+is recommended.
+
+[source,sql]
+--------------------------------------------
+INSERT INTO config.metabib_field
+ (field_class, name, label, format, xpath, search_field)
+ VALUES (
+ 'author',
+ 'personal - trimmed',
+ 'Personal Author (trimmed)',
+ 'mods32',
+ '//mods32:mods/mods32:name[@type=''personal'' and mods32:role/mods32:roleTerm[text()=''creator'']]/mods32:namePart[not (@type)]',
+ FALSE
+ );
+
+-- FULL BIB (OR INDEX-TARGETED) RE-INGEST REQUIRED
+--------------------------------------------
+
+
+Library Settings
++++++++++++++++++
+
+ * Maximum Parallel Z39.50 Batch Searches (cat.z3950.batch.max_parallel)
+ ** The maximum number of Z39.50 searches that can be in-flight at any given
+ time when performing batch Z39.50 searches
+ * Maximum Z39.50 Batch Search Results (cat.z3950.batch.max_results)
+ ** The maximum number of search results to retrieve and queue for each
+ record + Z39 source during batch Z39.50 searches
+
+
+
+Circulation
+~~~~~~~~~~~
+
+Patron barcode regex for patron registration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new library setting is available to set a barcode regex to be checked during
+patron registration.
+
+Setting for Desk Renewal to use original circulating library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new global flag option has been added to allow the circulating library of
+a desk renewal (a.k.a. a renewal using the staff client) to reuse the original
+circulation library for circ rule behaviors rather than using the workstation.
+This new setting is similar to existing options to use the originating
+circulation library in OPAC renewals.
+
+Library Setting to Disable Patron Credit
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new library setting is available to disable patron credit payments in the
+billing interface. When enabled, the setting will:
+
+* Disallow patron_credit payments in the payment API.
+* Hide all of the patron credit payment actions in the staff client patron
+payment interface.
+
+Option to Disallow Use of a Branch as a Pickup Library for Holds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new library setting is available to remove a branch from consideration as a
+hold pickup library. This setting only affects the OPAC pickup library selector
+and does not otherwise affect the display of the branch in the OPAC. It also
+has no effect on hold targeting / capturing.
+
+
+
+Floating Groups
+^^^^^^^^^^^^^^^
+
+In previous versions of Evergreen, floating group copies could float or not. If they floated, then they floated everywhere with no restrictions.
+
+This enhancement provides an interface to define where a copy will float by assigning it to a floating group.
+
+Long Overdue Circulations Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is a two-part feature, which covers marking circulations as long
+overdue via automated processing and check-in of long overdue circulations.
+
+Marking Circulations Long Overdue
++++++++++++++++++++++++++++++++++
+
+A new Action/Trigger reactor (MarkItemLongOverdue) and sample event
+definition (6 Month Overdue Mark Long-Overdue) are included for
+marking circulations and their associated copies as long overdue. New Library
+Settings (Org Unit Settings) determine whether the item price and/or a
+processing fee is applied.
+
+A secondary Action/Trigger hook (longoverdue.auto) and sample event
+definition (6 Month Long Overdue Notice) are added so that (email, etc.)
+notifications can be sent when a circulation is marked long overdue via
+this new automated process.
+
+Also included is a new Action/Trigger validator PatronNotInCollections, which
+can be used to prevent long overdue processing (or any circ-based event
+definition) for patrons that are in collections processing at (or above) the
+circulating library.
+
+Check-in of Long Overdue Circulations
++++++++++++++++++++++++++++++++++++++
+
+Check-in of long overdue items may result in any of the following actions,
+depending on configuration.
+
+ * Void the copy price billing
+ * Void the long-overdue processing fee billing
+ * Reinstate voided overdue fines
+
+The process is practically identical to Lost processing. However, one
+difference between Lost and Long Overdue check-in is that the window
+of time during which a long overdue item may be returned may be based on the
+due date (like Lost) or the last billing activity date (last payment, last
+billing). This is controlled with the "Long-Overdue Check-In Interval Uses
+Last Activity Date" Library Setting.
+
+New Library Settings
+++++++++++++++++++++
+
+ * Long-Overdue Materials Processing Fee
+ * Void Overdue Fines When Items are Marked Long-Overdue
+ * Leave transaction open when long overdue balance equals zero
+ * Long-Overdue Items Usable on Checkin
+ * Long-Overdue Max Return Interval
+ * Restore Overdues on Long-Overdue Item Return
+ * Void Long-Overdue Item Billing When Returned
+ * Void Processing Fee on Long-Overdue Item Return
+ * Long-Overdue Check-In Interval Uses Last Activity Date
+
+A combination of 'Charge lost on zero' and 'Default Item Price' are used to
+determine the amount to charge for the item price when a circulation is
+marked as long overdue.
+
+New Billing Types
++++++++++++++++++
+
+ * Long-Overdue Materials
+ * Long-Overdue Materials Processing Fee
+
+New Permissions
++++++++++++++++
+
+ * SET_CIRC_LONG_OVERDUE
+ * COPY_STATUS_LONGOVERDUE.override
+
+New Copy Status
++++++++++++++++
+
+ * Long Overdue
+
+
+
+
+Patron blocking by lost items and include lost as items out
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This feature has two main parts, both of which are to improve the staff's
+ability to assist patrons in regards to lost items.
+
+* Patron blocking by lost items. This will add a group penalty threshold
+that will alert staff when a patron has too many lost items. This
+setting is modified through the Group Penalty Thresholds page.
+
+* Include lost items as items out. Through a new Library Setting,
+'Include Lost circulations in lump sum tallies in Patron Display',
+the staff have the ability to determine if lost items will be included
+in items out.
+
+
+Long-Overdue Patron Standing Penalty
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the long-overdue version of the existing PATRON_EXCEEDS_LOST_COUNT
+standing penalty. When a patron exceeds the configured threshold for open
+long-overdue (i.e. non-zero balance) circulations, the penalty is applied.
+When the number once again goes below the threshold, the penalty is removed.
+
+The penalty name is PATRON_EXCEEDS_LONGOVERDUE_COUNT / "Patron Exceeds Max
+Long-Overdue Threshold"
+
+
+Per-Hold Behind Desk Setting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The value for behind-the-desk pickup is now stored directly on each
+hold request. This allows the system to better track the true location
+of captured hold items in cases where the patron setting has changed since
+hold capture.
+
+For these features to be accessible, the "Behind Desk Pickup Supported"
+(circ.holds.behind_desk_pickup_supported) Library Setting must be set
+to true.
+
+Staff Client
+++++++++++++
+
+In addition to the counts of ready for pickup and available holds, the
+staff client now also displays the number of behind-the-desk-holds ready
+for pickup at the staff's working location. If no items are held behind
+the desk, this information does not display, in particular, because this
+information is useless if behind the desk holds are not supported at the
+staff's working location.
+
+TPAC Changes
+++++++++++++
+
+The system also allows patrons to set their own behind-the-desk
+pickup preferences in the TPAC settings interface. To activate this
+feature, admins need to set the Opac Visible flag to "true" for the
+"Hold is behind Circ Desk" (circ.holds_behind_desk) user setting and
+"Behind Desk Pickup Supported" must be set to true for the patron's
+home library.
+
+Print Single Item Receipt
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This feature adds the ability to print a receipt for just a single selected
+item from the patron interface for Items Out or Lost, Claims Returned, Long
+Overdue, Has Unpaid Billings. This can be used via right-click or using the
+'Actions for Selected Items' button.
+
+More User Name Fields Available for Simplified Hold Pull List
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+More User Name fields are available for display in the simplified hold pull
+list interface including:
+
+* First Given Name
+* Second Given Name
+* Family Name
+* Prefix
+* Suffix
+* User Alias or First Given Name
+* User Alias or Display Name
+* User Alias
+
+
+
+
+Changes to Self-Check Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following improvements were made to the self-check interface:
+
+* Convert action links to buttons for increased clarity
+* Convert dashed fieldsets to gradient backed bubbles for depth
+* Color line-item table headers to distinguish from actual line-items
+* Color logo background for increased contrast
+* Larger input box
+* Background on prompts to distinguish from logo background
+
+
+
+
+Different Styles for Long Overdue Lost Items in Billing Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Lost or Long Overdue circulations that have not yet been returned will appear
+in the patron's list of billed transactions styled differently from other
+not-yet-returned items.
+
+The interface will also display a helpful message to staff indicating what
+colors map to what types of circulations.
+
+The default colors are maroon for Lost items and orange for Long Overdue items.
+
+To change the colors, modify circ.css. To change the language for the hint,
+modify lang.dtd.
+
+Checkout: Trim whitespace from beginning and end of barcode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In checkout, when pasting a barcode into the lookup field, one may accidentally
+include spaces or tabs in the beginning or end of the barcode string. Trim
+those away to avoid potential mis-scans.
+
+Wrong-Shelf Holds in Clearable Shelf-Expired Holds List
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following changes were made to the _Browse Holds Shelf_ interface:
+
+. Change the staff client _View Shelf-Expired Holds_ action label to _View
+Clearable Holds_.
+. When _View Clearable Holds_ is selected, show wrong-shelf holds in addition
+to shelf-expired and canceled holds.
+
+Client
+~~~~~~
+
+
+Customize Items Out Display for Lost, etc.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Items which are LOST, LONGOVERDUE, or CLAIMSRETURNED may now be displayed
+in the top/main list of circulations instead of the bottom list in the
+staff client patron Items Out interface. Similarly, such items can be
+removed from the display once the items are checked in even if the
+transaction is still open (fines are owed, etc.).
+
+Apart from organization, this has two additional effects:
+
+ * If all 3 types are hidden once checked in, the interface becomes a true
+ items out interface, instead of a combination of items out and
+ special circumstance checked-in circs.
+ * If, in addition, all types are configured to be displayed in the top
+ list, the bottom list is hidden from the UI (since nothing would display
+ there), which creates more screen space for the main items out list.
+
+New Library Settings
++++++++++++++++++++++
+
+ * Items Out Long-Overdue display setting (ui.circ.items_out.longoverdue)
+ * Items Out Lost display setting (ui.circ.items_out.lost)
+ * Items Out Claims Returned display setting (ui.circ.items_out.claimsreturned)
+
+The value for each 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, regardless of the state of
+the transaction.
+
+ * 1 = top list, then bottom list
+ * 2 = bottom list, then bottom list
+ * 5 = top list, then do not display
+ * 6 = bottom list, then do not display
+
+Hint: to hide the bottom list entirely, set the value for all three settings
+to '5'.
+
+
+
+Adjustable font size in the staff client catalog
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When using the staff client, the font size in the catalog can now be
+increased/decreased by using the CTRL key with + (to increase), with - (to
+decrease), and with 0 (to restore default font size). Font sizes can persist
+via a setting in user preferences.
+
+Standalone Mode Shortcut
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Evergreen installer now includes a shortcut that launches the staff client
+directly into standalone (offline) mode.
+
+
+
+
+User Setting Defaults
+^^^^^^^^^^^^^^^^^^^^^
+
+For use during Patron Registration, we can now supply default values for User
+Settings, under _Admin_ -> _Server Administration_ -> _User Setting Types_.
+
+OPAC
+~~~~
+
+Added Content by Record ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Traditionally, Evergreen has supported Added Content lookups by ISBN
+only, or (more recently) by one of ISBN or UPC.
+
+This enhancement adds support for Added Content lookups by record
+ID, while still supporting the previous URL format for lookups by
+ISBN.
+
+The JSPAC and TPAC skins, as well as the web-based Self Checkout
+interface templates are updated to use jacket images / cover art by
+record ID by default.
+
+By using record identifiers, the Added Content handler has the
+opportunity to examine additional identifiers in the bib record.
+Currently, these include:
+
+ * ISBN
+ * UPC
+ * ISSN
+
+Currently, only the OpenILS::WWW::AddedContent::Syndetic provider
+makes use of the new identifiers.
+
+
+Local Content Overrides
++++++++++++++++++++++++
+Just as with ISBN lookups, there is support for local overrides in
+the form of a file created on disk which short-circuits any external
+Added Content lookup.
+
+
+Apache Configuration
+++++++++++++++++++++
+
+The example Apache configs have been updated to support serving
+blank.png when added content jacket URLs return a 404. This prevents
+"broken image" placeholders in browsers, without requiring a
+Javascript onerror handler on each img tag.
+
+The changes are as follows:
+
+In the eg.conf VirtualHost declaration for SSL, add:
+
+[source,conf]
+SSLProxyEngine on # required for ErrorDocument 404 on SSL connections
+
+In the eg_vhost.conf file, add:
+
+[source,conf]
+<Location /opac/extras/ac/jacket>
+ ErrorDocument 404 /opac/images/blank.png
+</Location>
+
+
+Bib record browser with linked authorities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This feature provides a patron-oriented OPAC interface for browsing
+bibliographic records.
+
+Users choose to browse by Author, Title, Subject, or Series. They then
+enter a browse term, and the nearest match from a left-anchored search
+on the headings extracted for browse purposes will be displayed in a
+typical backwards/forwards paging display. Headings link to search
+results pages showing the related records. If the browse heading is
+linked to any authority records, and if any *other* authority records
+point to those with "See also" or other non-main entry headings, those
+alternative headings are displayed linked to a search results page
+showing related bib records related to the alternate heading.
+
+The counts of holdings displayed next to headings from bibliographic
+records are subject to the same visibility tests as search. This means
+that the org unit (and copy location group) dropdown on the browse
+interface affects counts, and it further means that whether or not
+you're looking at the browse interface through the staff client makes a
+difference.
+
+Configuration considerations for site administrators
+++++++++++++++++++++++++++++++++++++++++++++++++++++
+There are two off-by-default features that site administrators may wish
+to enable.
+
+ * Quick paging links: By adding a value for the Library Setting
+ _Paging shortcut links for OPAC Browse_ (opac.browse.pager_shortcuts), you
+ can make shortcut browsing links such as ''0-9 A B C D ...'' appear
+ between the Back and Next buttons on the browse page. The set of shortcuts
+ should be chosen based on the languages in use at your site, but a
+ reasonable value for English might be the string
+ "*0-9*ABCDEFGHIJKLMNOPQRSTUVWXYZ", which will yield a link for 0-9 and one
+ for each letter A-Z. The use of asterisks in the string group a shortcut
+ whose label is more than a single letter in length. Such longer shortcuts
+ have the multi-character string for the shortcut label, and the link just
+ goes to the first heading matching the first character of the label. The
+ letters not enclosed in asterisks just lead to individual letter shortcuts.
+
+ * There is a global flag by the name _Map of search classes to regular
+ expressions to warn user about leading articles_
+ (opac.browse.warnable_regexp_per_class) to control what leading
+ articles in users' entered browse terms trigger a warning about how
+ it might be better to search for "Rolling Stones" instead of "The
+ Rolling Stones" (or whatever). This is off by default, but can be
+ enabled if it suits your catalog, and can even be customized per
+ search class (author, title, series, subject).
+
+ * Also, by default, authors are indexed for browse in such a way that
+ relator roles like "creator" are dropped off the end of their headings.
+ This was an aesthetic choice. If a site wanted to display those kinds
+ of terms, they would update the 'config.metabib_field' table in
+ the database, setting 'browse_xpath' to NULL where 'field_class' =
+ ''author'' and 'browse_field' is true.
+
+
+Authority-enhanced bibliographic browse
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Evergreen OPAC includes functionality for browsing by bibliographic terms,
+and, where those terms are controlled by authority records, for linking directly
+to the records that use other authority controlled terms that are appropriately
+linked to the browse-exposed term. In this way, one can browse authors for
+"King, Stephen" and, when appropriate and correct cataloging has been performed,
+be presented with a browse link within the author browse list to that brings the
+user to a "Bachman, Richard" entry, assuming visible bibliographic records are
+indeed attached to both records. Likewise, when browsing for "Bachman,
+Richard", users will be presented with a browse link leading to the "King,
+Stephen" browse location.
+
+Additionally, any unused but inter-authority-linked terms will appear in the
+browse list if the linked heading is in use by bibliographic records. In this
+way, browsing for "Bachman, Richard" will lead the user to "King, Stephen" even
+if no bibliographic records make use of the "Bachman, Richard" heading.
+
+Linked authority records will not be exposed if neither is in use by visible
+bibliographic records. This means that the feature will not lead to dead-end
+searches, but also means that this is not a complete authority browsing tool
+acceptable for use as such by a cataloger. See the Manage Authorities interface
+exposed through the Staff Client for that functionality.
+
+
+Support for Conjoined Items
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The catalog now supports the display of conjoined items. The "joined" titles
+will display a copy record with a link in the copy table back to the "master"
+bib. The master bib will display a set of links to individual titles.
+
+
+Shelving Location Filter
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Filtering by shelving location is now available from the Advanced Search screen.
+
+Linked library names in copy details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A patron may find one or more available copies of an item that they want to
+retrieve, but may not be familiar with the location, hours of operation, or
+contact information for each branch of their local library system. To enable
+the patron to quickly access information about a given library branch, the TPAC
+and KPAC can link the name of the branch in the copy details display to a URL
+associated with that branch.
+
+To set the URL for a given branch, use the *Local Administration -> Library
+Settings Editor* and edit the *Library Information URL* setting for that
+branch. Any branches that do not have a library information URL setting display
+as normal text.
+
+Ability to set search context by shortname
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When searching in the catalog, sites are able to set the search location by
+embedding a locg parameter in the URL. With this new features, sites will be
+able to use a branch's shortname to set the search locations whereas
+previously, sites could only use an org unit id. This parameter is case
+insensitive.
+
+OPAC Maintenance Message
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sites can now set a maintenance message to display in the catalog by setting
+the ctx.maintenance_message variable in config.tt2.
+
+My List Enhancements
+^^^^^^^^^^^^^^^^^^^^
+
+The _My Lists_ feature has the following enhancements:
+
+* Improvement on current navigation for _My Lists_ by displaying a page number
+and allowing for navigation by page number;
+* Addition of pagination for items in a list;
+* Addition of _My Lists Preferences_ tab in _Account Preferences_ where users
+can identify the number of lists and the number of list items that should
+display in each page;
+* A prompt now displays when users select the _Delete List_ button confirming
+that they really want to delete the list.
+
+
+
+Web-Based Patron Self-Registration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Feature Summary
++++++++++++++++
+
+Patrons may now fill out a web-based form from within the TPAC to create
+pending user accounts. The goal is to make the registration process more
+efficient by allowing the patron to provide much of the registration
+details in advance of registering with staff.
+
+Pending user accounts have no privileges.
+
+The form supports hiding fields, requiring fields, applying format
+validation, and displaying example text for selected fields by inspecting the
+relevant patron registration Library Settings.
+
+The "Request Library Card" link appears as the second default "bottom link"
+in the TPAC.
+
+If a user is logged in when clicking the register link, the logged-in
+user will be tracked as the requesting user for the pending account.
+Additionally, the home org unit and some address fields will be pre-populated
+for convenience (with the assumption that these will likely be the same for
+the pending user -- they can, of course, be changed). When a requesting user
+is present on the pending user, a link to the requesting user will be
+displayed within the patron registration form in the staff client.
+
+Pending patron accounts which sit unattended in the database for too long
+are purged via a regularly running (CRON) script.
+
+Technical Details
++++++++++++++++++
+
+ * To activate the web form and allow pending patrons to be created, set
+ the _Allow Patron Self-Registration_ (opac.allow_pending_user) Library
+ Setting to true where appropriate.
+ * To purge old pending user accounts, set an interval value for the new
+ _Patron Self_Reg Expire Interval_ (opac.pending_user_expire_interval)
+ Library Setting.
+ * The Library Settings to indicate show/require/regex/example for patron
+ registration are loaded dynamically, so any Library Settings added in the
+ future will also be honored. Any setting matching the following format is
+ used:
+ ** ui.patron.edit.[au|aua].*.show
+ ** ui.patron.edit.[au|aua].*.require
+ ** ui.patron.edit.[au|aua].*.regex
+ ** ui.patron.edit.[au|aua].*.example
+
+
+
+Responsive catalog
+^^^^^^^^^^^^^^^^^^
+
+The design of the web catalog is more responsive, optimizing its display for
+mobile devices. Users will see the following changes to the catalog's display
+when viewing it on a device with a small screen:
+
+- Elements on the basic search page were resized to fit better on the screen.
+
+- Results display cleanly on the search results page. Facets do not display by
+default, but a _Refine these results_ button is available to retrieve facets.
+Links to _Place hold_ or _Add to my list_ display prominently beneath holdings
+information.
+
+- Search boxes and filters wrap neatly on the advanced search page.
+
+- The search bar was removed from the login and My Account pages to free up
+real estate for more relevant information.
+
+- Navigational tabs were replaced with dropdown menus in several My Account
+screens.
+
+
+
+
+
+
+
+RSS Links to Full Catalog Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Links in RSS feeds now point directly to the catalog record instead of the
+htmlholdings-full format of the record.
+
+
+
+
+Serials
+~~~~~~~
+
+
+
+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
+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.
+
+
+
+
+Support Reader Address Information in Routing Slip Template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The serials routing slip template can now render user addresses if users with
+addresses appear on a routing list. This feature is particularly useful for
+working with homebound patrons.
+
+Sites that don't want to see a mailing or billing address can adjust the
+default template. Sites that already use a customized template will not be
+affected.
+
+
+
+
+SIP
+~~~
+
+
+
+Support SIP Hold Cancellation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Evergreen now supports a subset of the SIP 15/16 Holds message pair for holds
+cancellation.
+
+1. New oils_sip.xml configuration option "msg64_hold_datatype". This
+is similar to msg64_summary_datatype, but affects holds instead of
+circulations. When set to 'barcode', holds information will be
+delivered as a set of copy barcodes instead of title strings for patron
+info requests. With barcodes, SIP clients can both find the title
+strings for display (via item info requests) and make subsequent
+hold-related action requests, like holds cancellation.
++
+----
+Copies are not an ideal identifier for holds, but SIP has a limited
+vocabulary. With copies we can (99% of the time) work to and from hold
+requests to find a reasonable data set to work on. If a patron has
+multiple holds for the same item and wants to cancel a specific one of
+those holds, the user should use the catalog instead of SIP.
+----
+
+2. When receiving a message 15 of with a cancellation action, find the
+newest open hold that matches the provided copy barcode and cancel the
+hold.
+
+
+
+
+
+Return Hold ID to SIP
+^^^^^^^^^^^^^^^^^^^^^
+
+If there is a hold on a copy, Evergreen will now return to SIP a hold id to
+indicate that the copy has been captured for a hold. One possible use case for
+this feature is a scenario where a delivery vendor may be sorting copies needed
+for holds into a different bin from copies returning to their home library. The
+presence of the hold ID indicates that the copy has been captured for a hold.
+It also could use for an Automated Materials Handling (AMH) System to indicate
+that the copy is needed to fill a hold.
+
+
+
+
+
+Support for SIP "Renew All" messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Evergreen now supports SIP "Renew All" functionality, AKA SIP message pair
+65/66. When a 65 message is received, the SIP code collects all open
+transactions for the user and renews them all. The set of successful and
+failed renewals is returned to the caller via the SIP BM and BN fields.
+
+
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+
+P.V. SUPA GoodStuff Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There is now a "Server Add-ons" module for integrating P.V. Supa's RFID product
+known as GoodStuff with the Evergreen staff client.
+
+To activate it, you should add the identifier "pv_supa_goodstuff" (without the
+quotes) to the list managed by the Admin->Workstation Administration->Server
+Add-ons menu action within the staff client. You will need the
+ADMIN_SERVER_ADDON_FOR_WORKSTATION permission to do this.
+
+After doing this and clicking the Update Active Add-Ons button, the interface
+will refresh and show a GoodStuff tab in the Add-on Preferences section. Within
+this tab you will have the option of specifying the hostname and port for the
+Goodstuff hardware. There is also an "Enabled" setting that needs to be checked.
+
+Currently three interfaces have been integrated:
+
+ * Circulation -> Check In Items
+ * Circulation -> Check Out Items (where you scan the patron barcode)
+ * Circulation -> Check Out Items (where you scan the item barcodes)
+
+Each interface gets an RFID checkbox if the "Enabled" preference has been set
+that can activate/deactivate the functionality on a per interface basis. The
+checkbox states persist (i.e. are sticky).
+
+
+++ /dev/null
-Evergreen 2.5 Release Notes
-===========================
-:toc:
-:numbered:
-
-Upgrade Notes
--------------
-
-Circulation
-~~~~~~~~~~~
-
-Long Overdue Circulations Management
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-If you are using a custom version of the
-'/openils/conf/action_trigger_filters.json.example' file, you will need to
-merge the changes made by this feature into your file. The change in
-question alters the 'checkout.due' hook such that LONGOVERDUE circulations
-are no longer treated as regular overdue items.
-
-OPAC
-~~~~
-
-Web-Based Patron Self-Registration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- * If a value is set for the _Patron Self-Reg Expire Interval_
- (opac.pending_user_expire_interval) for any org units, the new
- /openils/bin/purge_pending_users.srfsh script should also be added to the
- opensrf user's crontab. Running the script once per day should suffice.
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-Log Redaction Config Change
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The previous log protect redaction instructions missed a method used
-by the patron initiated password reset system. In order to fill this
-gap, you need to find the <log_protect> portion of your
-opensrf_core.xml file and add the following line:
-
- <match_string>open-ils.actor.patron.password_reset.commit</match_string>
-
-You should see a number of similar lines already there in between
-<log_protect> and </log_protect>.
-
-Server Add-ons
-^^^^^^^^^^^^^^
-This adds a "Server Add-ons" menu entry under Admin -> Workstation
-Administration in the staff client. Choosing this allows you to edit or set a
-list of identifiers that correspond to JSAN-style modules found in
-/server/addons/, and is meant mainly for activating 3rd party modules within the
-staff client on a per-workstation basis. You need the
-ADMIN_SERVER_ADDON_FOR_WORKSTATION permission to use it.
-
-Configuration options for activated add-ons may also show up in this interface.
-
-
-
-
-New Features
-------------
-
-
-Acquisitions
-~~~~~~~~~~~~
-
-
-
-Support PO activation without requiring items
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A new _Activate PO Without Loading Items_ option in the PO allows staff to
-activate the PO without loading copies into the catalog.
-
-
-
-
-Differentiate between cancelled and "delayed" lineitems
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In the ACQ user interface, it is now more clear to users when a lineitem has
-been fully cancelled or if it has been cancelled temporarily (e.g.
-back-ordered).
-
-When a lineitem is cancelled, but "keep_debits" is true on the cancel reason,
-the lineitem is in effect delayed instead of truly cancelled. This is now
-more obvious in the interface with different row styling for cancelled vs
-delayed lineitems. We also always show the lineitem cancel reason (label)
-next to the non-title attributes in the lineitem list display.
-
-
-
-
-Opportunistic Acquisitions In-Process Copy Overlay
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Improves existing acquisitions copy overlay code (which matches and overlays
-using specified IDs) by adding broader matching criteria. By selecting the new
-option, _Auto Overlay In-process Acquisitions Copies_, the system will
-potentially overlay copies which:
-
-* 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_.
-
-
-
-
-
-
-Printing PO Names on Purchase Orders
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The _Print Purchase Order_ option now prints the PO Name in addition to the PO
-ID.
-
-
-
-
-Administration
-~~~~~~~~~~~~~~
-
-
-
-Default filter option for configuration screens
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, most admin configuration screens in the staff client will now
-include filters allowing staff to display just those items matching a certain
-criteria.
-
-
-
-
-Upgrade Notes : IDL2js Locale Support
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following Apache configuration changes are required to support the
-locale-aware IDL2js module.
-
-// note: there's no Apache conf highlighting. 'bash' works well enough.
-[source, bash]
------------------------------------------------------------------
-# file: eg_vhost.conf
-
-# this is the new part
-# capture locale CGI param for /reports/fm_IDL.xml
-RewriteCond %{REQUEST_URI} ^/reports/fm_IDL.xml
-RewriteCond %{QUERY_STRING} locale=([^&;]*)
-RewriteRule . - [E=locale:%1]
-
-# it should be placed just above this existing config section
-<LocationMatch /reports/fm_IDL.xml>
- IDLChunkStripPI "yes"
- IDLChunkEscapeScript "no"
- IDLChunkStripComments "yes"
- IDLChunkStripDoctype "yes"
- IDLChunkContentType "application/xml; charset=utf-8"
- AddOutputFilter INCLUDES;IDLCHUNK .xml
-</LocationMatch>
------------------------------------------------------------------
-
-Inter-authority linking script
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Adds a script called authority_authority_linker.pl in support-scripts that,
-when run, will link authority reference headings to authority records that
-contain the same main entry using a subfield 0. This causes triggers to fill
-up the authority-authority linking table and allows more information to appear
-in the bib/authority browse when a displayed heading comes from an authority
-record that has linked _See Also_ references.
-
-
-
-
-New Updates Tools
-^^^^^^^^^^^^^^^^^
-
-Source code for tools to generate the staff clients updates tools were
-added to Open-ILS/xul/staff_client/external/libmar. These tools
-replace the downloadable tools from Mozilla.org that were previously
-used to generate the staff client updates files.
-
-They come with their own configuration script and are configured
-automatically as a subpackage when you configure Evergreen for
-installation. They are also built and ready for use when you make
-Evergreen during the installation or upgrade process.
-
-The make_updates.sh script that is run when you tell Evergreen to make
-the staff client updates has been modified to use the new tools.
-
-These tools introduce a dependency on libbz2. This is often only
-available when installing the libbz2-dev or libbz2-devel packages.
-Thus this branch introduces a new dependency on the development packages
-for libbz2 in Evergreen.
-
-Nothing in the user facing behavior of building updates changes with
-these tools. They are drop-in replacements for the previous tools and
-other than the new dependency on libbz2, you don't even need to know
-that they are there.
-
-These tools were added to Evergreen to be an aid in portability to
-operating systems other than Linux. They also remove a dependency on
-a third-party tool, that is typically downloaded as a binary.
-
-
-
-Phonelist.pm Module
-^^^^^^^^^^^^^^^^^^^
-
-PhoneList.pm is a mod_perl module for Apache that works with Evergreen
-to generate callings lists for patron holds. 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.
-
-.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.
-
-
-
-
-"Purge Holds"
-^^^^^^^^^^^^^
-Similar to purging circulations one may wish to purge old (filled or canceled) hold information. This feature adds a database function and settings for doing so.
-
-Purged holds are moved to the action.aged_hold_request table with patron identifying information scrubbed, much like circulations are moved to action.aged_circulation.
-
-The settings allow for a default retention age as well as distinct retention
-ages for holds filled, holds canceled, and holds canceled by specific cancel
-causes. The most specific one wins unless a patron is retaining their hold history. In the latter case the patron's holds are retained either way.
-
-Note that the function still needs to be called, which could be set up as a cron job or done more manually, say after statistics collection. A new script, purge_holds.srfsh, is added that can be used to purge holds from cron.
-
-
-
-
-Action Trigger Event Repeatability
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Action Trigger Event Definitions have a new field, "Event Repeatability
-Delay". This feature allows events to be repeated after the designated
-delay interval. An example of this is sending a notification email when a
-patron's library card expires. If the library extends the expiration date
-on that card, we then need a way to send another notification email when
-that same card expires again. Before, the Action Trigger processor only
-created a new event if the event definition for that target had never
-been run before. But now it allows repeating of the event after the delay
-interval, if present.
-
-
-
-
-Cataloging
-~~~~~~~~~~
-
-
-Vandelay Item Import Defaults
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Via the Library Settings Editor (Org Unit Settings), support auto-generation of
-call numbers and barcodes for items imported via the staff client's MARC Batch
-Import interface (a.k.a. Vandelay). Support settings for applying a local
-prefix string to auto-generated call numbers and barcodes. For both, the
-prefix defaults to "VAN".
-
-Similarly, support default copy location and circ modifiers.
-
-New Library Settings
-+++++++++++++++++++++
-
- * Vandelay Generate Default Barcodes (vandelay.item.barcode.auto)
- * Vandelay Default Barcode Prefix (vandelay.item.barcode.prefix)
- * Vandelay General Default Call Numbers (vandelay.item.call_number.auto)
- * Vandelay Default Call Number Prefix (vandelay.item.call_number.prefix)
- * Vandelay Default Copy Location (vandelay.item.copy_location.default)
- * Vandelay Default Circulation Modifier (vandelay.item.circ_modifier.default)
-
-Z39.50 Batch Search and Queue
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Staff Work Flow
-+++++++++++++++
-
- * Staff add records to bib record buckets
- * Staff select the new "Locate Z39.50 Matches" action for a selected bucket.
- * Staff choose which Z39.50 sources and indexes to search and the destination
- queue.
- * Submitting the search fires a series of parallel Z39.50 searches across
- all selected Z39.50 sources.
- * Matches are added to the selected (Vandelay) queue.
- * Matched records may be manually or automatically overlaid to existing
- catalog records using the existing Vandelay import/merge/overlay features.
-
-Vandelay Limit to Bucket
-++++++++++++++++++++++++
-
-As a side effect of this feature, Vandelay now has a new option in the
-interface which allows staff to limit which catalog records to which an
-inbound record matches to bib records within a record bucket. When a record
-bucket and match set are chosen, only the records in the bucket can act as
-merge/overlay targets for the inbound Vandelay records.
-
-Server Admin Settings
-+++++++++++++++++++++
-
-_Z39.50 Index Field Maps_ can be used to map bib record
-indexes (Metabib Fields and Record Attributes) to Z39.50
-search attributes. The purpose of the mapping is to allow the server to
-determine which values to use for the automated Z39.50 searches. For example,
-if the Z39.50 "title" attribute is mapped to the "Uniform Title" Metabib Field,
-the extracted value for "Uniform Title" for each record in the bucket will be
-used as the "title" value in the Z39.50 search.
-
-Mappings can be applied to specific Z39.50 attributes, which define an attribute
-type and a Z39.50 source, or to generic attribute types (e.g. "title"). When
-a specific attribute is used, the mapping will only be applied to searches
-directed at the Z39.50 source linked to the attribute.
-
-The management interface can be found in the staff client under
-
-Admin => Server Administration => Z39.50 Index Field Maps
-
-Metabib Field Additions
-+++++++++++++++++++++++
-
-Stock config.metabib_field entries for author include additional author-
-related data, like dates. For example, a value for Personal Author might
-look like this:
-
-'girdlestone cuthbert morton 1895 1975 creator'
-
-In the context of searching Z39.50 servers, the extraneous data can be
-detrimental. Creating a separate field definition without the extra data
-is recommended.
-
-[source,sql]
---------------------------------------------
-INSERT INTO config.metabib_field
- (field_class, name, label, format, xpath, search_field)
- VALUES (
- 'author',
- 'personal - trimmed',
- 'Personal Author (trimmed)',
- 'mods32',
- '//mods32:mods/mods32:name[@type=''personal'' and mods32:role/mods32:roleTerm[text()=''creator'']]/mods32:namePart[not (@type)]',
- FALSE
- );
-
--- FULL BIB (OR INDEX-TARGETED) RE-INGEST REQUIRED
---------------------------------------------
-
-
-Library Settings
-+++++++++++++++++
-
- * Maximum Parallel Z39.50 Batch Searches (cat.z3950.batch.max_parallel)
- ** The maximum number of Z39.50 searches that can be in-flight at any given
- time when performing batch Z39.50 searches
- * Maximum Z39.50 Batch Search Results (cat.z3950.batch.max_results)
- ** The maximum number of search results to retrieve and queue for each
- record + Z39 source during batch Z39.50 searches
-
-
-
-Circulation
-~~~~~~~~~~~
-
-Patron barcode regex for patron registration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new library setting is available to set a barcode regex to be checked during
-patron registration.
-
-Setting for Desk Renewal to use original circulating library
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A new global flag option has been added to allow the circulating library of
-a desk renewal (a.k.a. a renewal using the staff client) to reuse the original
-circulation library for circ rule behaviors rather than using the workstation.
-This new setting is similar to existing options to use the originating
-circulation library in OPAC renewals.
-
-Library Setting to Disable Patron Credit
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new library setting is available to disable patron credit payments in the
-billing interface. When enabled, the setting will:
-
-* Disallow patron_credit payments in the payment API.
-* Hide all of the patron credit payment actions in the staff client patron
-payment interface.
-
-Option to Disallow Use of a Branch as a Pickup Library for Holds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new library setting is available to remove a branch from consideration as a
-hold pickup library. This setting only affects the OPAC pickup library selector
-and does not otherwise affect the display of the branch in the OPAC. It also
-has no effect on hold targeting / capturing.
-
-
-
-Floating Groups
-^^^^^^^^^^^^^^^
-
-In previous versions of Evergreen, floating group copies could float or not. If they floated, then they floated everywhere with no restrictions.
-
-This enhancement provides an interface to define where a copy will float by assigning it to a floating group.
-
-Long Overdue Circulations Management
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is a two-part feature, which covers marking circulations as long
-overdue via automated processing and check-in of long overdue circulations.
-
-Marking Circulations Long Overdue
-+++++++++++++++++++++++++++++++++
-
-A new Action/Trigger reactor (MarkItemLongOverdue) and sample event
-definition (6 Month Overdue Mark Long-Overdue) are included for
-marking circulations and their associated copies as long overdue. New Library
-Settings (Org Unit Settings) determine whether the item price and/or a
-processing fee is applied.
-
-A secondary Action/Trigger hook (longoverdue.auto) and sample event
-definition (6 Month Long Overdue Notice) are added so that (email, etc.)
-notifications can be sent when a circulation is marked long overdue via
-this new automated process.
-
-Also included is a new Action/Trigger validator PatronNotInCollections, which
-can be used to prevent long overdue processing (or any circ-based event
-definition) for patrons that are in collections processing at (or above) the
-circulating library.
-
-Check-in of Long Overdue Circulations
-+++++++++++++++++++++++++++++++++++++
-
-Check-in of long overdue items may result in any of the following actions,
-depending on configuration.
-
- * Void the copy price billing
- * Void the long-overdue processing fee billing
- * Reinstate voided overdue fines
-
-The process is practically identical to Lost processing. However, one
-difference between Lost and Long Overdue check-in is that the window
-of time during which a long overdue item may be returned may be based on the
-due date (like Lost) or the last billing activity date (last payment, last
-billing). This is controlled with the "Long-Overdue Check-In Interval Uses
-Last Activity Date" Library Setting.
-
-New Library Settings
-++++++++++++++++++++
-
- * Long-Overdue Materials Processing Fee
- * Void Overdue Fines When Items are Marked Long-Overdue
- * Leave transaction open when long overdue balance equals zero
- * Long-Overdue Items Usable on Checkin
- * Long-Overdue Max Return Interval
- * Restore Overdues on Long-Overdue Item Return
- * Void Long-Overdue Item Billing When Returned
- * Void Processing Fee on Long-Overdue Item Return
- * Long-Overdue Check-In Interval Uses Last Activity Date
-
-A combination of 'Charge lost on zero' and 'Default Item Price' are used to
-determine the amount to charge for the item price when a circulation is
-marked as long overdue.
-
-New Billing Types
-+++++++++++++++++
-
- * Long-Overdue Materials
- * Long-Overdue Materials Processing Fee
-
-New Permissions
-+++++++++++++++
-
- * SET_CIRC_LONG_OVERDUE
- * COPY_STATUS_LONGOVERDUE.override
-
-New Copy Status
-+++++++++++++++
-
- * Long Overdue
-
-
-
-
-Patron blocking by lost items and include lost as items out
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This feature has two main parts, both of which are to improve the staff's
-ability to assist patrons in regards to lost items.
-
-* Patron blocking by lost items. This will add a group penalty threshold
-that will alert staff when a patron has too many lost items. This
-setting is modified through the Group Penalty Thresholds page.
-
-* Include lost items as items out. Through a new Library Setting,
-'Include Lost circulations in lump sum tallies in Patron Display',
-the staff have the ability to determine if lost items will be included
-in items out.
-
-
-Long-Overdue Patron Standing Penalty
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is the long-overdue version of the existing PATRON_EXCEEDS_LOST_COUNT
-standing penalty. When a patron exceeds the configured threshold for open
-long-overdue (i.e. non-zero balance) circulations, the penalty is applied.
-When the number once again goes below the threshold, the penalty is removed.
-
-The penalty name is PATRON_EXCEEDS_LONGOVERDUE_COUNT / "Patron Exceeds Max
-Long-Overdue Threshold"
-
-
-Per-Hold Behind Desk Setting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The value for behind-the-desk pickup is now stored directly on each
-hold request. This allows the system to better track the true location
-of captured hold items in cases where the patron setting has changed since
-hold capture.
-
-For these features to be accessible, the "Behind Desk Pickup Supported"
-(circ.holds.behind_desk_pickup_supported) Library Setting must be set
-to true.
-
-Staff Client
-++++++++++++
-
-In addition to the counts of ready for pickup and available holds, the
-staff client now also displays the number of behind-the-desk-holds ready
-for pickup at the staff's working location. If no items are held behind
-the desk, this information does not display, in particular, because this
-information is useless if behind the desk holds are not supported at the
-staff's working location.
-
-TPAC Changes
-++++++++++++
-
-The system also allows patrons to set their own behind-the-desk
-pickup preferences in the TPAC settings interface. To activate this
-feature, admins need to set the Opac Visible flag to "true" for the
-"Hold is behind Circ Desk" (circ.holds_behind_desk) user setting and
-"Behind Desk Pickup Supported" must be set to true for the patron's
-home library.
-
-Print Single Item Receipt
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This feature adds the ability to print a receipt for just a single selected
-item from the patron interface for Items Out or Lost, Claims Returned, Long
-Overdue, Has Unpaid Billings. This can be used via right-click or using the
-'Actions for Selected Items' button.
-
-More User Name Fields Available for Simplified Hold Pull List
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-More User Name fields are available for display in the simplified hold pull
-list interface including:
-
-* First Given Name
-* Second Given Name
-* Family Name
-* Prefix
-* Suffix
-* User Alias or First Given Name
-* User Alias or Display Name
-* User Alias
-
-
-
-
-Changes to Self-Check Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The following improvements were made to the self-check interface:
-
-* Convert action links to buttons for increased clarity
-* Convert dashed fieldsets to gradient backed bubbles for depth
-* Color line-item table headers to distinguish from actual line-items
-* Color logo background for increased contrast
-* Larger input box
-* Background on prompts to distinguish from logo background
-
-
-
-
-Different Styles for Long Overdue Lost Items in Billing Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Lost or Long Overdue circulations that have not yet been returned will appear
-in the patron's list of billed transactions styled differently from other
-not-yet-returned items.
-
-The interface will also display a helpful message to staff indicating what
-colors map to what types of circulations.
-
-The default colors are maroon for Lost items and orange for Long Overdue items.
-
-To change the colors, modify circ.css. To change the language for the hint,
-modify lang.dtd.
-
-Checkout: Trim whitespace from beginning and end of barcode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In checkout, when pasting a barcode into the lookup field, one may accidentally
-include spaces or tabs in the beginning or end of the barcode string. Trim
-those away to avoid potential mis-scans.
-
-Wrong-Shelf Holds in Clearable Shelf-Expired Holds List
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following changes were made to the _Browse Holds Shelf_ interface:
-
-. Change the staff client _View Shelf-Expired Holds_ action label to _View
-Clearable Holds_.
-. When _View Clearable Holds_ is selected, show wrong-shelf holds in addition
-to shelf-expired and canceled holds.
-
-Client
-~~~~~~
-
-
-Customize Items Out Display for Lost, etc.
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Items which are LOST, LONGOVERDUE, or CLAIMSRETURNED may now be displayed
-in the top/main list of circulations instead of the bottom list in the
-staff client patron Items Out interface. Similarly, such items can be
-removed from the display once the items are checked in even if the
-transaction is still open (fines are owed, etc.).
-
-Apart from organization, this has two additional effects:
-
- * If all 3 types are hidden once checked in, the interface becomes a true
- items out interface, instead of a combination of items out and
- special circumstance checked-in circs.
- * If, in addition, all types are configured to be displayed in the top
- list, the bottom list is hidden from the UI (since nothing would display
- there), which creates more screen space for the main items out list.
-
-New Library Settings
-+++++++++++++++++++++
-
- * Items Out Long-Overdue display setting (ui.circ.items_out.longoverdue)
- * Items Out Lost display setting (ui.circ.items_out.lost)
- * Items Out Claims Returned display setting (ui.circ.items_out.claimsreturned)
-
-The value for each 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, regardless of the state of
-the transaction.
-
- * 1 = top list, then bottom list
- * 2 = bottom list, then bottom list
- * 5 = top list, then do not display
- * 6 = bottom list, then do not display
-
-Hint: to hide the bottom list entirely, set the value for all three settings
-to '5'.
-
-
-
-Adjustable font size in the staff client catalog
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When using the staff client, the font size in the catalog can now be
-increased/decreased by using the CTRL key with + (to increase), with - (to
-decrease), and with 0 (to restore default font size). Font sizes can persist
-via a setting in user preferences.
-
-Standalone Mode Shortcut
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Evergreen installer now includes a shortcut that launches the staff client
-directly into standalone (offline) mode.
-
-
-
-
-User Setting Defaults
-^^^^^^^^^^^^^^^^^^^^^
-
-For use during Patron Registration, we can now supply default values for User
-Settings, under _Admin_ -> _Server Administration_ -> _User Setting Types_.
-
-OPAC
-~~~~
-
-Added Content by Record ID
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-Traditionally, Evergreen has supported Added Content lookups by ISBN
-only, or (more recently) by one of ISBN or UPC.
-
-This enhancement adds support for Added Content lookups by record
-ID, while still supporting the previous URL format for lookups by
-ISBN.
-
-The JSPAC and TPAC skins, as well as the web-based Self Checkout
-interface templates are updated to use jacket images / cover art by
-record ID by default.
-
-By using record identifiers, the Added Content handler has the
-opportunity to examine additional identifiers in the bib record.
-Currently, these include:
-
- * ISBN
- * UPC
- * ISSN
-
-Currently, only the OpenILS::WWW::AddedContent::Syndetic provider
-makes use of the new identifiers.
-
-
-Local Content Overrides
-+++++++++++++++++++++++
-Just as with ISBN lookups, there is support for local overrides in
-the form of a file created on disk which short-circuits any external
-Added Content lookup.
-
-
-Apache Configuration
-++++++++++++++++++++
-
-The example Apache configs have been updated to support serving
-blank.png when added content jacket URLs return a 404. This prevents
-"broken image" placeholders in browsers, without requiring a
-Javascript onerror handler on each img tag.
-
-The changes are as follows:
-
-In the eg.conf VirtualHost declaration for SSL, add:
-
-[source,conf]
-SSLProxyEngine on # required for ErrorDocument 404 on SSL connections
-
-In the eg_vhost.conf file, add:
-
-[source,conf]
-<Location /opac/extras/ac/jacket>
- ErrorDocument 404 /opac/images/blank.png
-</Location>
-
-
-Bib record browser with linked authorities
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This feature provides a patron-oriented OPAC interface for browsing
-bibliographic records.
-
-Users choose to browse by Author, Title, Subject, or Series. They then
-enter a browse term, and the nearest match from a left-anchored search
-on the headings extracted for browse purposes will be displayed in a
-typical backwards/forwards paging display. Headings link to search
-results pages showing the related records. If the browse heading is
-linked to any authority records, and if any *other* authority records
-point to those with "See also" or other non-main entry headings, those
-alternative headings are displayed linked to a search results page
-showing related bib records related to the alternate heading.
-
-The counts of holdings displayed next to headings from bibliographic
-records are subject to the same visibility tests as search. This means
-that the org unit (and copy location group) dropdown on the browse
-interface affects counts, and it further means that whether or not
-you're looking at the browse interface through the staff client makes a
-difference.
-
-Configuration considerations for site administrators
-++++++++++++++++++++++++++++++++++++++++++++++++++++
-There are two off-by-default features that site administrators may wish
-to enable.
-
- * Quick paging links: By adding a value for the Library Setting
- _Paging shortcut links for OPAC Browse_ (opac.browse.pager_shortcuts), you
- can make shortcut browsing links such as ''0-9 A B C D ...'' appear
- between the Back and Next buttons on the browse page. The set of shortcuts
- should be chosen based on the languages in use at your site, but a
- reasonable value for English might be the string
- "*0-9*ABCDEFGHIJKLMNOPQRSTUVWXYZ", which will yield a link for 0-9 and one
- for each letter A-Z. The use of asterisks in the string group a shortcut
- whose label is more than a single letter in length. Such longer shortcuts
- have the multi-character string for the shortcut label, and the link just
- goes to the first heading matching the first character of the label. The
- letters not enclosed in asterisks just lead to individual letter shortcuts.
-
- * There is a global flag by the name _Map of search classes to regular
- expressions to warn user about leading articles_
- (opac.browse.warnable_regexp_per_class) to control what leading
- articles in users' entered browse terms trigger a warning about how
- it might be better to search for "Rolling Stones" instead of "The
- Rolling Stones" (or whatever). This is off by default, but can be
- enabled if it suits your catalog, and can even be customized per
- search class (author, title, series, subject).
-
- * Also, by default, authors are indexed for browse in such a way that
- relator roles like "creator" are dropped off the end of their headings.
- This was an aesthetic choice. If a site wanted to display those kinds
- of terms, they would update the 'config.metabib_field' table in
- the database, setting 'browse_xpath' to NULL where 'field_class' =
- ''author'' and 'browse_field' is true.
-
-
-Authority-enhanced bibliographic browse
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Evergreen OPAC includes functionality for browsing by bibliographic terms,
-and, where those terms are controlled by authority records, for linking directly
-to the records that use other authority controlled terms that are appropriately
-linked to the browse-exposed term. In this way, one can browse authors for
-"King, Stephen" and, when appropriate and correct cataloging has been performed,
-be presented with a browse link within the author browse list to that brings the
-user to a "Bachman, Richard" entry, assuming visible bibliographic records are
-indeed attached to both records. Likewise, when browsing for "Bachman,
-Richard", users will be presented with a browse link leading to the "King,
-Stephen" browse location.
-
-Additionally, any unused but inter-authority-linked terms will appear in the
-browse list if the linked heading is in use by bibliographic records. In this
-way, browsing for "Bachman, Richard" will lead the user to "King, Stephen" even
-if no bibliographic records make use of the "Bachman, Richard" heading.
-
-Linked authority records will not be exposed if neither is in use by visible
-bibliographic records. This means that the feature will not lead to dead-end
-searches, but also means that this is not a complete authority browsing tool
-acceptable for use as such by a cataloger. See the Manage Authorities interface
-exposed through the Staff Client for that functionality.
-
-
-Support for Conjoined Items
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The catalog now supports the display of conjoined items. The "joined" titles
-will display a copy record with a link in the copy table back to the "master"
-bib. The master bib will display a set of links to individual titles.
-
-
-Shelving Location Filter
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Filtering by shelving location is now available from the Advanced Search screen.
-
-Linked library names in copy details
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A patron may find one or more available copies of an item that they want to
-retrieve, but may not be familiar with the location, hours of operation, or
-contact information for each branch of their local library system. To enable
-the patron to quickly access information about a given library branch, the TPAC
-and KPAC can link the name of the branch in the copy details display to a URL
-associated with that branch.
-
-To set the URL for a given branch, use the *Local Administration -> Library
-Settings Editor* and edit the *Library Information URL* setting for that
-branch. Any branches that do not have a library information URL setting display
-as normal text.
-
-Ability to set search context by shortname
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When searching in the catalog, sites are able to set the search location by
-embedding a locg parameter in the URL. With this new features, sites will be
-able to use a branch's shortname to set the search locations whereas
-previously, sites could only use an org unit id. This parameter is case
-insensitive.
-
-OPAC Maintenance Message
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Sites can now set a maintenance message to display in the catalog by setting
-the ctx.maintenance_message variable in config.tt2.
-
-My List Enhancements
-^^^^^^^^^^^^^^^^^^^^
-
-The _My Lists_ feature has the following enhancements:
-
-* Improvement on current navigation for _My Lists_ by displaying a page number
-and allowing for navigation by page number;
-* Addition of pagination for items in a list;
-* Addition of _My Lists Preferences_ tab in _Account Preferences_ where users
-can identify the number of lists and the number of list items that should
-display in each page;
-* A prompt now displays when users select the _Delete List_ button confirming
-that they really want to delete the list.
-
-
-
-Web-Based Patron Self-Registration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Feature Summary
-+++++++++++++++
-
-Patrons may now fill out a web-based form from within the TPAC to create
-pending user accounts. The goal is to make the registration process more
-efficient by allowing the patron to provide much of the registration
-details in advance of registering with staff.
-
-Pending user accounts have no privileges.
-
-The form supports hiding fields, requiring fields, applying format
-validation, and displaying example text for selected fields by inspecting the
-relevant patron registration Library Settings.
-
-The "Request Library Card" link appears as the second default "bottom link"
-in the TPAC.
-
-If a user is logged in when clicking the register link, the logged-in
-user will be tracked as the requesting user for the pending account.
-Additionally, the home org unit and some address fields will be pre-populated
-for convenience (with the assumption that these will likely be the same for
-the pending user -- they can, of course, be changed). When a requesting user
-is present on the pending user, a link to the requesting user will be
-displayed within the patron registration form in the staff client.
-
-Pending patron accounts which sit unattended in the database for too long
-are purged via a regularly running (CRON) script.
-
-Technical Details
-+++++++++++++++++
-
- * To activate the web form and allow pending patrons to be created, set
- the _Allow Patron Self-Registration_ (opac.allow_pending_user) Library
- Setting to true where appropriate.
- * To purge old pending user accounts, set an interval value for the new
- _Patron Self_Reg Expire Interval_ (opac.pending_user_expire_interval)
- Library Setting.
- * The Library Settings to indicate show/require/regex/example for patron
- registration are loaded dynamically, so any Library Settings added in the
- future will also be honored. Any setting matching the following format is
- used:
- ** ui.patron.edit.[au|aua].*.show
- ** ui.patron.edit.[au|aua].*.require
- ** ui.patron.edit.[au|aua].*.regex
- ** ui.patron.edit.[au|aua].*.example
-
-
-
-Responsive catalog
-^^^^^^^^^^^^^^^^^^
-
-The design of the web catalog is more responsive, optimizing its display for
-mobile devices. Users will see the following changes to the catalog's display
-when viewing it on a device with a small screen:
-
-- Elements on the basic search page were resized to fit better on the screen.
-
-- Results display cleanly on the search results page. Facets do not display by
-default, but a _Refine these results_ button is available to retrieve facets.
-Links to _Place hold_ or _Add to my list_ display prominently beneath holdings
-information.
-
-- Search boxes and filters wrap neatly on the advanced search page.
-
-- The search bar was removed from the login and My Account pages to free up
-real estate for more relevant information.
-
-- Navigational tabs were replaced with dropdown menus in several My Account
-screens.
-
-
-
-
-
-
-
-RSS Links to Full Catalog Record
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Links in RSS feeds now point directly to the catalog record instead of the
-htmlholdings-full format of the record.
-
-
-
-
-Serials
-~~~~~~~
-
-
-
-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
-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.
-
-
-
-
-Support Reader Address Information in Routing Slip Template
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The serials routing slip template can now render user addresses if users with
-addresses appear on a routing list. This feature is particularly useful for
-working with homebound patrons.
-
-Sites that don't want to see a mailing or billing address can adjust the
-default template. Sites that already use a customized template will not be
-affected.
-
-
-
-
-SIP
-~~~
-
-
-
-Support SIP Hold Cancellation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Evergreen now supports a subset of the SIP 15/16 Holds message pair for holds
-cancellation.
-
-1. New oils_sip.xml configuration option "msg64_hold_datatype". This
-is similar to msg64_summary_datatype, but affects holds instead of
-circulations. When set to 'barcode', holds information will be
-delivered as a set of copy barcodes instead of title strings for patron
-info requests. With barcodes, SIP clients can both find the title
-strings for display (via item info requests) and make subsequent
-hold-related action requests, like holds cancellation.
-+
-----
-Copies are not an ideal identifier for holds, but SIP has a limited
-vocabulary. With copies we can (99% of the time) work to and from hold
-requests to find a reasonable data set to work on. If a patron has
-multiple holds for the same item and wants to cancel a specific one of
-those holds, the user should use the catalog instead of SIP.
-----
-
-2. When receiving a message 15 of with a cancellation action, find the
-newest open hold that matches the provided copy barcode and cancel the
-hold.
-
-
-
-
-
-Return Hold ID to SIP
-^^^^^^^^^^^^^^^^^^^^^
-
-If there is a hold on a copy, Evergreen will now return to SIP a hold id to
-indicate that the copy has been captured for a hold. One possible use case for
-this feature is a scenario where a delivery vendor may be sorting copies needed
-for holds into a different bin from copies returning to their home library. The
-presence of the hold ID indicates that the copy has been captured for a hold.
-It also could use for an Automated Materials Handling (AMH) System to indicate
-that the copy is needed to fill a hold.
-
-
-
-
-
-Support for SIP "Renew All" messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Evergreen now supports SIP "Renew All" functionality, AKA SIP message pair
-65/66. When a 65 message is received, the SIP code collects all open
-transactions for the user and renews them all. The set of successful and
-failed renewals is returned to the caller via the SIP BM and BN fields.
-
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-
-P.V. SUPA GoodStuff Integration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There is now a "Server Add-ons" module for integrating P.V. Supa's RFID product
-known as GoodStuff with the Evergreen staff client.
-
-To activate it, you should add the identifier "pv_supa_goodstuff" (without the
-quotes) to the list managed by the Admin->Workstation Administration->Server
-Add-ons menu action within the staff client. You will need the
-ADMIN_SERVER_ADDON_FOR_WORKSTATION permission to do this.
-
-After doing this and clicking the Update Active Add-Ons button, the interface
-will refresh and show a GoodStuff tab in the Add-on Preferences section. Within
-this tab you will have the option of specifying the hostname and port for the
-Goodstuff hardware. There is also an "Enabled" setting that needs to be checked.
-
-Currently three interfaces have been integrated:
-
- * Circulation -> Check In Items
- * Circulation -> Check Out Items (where you scan the patron barcode)
- * Circulation -> Check Out Items (where you scan the item barcodes)
-
-Each interface gets an RFID checkbox if the "Enabled" preference has been set
-that can activate/deactivate the functionality on a per interface basis. The
-checkbox states persist (i.e. are sticky).
-
-
--- /dev/null
+Evergreen 2.6 Release Notes
+===========================
+:toc:
+:numbered:
+
+Upgrade notes
+-------------
+
+OPAC
+~~~~
+
+TPAC library pages
+^^^^^^^^^^^^^^^^^^
+Evergreen 2.5 introduced the `Library information URL` library setting to
+associate a web page with a library. If set, this value was used as the target
+of the library link in the copy table on the record details page. However, the
+new default behavior is to link to the automatically generated TPAC library
+page, which in turn links to the external web site.
+
+If you wish to maintain the previous behavior, you can set the `Use external
+library information URL` library setting to `True`.
+
+
+Disable Autosuggest by Default
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+As described in https://bugs.launchpad.net/evergreen/+bug/1187993, the
+community is aware of ongoing accessibility issues caused through use of
+the autosuggest feature of the Evergreen catalog. The decision has been
+made to disable autosuggest by default for new installations. Existing sites
+are cautioned to take note of this change and decide for themselves whether
+to discontinue use.
+
+It is possible to disable the autosuggest feature via a global flag. Look in
+`Admin -> Server Administration -> Global Flags`, find the `OPAC: Show
+auto-completing suggestions dialog...` setting, then edit and uncheck the
+`Enabled` box.
+
+
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+Removal of open-ils.ingest service
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The open-ils.ingest service is no longer required, and has been
+removed.
+
+You should update your opensrf.xml file to remove references to
+open-ils.ingest, and you may also wish to remove the
+OpenILS/Application/Ingest.pm file from your Perl @INC path.
+
+In opensrf.xml, remove the entire <open-ils.ingest> element from the
+<apps> element, and remove <appname>open-ils.ingest</appname> from
+any <activeapps> elements where it is present.
+
+If you have the perldoc command installed, you can use the following
+command to locate the path on disk of the Ingest.pm file, which is
+no longer required and can be removed:
+
+[source, bash]
+-----------------------------------------------------------------
+perldoc -l OpenILS::Application::Ingest
+-----------------------------------------------------------------
+
+
+Reporter view 'classic_current_circ' dropped
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+As part of the DB upgrade, the reporter view
+"reporter.classic_current_circ" was dropped. If you previously
+installed this view from example.reporter-extension.sql, it will
+have to be re-installed by executing the "CREATE OR REPLACE
+VIEW reporter.classic_current_circ AS..." SQL once again from
+example.reporter-extension.sql.
+
+
+
+New Features
+------------
+
+Administration
+~~~~~~~~~~~~~~
+
+Add granular settings for requiring staff initials for notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are now three separate library settings for controlling whether staff
+are required to input their initials when creating different types of notes.
+See new library settings below.
+
+Any pre-existing library setting for requiring staff initials are preserved
+during the upgrade process. After upgrading, you may choose to change the set
+behavior for any of the three new settings.
+
+New Library Settings
++++++++++++++++++++++
+ * Require staff initials for entry/edit of patron standing penalties and messages. (ui.staff.require_initials.patron_standing_penalty)
+ * Require staff initials for entry/edit of patron notes. (ui.staff.require_initials.patron_info_notes)
+ * Require staff initials for entry/edit of copy notes. (ui.staff.require_initials.copy_notes)
+
+
+Cataloging
+~~~~~~~~~~
+
+Enhancements to Evergreen's MARC Editor Concerning Fixed Fields
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This work is a combination of two features. One provides suggested
+values in a right-click context menus for fixed field values based on
+the 'type' of the record being edited. The other provides a wizard to
+help specifically with the Physical Characteristics of the record, i.e.
+the 007 field.
+
+Right-Click Context Menus
++++++++++++++++++++++++++
+Users will be able to right-click on the value control for fixed fields
+in the MARC Editor, and Evergreen will provide a menu from which the
+user can select a possible value. This will work for fixed fields where
+Evergreen already contains information from the Library of Congress's
+MARC 21 standard.
+
+Example:
+
+image::media/ffer-right-click.png["Right-clicking the BLvl field"]
+
+Evergreen already comes loaded with information from the Library of
+Congress's MARC 21 standard on possible values for some fixed fields.
+
+The following table shows which fixed fields for which 'Record Types'
+have values already loaded into Evergreen.
+
+---------------------------------------------------------
+
+ Fixed Field | Record Types
+-------------+-----------------------------------
+ Audn | {BKS,COM,REC,SCO,SER,VIS}
+ BLvl | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
+ Form | {BKS,MAP,MIX,REC,SCO,SER,VIS}
+ Lang | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
+ LitF | {BKS}
+ Type | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
+
+
+---------------------------------------------------------
+
+A 'Record Type' is itself a combination of the 'Type of Record' (fixed
+field name: Type) and 'Bibliographic Level' (fixed field name: BLvl)
+elements of the MARC leader (positions 06 and 07 respectively). You can
+see a record's Record Type in the MARC Editor as shown in
+this screenshot:
+
+'Record Type':
+
+image::media/ffer-record-type.png["This Record Type is REC"]
+
+A user may add values to these fixed fields as well as to other fixed
+fields through the MARC Coded Value Maps interface found under the Admin
+-> Server Administration menu in the staff client. These are grouped by
+Record Attribute Types (a superset of fixed fields) which have labels
+such as 'Alph', 'Biog', 'Videorecording format', and 'Language'.
+
+From LOC Fixed Fields documentation, 'Alph' is 'Original alphabet or
+script of title', 'Biog' is 'Biography', 'Videorecording format' is from
+the 007 field, 'Language' is positions 35-37 of the 008, and so on.
+Other Record Attribute Types such as 'Author' are, of course, not fixed
+fields at all.
+
+When users add new values here, the right-click context menus of the
+fixed fields in the MARC Editor will include those values.
+
+All values added for any fixed field in the Coded Value Map will display
+for any 'Record Type' that uses that fixed field.
+
+Users of the MARC Editor always retain the option of leaving a fixed
+field blank, entering the special values # or |, or entering a value not
+provided by the right-click context menu.
+
+Physical Characteristics Wizard
++++++++++++++++++++++++++++++++
+By right-clicking on an existing or new 007 field in the MARC Editor, users
+will be able to enter a wizard that leads them step-by-step through the
+positions in that 007 field, telling them the significance of the current
+position and providing a drop-down list of possible values.
+
+Launching the Physical Characteristics Wizard:
+
+image::media/ffer-open-wizard.png["Launching the Physical Characteristics Wizard"]
+
+Choosing the Category of Material:
+
+image::media/ffer-007-00.png["Choosing the Category of Material"]
+
+Choosing a value for a later position:
+
+image::media/ffer-007-smd.png["Choosing a value for a later position"]
+
+
+marc_export script replacement
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The `/openils/bin/marc_export` script is completely rewritten. This
+new version accepts all of the same command line options as the old
+version as well as some new options.
+
+The rewritten `marc_export` talks directly to your Evergreen database
+and is a great deal faster than the previous version. Because the new
+script talks directly to the database, it needs to know how to
+connect. To facilitate this, a new option, `--store`, was added that
+allows the user to specify one of three Evergreen storage backends to
+use when exporting records. The valid choices are `reporter`,
+`cstore`, or `storage`. The default of `reporter` should work in most
+cases, but if you do have a separate reporter database and you know
+you want to talk directly to your main production database, then you
+will probably want to choose either `cstore` or `storage`.
+
+In addition to the `--store` option, a `--since` option is also added
+so that you can specify output of an update file of records changed,
+added, and/or deleted since the given date. The `--since` option uses
+a fairly flexible date parser and can accept a wide range of date
+formats including ISO 8601, man common date formats such as M/D/Y
+(common in the US) or D/Mon/Y (with the first 3 characters or more of
+the month spelled out), as well as several less common date formats.
+Special date strings such as `yesterday`, `today`, `yesterday week`,
+and `today week` are also supported. For more information see the
+VALID DATE FORMATS section of the `Date::Manip::Date` man page.
+Available online here:
+
+http://search.cpan.org/~sbeck/Date-Manip-6.42/lib/Date/Manip/Date.pod#VALID_DATE_FORMATS
+
+There is one final difference between the new script and the old
+`marc_export`. The new script does not output progress as it
+executes. Many of the statistics that the script reported are not
+readily available to the new script. It was deemed better to just not
+output any progress rather than to output something different from the
+old program. If your scripts parse the output from `marc_export`,
+they will need to modified not to expect any.
+
+
+Circulation
+~~~~~~~~~~~
+
+Lost Item Billing: New Min/Max Price Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When an item is marked lost, the user is typically billed for the item.
+In Evergreen, they can either be charged the amount recorded in the item
+object, or if that value is blank (or zero), charged a default price
+(controlled by settings).
+
+In addition to these existing settings, now we can accommodate a range of
+prices by saying the patron should be billed at least 'X' and not more
+than 'Y'. This also allows you to effectively set a fixed price for all
+lost items by setting min and max to the same amount.
+
+New Org Unit Settings
++++++++++++++++++++++
+ * Minimum Item Price: circ.min_item_price
+ * Maximum Item Price: circ.max_item_price
+
+New Permissions
++++++++++++++++
+ * UPDATE_ORG_UNIT_SETTING.circ.min_item_price
+ * UPDATE_ORG_UNIT_SETTING.circ.max_item_price
+
+
+User Editor: "Update Expire Date" button
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new button labeled "Update Expire Date" is added in the user
+editor next to expire date field. This button can be used to
+re-calculate the user's expire date based on the current profile's
+permission interval and today's date.
+
+This is similar to how the expire date is populated when creating a
+new user, or when changing the profile group.
+
+This button simplifies the process of "renewing" a user, by
+eliminating the requirement that staff manually enter a new expire
+date.
+
+A button is used here so that the updating of the expire date
+remains an intentional process, not one that happens upon any edit.
+
+
+OPAC
+~~~~
+
+Composite Record Attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With this feature we create an abstraction on top of the Record Attribute
+infrastructure to allow the aggregation of multiple, cross-Attribute values
+under a single search filter value, accessible through new, dynamic filters.
+
+Each QueryParser filter will be created by the addition of a Composite Record
+Attribute Definition. For instance, one may wish to create a Composite Record
+Attribute Definition for an abstract "Item Type" interface component that
+uses information from the item_type, vr_format, bib_level and item_form
+Record Attribute Definitions, with each Composite Record Attribute Value
+having a different combination of Record Attribute Values from some or all of
+these Record Attribute Definitions. In this way, as single interface
+component might be presented as a dropdown with options such as "All Books",
+"All video recordings", "DVDs", "VHS Tapes", "E-Books", "Audio Books" and
+"Large Print Books". Of particular note are the "DVDs" and "VHS Tapes"
+entries, which include information from Record Attribute Definitions
+completely separate from the others. Additionally, the Composite Record
+Attribute Values defined by this Composite Record Attribute Definition
+can be used to drive behavioral logic, such as alternate icon display or
+link generation, in upgrade-friendly template adjustments.
+
+Included in this development is a replacement for the single-attribute
+Format filter supplied for basic search. Instead, a Composite Attribute
+is used to combine the values from Item Type, Item Form and Videorecording
+Format in various ways that provide a more patron-friendly set of choices.
+
+This new Format filter can be adjusted, or even replaced with a completely
+local one, through configuration and without template adjustment.
+
+
+
+Located URI visibility options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Before this, Evergreen restricted the visibility of bibliographic records
+that make use of Located URIs in a way that attempts to model licensing
+restrictions.
+
+There now exists a global flag to allow sites the option of changing the
+behaviour of Located URIs so that they act in a way analogous to copies
+for visibility testing. When the opac.located_uri.act_as_copy global flag
+is enabled, Located URIs will cause their containing bib records to become
+visible in searches where the URI is in scope to either ancestors of the
+search library, as before, or descendants of the search library, as copies
+do. As before, if a preferred library is supplied by the user, it is
+added to the list of visible org units to check.
+
+Additionally, while the underlying UnAPI and supporting code was capable
+of providing a reasonable and logical sort order for the Located URIs when
+embedded as XML holdings elements, the client-facing UnAPI method was not
+making use of that. It now does, and uses the same sorting algorithm as
+is used for copies.
+
+
+Multi-valued Record Attributes and Controlled Record Attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Having identified common use cases and reasonable restrictions that can be
+placed on the feature set, we have extended the Record Attribute
+infrastructure to support both the extraction and storage of all instances
+of a defined Attribute found within a bibliographic record, as well as
+provide new and more powerful indexing of existing data, in several ways.
+
+Record Attributes can now be defined by configuration as either single-valued
+or multi-valued. For any Attribute configured as single-valued, only the
+first value extracted from a record will be stored. This configuration
+parameter and restriction is in place to support potential query
+optimizations based on foreknowledge of whether a given Attribute is multi-
+valued or not.
+
+Record Attributes will be defined by configuration as either controlled or
+uncontrolled. A controlled Record Attribute is one that has entries in the
+Coded Value Map infrastructure specifying the valid values the record may
+carry for this attribute. If defined as a controlled Attribute, any unknown
+values extracted from a record will be ignored. Uncontrolled Attributes,
+however, may contain any value. This configuration parameter and restriction
+also supports potential query optimization.
+
+We store uncontrolled attribute values in a new table with a monotonically
+decreasing ID sequence, separating it from controlled values, reducing storage
+requirements by retaining only unique values, and making lookup faster.
+
+Restrictions
+++++++++++++
+ * A Record Attribute's values must match Coded Value Map entries if it is to be a Controlled Attribute. Coded Value Map control is indicated by a new "controlled" boolean on the config.record_attr_definition table.
+ * Record Attributes must "opt in" to multi-valued-ness. Record Attributes will opt in via a new "multi" boolean on config.record_attr_definition; this restriction enforces site config requirements by being explicit about the definition of "multi" fields.
+ * If controlled but not opt'd in to multi-mode, only the first value will be recorded but the new search mechanism will be used.
+ * Only single-valued Record Attributes will be available for use by the system as Sort Axes.
+ * Only controlled Record Attributes will be available for use by the TPAC as dynamically generated filter UI components, such as filter dropdowns or multi-selects.
+
+New External Dependency
++++++++++++++++++++++++
+This new feature requires the addition of the intarray extension to Postgres.
+This is a stock extension available on most linux distributions via the same
+package as the already-required plperl extension.
+
+
+Restore OpenSearch Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Restore previously held functionality from JSPAC to support OpenSearch in TPAC.
+This allows users to easily add the Evergreen search engine to their browser's
+built-in set of search engines.
+
+
+Accepting payments with Stripe
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Stripe is a payment processing service that lets
+sites take credit card payments without payment card information ever
+touching the sites' own servers.
+
+NOTE: Using Stripe as a payment processor means that clients *must*
+have Javascript enabled in order to submit fine payments through your
+OPAC.
+
+Library Settings
+++++++++++++++++
+The following settings need to be set at the appropriate org level for
+sites wanting to use Stripe.
+
+ * "Allow Credit Card Payments" (should be 'true')
+
+ credit.payments.allow
+
+ * "Enable Stripe payments" (should be 'true')
+
+ credit.processor.stripe.enabled
+
+ * "Stripe publishable key" (value provided by Stripe)
+
+ credit.processor.stripe.pubkey
+
+ * "Stripe secret key" (value provided by Stripe)
+
+ credit.processor.stripe.secretkey
+
+ * "Name default credit processor" (should be 'Stripe')
+
+ credit.processor.default
+
+
+TPAC library pages
+^^^^^^^^^^^^^^^^^^
+This feature adds one web page per library in the system to the TPAC at
+`http://hostname/eg/opac/library/<SHORTNAME>` and
+`http://hostname/eg/opac/library/<ID>`. The pages publish the following
+information from Evergreen (if available):
+
+* Name of the library
+* Link to the library web site (from `Library Information URL` library setting)
+* Opening hours
+* Email address
+* Phone number
+* Mailing address
+* Link to parent library (if applicable)
+
+Library pages are linked from the copy table on the record details page.
+
+Structured data
++++++++++++++++
+The library web pages publish schema.org structured data, which can enable
+search engines and other systems to better understand your libraries and their
+resources.
+
+
+TPAC Metarecord Search and Holds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This feature adds support for searching and placing holds against
+metarecords.
+
+Metarecord Searching
+++++++++++++++++++++
+In the top search bar and in the advanced search page, there is a new
+search modifier labeled "Group Formats and Editions". When selected,
+searches are performed against metarecords and metarecords are shown
+in the results list.
+
+For each metarecord, format icons for all constituent records are shown.
+When a use clicks on a metarecord, if the metarecord has multiple
+constituent records, the user is taken to the constituent records
+list. Similarly, when a metarecord only has one constituent record,
+the user is directed to the record detail page for the constituent
+record.
+
+Metarecord Holds
+++++++++++++++++
+Clicking the place hold link from the metarecord results page shows
+the available formats and languages for the metarecord, allowing
+the user to limit the scope of the hold. Non-metarecord holds now
+get a new "Advanced Holds Options" link which allows user to promote
+a title hold to a metarecord hold, thus providing access
+to the formats / editions selector, before the hold is placed.
+
+In the My Account holds list, icons for all selected formats are
+displayed in the Format columns for the hold. When editing a
+metarecord hold, users may modify the desired formats and languages.
+
+Configuration
++++++++++++++
+Admins may disable this feature by un-commenting the "metarecord.disabled"
+attribute in config.tt2
+
+
+Web Content Accessibility Guidelines (WCAG) Compliance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To make the catalog more accessible to users with a range of disabilities,
+including blindness and low vision, the catalog has been revised to better
+comply with the Web Content Accessibility Guidelines (WCAG) 2.0. These
+revisions target level "AA" of compliance.
+
+For more information on WCAG, see http://www.w3.org/WAI/intro/wcag
+
+
+Bug Fixes
+---------
+
+IMPORTANT SECURITY INFORMATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A serious security flaw that allows unauthorized remote access to
+organizational unit settings is fixed in the following releases of
+Evergreen: 2.5.9, 2.6.7, and 2.7.4. All prior releases of Evergreen
+are vulnerable to exploitation of this flaw to reveal sensitive system
+information. If you are running a vulnerable release of Evergreen you
+are *strongly* encouraged to upgrade to a non-vulnerable release as
+soon as possible.
+
+Set resource limits for Clark Kent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Several parameters are now available for the reporter daemon process
+(`clark-kent.pl`) to control resource usage. These can be used to
+reduce the chances that a malformed report can cause indigestion
+on a database or reports server. The new parameters, which can be
+set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
+
+* `//reporter/setup/statement_timeout` / `--statement-timeout`
+
+Number of minutes to allow a report's underlying SQL query
+to run before it gets cancelled. Default value is
+60 minutes. If a report's query gets cancelled, the
+error_text value will be set to a valid that indicates that
+the allowed time was exceeded.
+
+* `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
+
+Number of rows permitted in the query's output before
+Clark Kent refuses to attempt to draw a graph. Default
+value is 1,000 rows.
+
+* `//reporter/setup/resultset_limit` / `--resultset-limit`
+
+If set, truncates the report's output to the specified
+number of hits. Note that it will not be apparent
+to a staff user if the report's output has been
+truncated. Default value is unlimited.
+
+The report concurrency (i.e., the number of reports that Clark
+Kent will run in parallel) can now also be controlled via
+the `opensrf.xml` setting `//reporter/setup/parallel`.
+
+Acknowledgments
+---------------
+The Evergreen project would like to acknowledge the following
+organizations who commissioned developments in this release of
+Evergreen:
+
+ * Butler Public Library, IN, USA
+ * British Columbia Libraries Cooperative
+ * Carnegie Public Library of Steuben County, IN, USA
+ * Centerville-Center Township Public Library, IN, USA
+ * Flora Public Library, IN, USA
+ * Hagerstown - Jefferson Township Library, IN, USA
+ * Howe Library, Hanover, NH, USA
+ * Massachusetts Library Network Cooperative
+ * Newton County Public Library, IN, USA
+ * Noble County Public Library, IN, USA
+ * Natural Resources Canada
+ * North of Boston Library Exchange
+ * Perry County Public Library, IN, USA
+ * Plainfield-Guilford Township Public Library, IN, USA
+ * Rodgers Memorial Library, Hudson, NH, USA
+ * Statistics Canada
+ * Union County Public Library, IN, USA
+ * Westfield Washington Public Library, IN, USA
+
+We would also like to thank the following individuals who contributed
+code and documentations patches to this release of Evergreen:
+
+ * Jason Boyer
+ * Galen Charlton
+ * Mark Cooper
+ * Bill Erickson
+ * Jason Etheridge
+ * Lebbeous Fogle-Weekley
+ * Jeff Godin
+ * Pasi Kallinen
+ * Mike Rylander
+ * Dan Scott
+ * Chris Sharp
+ * Ben Shum
+ * Remington Steed
+ * Jason Stephenson
+ * Yamil Suarez
+ * Elliot Voris
+ * Dan Wells
+
+We also thank the following organizations whose employees contributed
+patches:
+
+ * Berklee College of Music
+ * Bibliomation
+ * Calvin College
+ * Equinox Software, Inc.
+ * Georgia Public Library Service
+ * Indiana State Library
+ * Laurentian University
+ * Merrimack Valley Library Consortium
+ * Pohjois-Karjalan Tietotekniikkakeskus Oy
+ * Saint Louis Christian College
+ * Traverse Area District Library
+
+We regret any omissions. If a contributor has been inadvertently
+missed, please open a bug at http://bugs.launchpad.net/evergreen/
+with a correction.
+
+++ /dev/null
-Evergreen 2.6 Release Notes
-===========================
-:toc:
-:numbered:
-
-Upgrade notes
--------------
-
-OPAC
-~~~~
-
-TPAC library pages
-^^^^^^^^^^^^^^^^^^
-Evergreen 2.5 introduced the `Library information URL` library setting to
-associate a web page with a library. If set, this value was used as the target
-of the library link in the copy table on the record details page. However, the
-new default behavior is to link to the automatically generated TPAC library
-page, which in turn links to the external web site.
-
-If you wish to maintain the previous behavior, you can set the `Use external
-library information URL` library setting to `True`.
-
-
-Disable Autosuggest by Default
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-As described in https://bugs.launchpad.net/evergreen/+bug/1187993, the
-community is aware of ongoing accessibility issues caused through use of
-the autosuggest feature of the Evergreen catalog. The decision has been
-made to disable autosuggest by default for new installations. Existing sites
-are cautioned to take note of this change and decide for themselves whether
-to discontinue use.
-
-It is possible to disable the autosuggest feature via a global flag. Look in
-`Admin -> Server Administration -> Global Flags`, find the `OPAC: Show
-auto-completing suggestions dialog...` setting, then edit and uncheck the
-`Enabled` box.
-
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-Removal of open-ils.ingest service
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The open-ils.ingest service is no longer required, and has been
-removed.
-
-You should update your opensrf.xml file to remove references to
-open-ils.ingest, and you may also wish to remove the
-OpenILS/Application/Ingest.pm file from your Perl @INC path.
-
-In opensrf.xml, remove the entire <open-ils.ingest> element from the
-<apps> element, and remove <appname>open-ils.ingest</appname> from
-any <activeapps> elements where it is present.
-
-If you have the perldoc command installed, you can use the following
-command to locate the path on disk of the Ingest.pm file, which is
-no longer required and can be removed:
-
-[source, bash]
------------------------------------------------------------------
-perldoc -l OpenILS::Application::Ingest
------------------------------------------------------------------
-
-
-Reporter view 'classic_current_circ' dropped
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-As part of the DB upgrade, the reporter view
-"reporter.classic_current_circ" was dropped. If you previously
-installed this view from example.reporter-extension.sql, it will
-have to be re-installed by executing the "CREATE OR REPLACE
-VIEW reporter.classic_current_circ AS..." SQL once again from
-example.reporter-extension.sql.
-
-
-
-New Features
-------------
-
-Administration
-~~~~~~~~~~~~~~
-
-Add granular settings for requiring staff initials for notes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are now three separate library settings for controlling whether staff
-are required to input their initials when creating different types of notes.
-See new library settings below.
-
-Any pre-existing library setting for requiring staff initials are preserved
-during the upgrade process. After upgrading, you may choose to change the set
-behavior for any of the three new settings.
-
-New Library Settings
-+++++++++++++++++++++
- * Require staff initials for entry/edit of patron standing penalties and messages. (ui.staff.require_initials.patron_standing_penalty)
- * Require staff initials for entry/edit of patron notes. (ui.staff.require_initials.patron_info_notes)
- * Require staff initials for entry/edit of copy notes. (ui.staff.require_initials.copy_notes)
-
-
-Cataloging
-~~~~~~~~~~
-
-Enhancements to Evergreen's MARC Editor Concerning Fixed Fields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This work is a combination of two features. One provides suggested
-values in a right-click context menus for fixed field values based on
-the 'type' of the record being edited. The other provides a wizard to
-help specifically with the Physical Characteristics of the record, i.e.
-the 007 field.
-
-Right-Click Context Menus
-+++++++++++++++++++++++++
-Users will be able to right-click on the value control for fixed fields
-in the MARC Editor, and Evergreen will provide a menu from which the
-user can select a possible value. This will work for fixed fields where
-Evergreen already contains information from the Library of Congress's
-MARC 21 standard.
-
-Example:
-
-image::media/ffer-right-click.png["Right-clicking the BLvl field"]
-
-Evergreen already comes loaded with information from the Library of
-Congress's MARC 21 standard on possible values for some fixed fields.
-
-The following table shows which fixed fields for which 'Record Types'
-have values already loaded into Evergreen.
-
----------------------------------------------------------
-
- Fixed Field | Record Types
--------------+-----------------------------------
- Audn | {BKS,COM,REC,SCO,SER,VIS}
- BLvl | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
- Form | {BKS,MAP,MIX,REC,SCO,SER,VIS}
- Lang | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
- LitF | {BKS}
- Type | {BKS,COM,MAP,MIX,REC,SCO,SER,VIS}
-
-
----------------------------------------------------------
-
-A 'Record Type' is itself a combination of the 'Type of Record' (fixed
-field name: Type) and 'Bibliographic Level' (fixed field name: BLvl)
-elements of the MARC leader (positions 06 and 07 respectively). You can
-see a record's Record Type in the MARC Editor as shown in
-this screenshot:
-
-'Record Type':
-
-image::media/ffer-record-type.png["This Record Type is REC"]
-
-A user may add values to these fixed fields as well as to other fixed
-fields through the MARC Coded Value Maps interface found under the Admin
--> Server Administration menu in the staff client. These are grouped by
-Record Attribute Types (a superset of fixed fields) which have labels
-such as 'Alph', 'Biog', 'Videorecording format', and 'Language'.
-
-From LOC Fixed Fields documentation, 'Alph' is 'Original alphabet or
-script of title', 'Biog' is 'Biography', 'Videorecording format' is from
-the 007 field, 'Language' is positions 35-37 of the 008, and so on.
-Other Record Attribute Types such as 'Author' are, of course, not fixed
-fields at all.
-
-When users add new values here, the right-click context menus of the
-fixed fields in the MARC Editor will include those values.
-
-All values added for any fixed field in the Coded Value Map will display
-for any 'Record Type' that uses that fixed field.
-
-Users of the MARC Editor always retain the option of leaving a fixed
-field blank, entering the special values # or |, or entering a value not
-provided by the right-click context menu.
-
-Physical Characteristics Wizard
-+++++++++++++++++++++++++++++++
-By right-clicking on an existing or new 007 field in the MARC Editor, users
-will be able to enter a wizard that leads them step-by-step through the
-positions in that 007 field, telling them the significance of the current
-position and providing a drop-down list of possible values.
-
-Launching the Physical Characteristics Wizard:
-
-image::media/ffer-open-wizard.png["Launching the Physical Characteristics Wizard"]
-
-Choosing the Category of Material:
-
-image::media/ffer-007-00.png["Choosing the Category of Material"]
-
-Choosing a value for a later position:
-
-image::media/ffer-007-smd.png["Choosing a value for a later position"]
-
-
-marc_export script replacement
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The `/openils/bin/marc_export` script is completely rewritten. This
-new version accepts all of the same command line options as the old
-version as well as some new options.
-
-The rewritten `marc_export` talks directly to your Evergreen database
-and is a great deal faster than the previous version. Because the new
-script talks directly to the database, it needs to know how to
-connect. To facilitate this, a new option, `--store`, was added that
-allows the user to specify one of three Evergreen storage backends to
-use when exporting records. The valid choices are `reporter`,
-`cstore`, or `storage`. The default of `reporter` should work in most
-cases, but if you do have a separate reporter database and you know
-you want to talk directly to your main production database, then you
-will probably want to choose either `cstore` or `storage`.
-
-In addition to the `--store` option, a `--since` option is also added
-so that you can specify output of an update file of records changed,
-added, and/or deleted since the given date. The `--since` option uses
-a fairly flexible date parser and can accept a wide range of date
-formats including ISO 8601, man common date formats such as M/D/Y
-(common in the US) or D/Mon/Y (with the first 3 characters or more of
-the month spelled out), as well as several less common date formats.
-Special date strings such as `yesterday`, `today`, `yesterday week`,
-and `today week` are also supported. For more information see the
-VALID DATE FORMATS section of the `Date::Manip::Date` man page.
-Available online here:
-
-http://search.cpan.org/~sbeck/Date-Manip-6.42/lib/Date/Manip/Date.pod#VALID_DATE_FORMATS
-
-There is one final difference between the new script and the old
-`marc_export`. The new script does not output progress as it
-executes. Many of the statistics that the script reported are not
-readily available to the new script. It was deemed better to just not
-output any progress rather than to output something different from the
-old program. If your scripts parse the output from `marc_export`,
-they will need to modified not to expect any.
-
-
-Circulation
-~~~~~~~~~~~
-
-Lost Item Billing: New Min/Max Price Settings
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When an item is marked lost, the user is typically billed for the item.
-In Evergreen, they can either be charged the amount recorded in the item
-object, or if that value is blank (or zero), charged a default price
-(controlled by settings).
-
-In addition to these existing settings, now we can accommodate a range of
-prices by saying the patron should be billed at least 'X' and not more
-than 'Y'. This also allows you to effectively set a fixed price for all
-lost items by setting min and max to the same amount.
-
-New Org Unit Settings
-+++++++++++++++++++++
- * Minimum Item Price: circ.min_item_price
- * Maximum Item Price: circ.max_item_price
-
-New Permissions
-+++++++++++++++
- * UPDATE_ORG_UNIT_SETTING.circ.min_item_price
- * UPDATE_ORG_UNIT_SETTING.circ.max_item_price
-
-
-User Editor: "Update Expire Date" button
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new button labeled "Update Expire Date" is added in the user
-editor next to expire date field. This button can be used to
-re-calculate the user's expire date based on the current profile's
-permission interval and today's date.
-
-This is similar to how the expire date is populated when creating a
-new user, or when changing the profile group.
-
-This button simplifies the process of "renewing" a user, by
-eliminating the requirement that staff manually enter a new expire
-date.
-
-A button is used here so that the updating of the expire date
-remains an intentional process, not one that happens upon any edit.
-
-
-OPAC
-~~~~
-
-Composite Record Attributes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-With this feature we create an abstraction on top of the Record Attribute
-infrastructure to allow the aggregation of multiple, cross-Attribute values
-under a single search filter value, accessible through new, dynamic filters.
-
-Each QueryParser filter will be created by the addition of a Composite Record
-Attribute Definition. For instance, one may wish to create a Composite Record
-Attribute Definition for an abstract "Item Type" interface component that
-uses information from the item_type, vr_format, bib_level and item_form
-Record Attribute Definitions, with each Composite Record Attribute Value
-having a different combination of Record Attribute Values from some or all of
-these Record Attribute Definitions. In this way, as single interface
-component might be presented as a dropdown with options such as "All Books",
-"All video recordings", "DVDs", "VHS Tapes", "E-Books", "Audio Books" and
-"Large Print Books". Of particular note are the "DVDs" and "VHS Tapes"
-entries, which include information from Record Attribute Definitions
-completely separate from the others. Additionally, the Composite Record
-Attribute Values defined by this Composite Record Attribute Definition
-can be used to drive behavioral logic, such as alternate icon display or
-link generation, in upgrade-friendly template adjustments.
-
-Included in this development is a replacement for the single-attribute
-Format filter supplied for basic search. Instead, a Composite Attribute
-is used to combine the values from Item Type, Item Form and Videorecording
-Format in various ways that provide a more patron-friendly set of choices.
-
-This new Format filter can be adjusted, or even replaced with a completely
-local one, through configuration and without template adjustment.
-
-
-
-Located URI visibility options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Before this, Evergreen restricted the visibility of bibliographic records
-that make use of Located URIs in a way that attempts to model licensing
-restrictions.
-
-There now exists a global flag to allow sites the option of changing the
-behaviour of Located URIs so that they act in a way analogous to copies
-for visibility testing. When the opac.located_uri.act_as_copy global flag
-is enabled, Located URIs will cause their containing bib records to become
-visible in searches where the URI is in scope to either ancestors of the
-search library, as before, or descendants of the search library, as copies
-do. As before, if a preferred library is supplied by the user, it is
-added to the list of visible org units to check.
-
-Additionally, while the underlying UnAPI and supporting code was capable
-of providing a reasonable and logical sort order for the Located URIs when
-embedded as XML holdings elements, the client-facing UnAPI method was not
-making use of that. It now does, and uses the same sorting algorithm as
-is used for copies.
-
-
-Multi-valued Record Attributes and Controlled Record Attributes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Having identified common use cases and reasonable restrictions that can be
-placed on the feature set, we have extended the Record Attribute
-infrastructure to support both the extraction and storage of all instances
-of a defined Attribute found within a bibliographic record, as well as
-provide new and more powerful indexing of existing data, in several ways.
-
-Record Attributes can now be defined by configuration as either single-valued
-or multi-valued. For any Attribute configured as single-valued, only the
-first value extracted from a record will be stored. This configuration
-parameter and restriction is in place to support potential query
-optimizations based on foreknowledge of whether a given Attribute is multi-
-valued or not.
-
-Record Attributes will be defined by configuration as either controlled or
-uncontrolled. A controlled Record Attribute is one that has entries in the
-Coded Value Map infrastructure specifying the valid values the record may
-carry for this attribute. If defined as a controlled Attribute, any unknown
-values extracted from a record will be ignored. Uncontrolled Attributes,
-however, may contain any value. This configuration parameter and restriction
-also supports potential query optimization.
-
-We store uncontrolled attribute values in a new table with a monotonically
-decreasing ID sequence, separating it from controlled values, reducing storage
-requirements by retaining only unique values, and making lookup faster.
-
-Restrictions
-++++++++++++
- * A Record Attribute's values must match Coded Value Map entries if it is to be a Controlled Attribute. Coded Value Map control is indicated by a new "controlled" boolean on the config.record_attr_definition table.
- * Record Attributes must "opt in" to multi-valued-ness. Record Attributes will opt in via a new "multi" boolean on config.record_attr_definition; this restriction enforces site config requirements by being explicit about the definition of "multi" fields.
- * If controlled but not opt'd in to multi-mode, only the first value will be recorded but the new search mechanism will be used.
- * Only single-valued Record Attributes will be available for use by the system as Sort Axes.
- * Only controlled Record Attributes will be available for use by the TPAC as dynamically generated filter UI components, such as filter dropdowns or multi-selects.
-
-New External Dependency
-+++++++++++++++++++++++
-This new feature requires the addition of the intarray extension to Postgres.
-This is a stock extension available on most linux distributions via the same
-package as the already-required plperl extension.
-
-
-Restore OpenSearch Support
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-Restore previously held functionality from JSPAC to support OpenSearch in TPAC.
-This allows users to easily add the Evergreen search engine to their browser's
-built-in set of search engines.
-
-
-Accepting payments with Stripe
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Stripe is a payment processing service that lets
-sites take credit card payments without payment card information ever
-touching the sites' own servers.
-
-NOTE: Using Stripe as a payment processor means that clients *must*
-have Javascript enabled in order to submit fine payments through your
-OPAC.
-
-Library Settings
-++++++++++++++++
-The following settings need to be set at the appropriate org level for
-sites wanting to use Stripe.
-
- * "Allow Credit Card Payments" (should be 'true')
-
- credit.payments.allow
-
- * "Enable Stripe payments" (should be 'true')
-
- credit.processor.stripe.enabled
-
- * "Stripe publishable key" (value provided by Stripe)
-
- credit.processor.stripe.pubkey
-
- * "Stripe secret key" (value provided by Stripe)
-
- credit.processor.stripe.secretkey
-
- * "Name default credit processor" (should be 'Stripe')
-
- credit.processor.default
-
-
-TPAC library pages
-^^^^^^^^^^^^^^^^^^
-This feature adds one web page per library in the system to the TPAC at
-`http://hostname/eg/opac/library/<SHORTNAME>` and
-`http://hostname/eg/opac/library/<ID>`. The pages publish the following
-information from Evergreen (if available):
-
-* Name of the library
-* Link to the library web site (from `Library Information URL` library setting)
-* Opening hours
-* Email address
-* Phone number
-* Mailing address
-* Link to parent library (if applicable)
-
-Library pages are linked from the copy table on the record details page.
-
-Structured data
-+++++++++++++++
-The library web pages publish schema.org structured data, which can enable
-search engines and other systems to better understand your libraries and their
-resources.
-
-
-TPAC Metarecord Search and Holds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This feature adds support for searching and placing holds against
-metarecords.
-
-Metarecord Searching
-++++++++++++++++++++
-In the top search bar and in the advanced search page, there is a new
-search modifier labeled "Group Formats and Editions". When selected,
-searches are performed against metarecords and metarecords are shown
-in the results list.
-
-For each metarecord, format icons for all constituent records are shown.
-When a use clicks on a metarecord, if the metarecord has multiple
-constituent records, the user is taken to the constituent records
-list. Similarly, when a metarecord only has one constituent record,
-the user is directed to the record detail page for the constituent
-record.
-
-Metarecord Holds
-++++++++++++++++
-Clicking the place hold link from the metarecord results page shows
-the available formats and languages for the metarecord, allowing
-the user to limit the scope of the hold. Non-metarecord holds now
-get a new "Advanced Holds Options" link which allows user to promote
-a title hold to a metarecord hold, thus providing access
-to the formats / editions selector, before the hold is placed.
-
-In the My Account holds list, icons for all selected formats are
-displayed in the Format columns for the hold. When editing a
-metarecord hold, users may modify the desired formats and languages.
-
-Configuration
-+++++++++++++
-Admins may disable this feature by un-commenting the "metarecord.disabled"
-attribute in config.tt2
-
-
-Web Content Accessibility Guidelines (WCAG) Compliance
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To make the catalog more accessible to users with a range of disabilities,
-including blindness and low vision, the catalog has been revised to better
-comply with the Web Content Accessibility Guidelines (WCAG) 2.0. These
-revisions target level "AA" of compliance.
-
-For more information on WCAG, see http://www.w3.org/WAI/intro/wcag
-
-
-Bug Fixes
----------
-
-IMPORTANT SECURITY INFORMATION
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A serious security flaw that allows unauthorized remote access to
-organizational unit settings is fixed in the following releases of
-Evergreen: 2.5.9, 2.6.7, and 2.7.4. All prior releases of Evergreen
-are vulnerable to exploitation of this flaw to reveal sensitive system
-information. If you are running a vulnerable release of Evergreen you
-are *strongly* encouraged to upgrade to a non-vulnerable release as
-soon as possible.
-
-Set resource limits for Clark Kent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Several parameters are now available for the reporter daemon process
-(`clark-kent.pl`) to control resource usage. These can be used to
-reduce the chances that a malformed report can cause indigestion
-on a database or reports server. The new parameters, which can be
-set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
-
-* `//reporter/setup/statement_timeout` / `--statement-timeout`
-
-Number of minutes to allow a report's underlying SQL query
-to run before it gets cancelled. Default value is
-60 minutes. If a report's query gets cancelled, the
-error_text value will be set to a valid that indicates that
-the allowed time was exceeded.
-
-* `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
-
-Number of rows permitted in the query's output before
-Clark Kent refuses to attempt to draw a graph. Default
-value is 1,000 rows.
-
-* `//reporter/setup/resultset_limit` / `--resultset-limit`
-
-If set, truncates the report's output to the specified
-number of hits. Note that it will not be apparent
-to a staff user if the report's output has been
-truncated. Default value is unlimited.
-
-The report concurrency (i.e., the number of reports that Clark
-Kent will run in parallel) can now also be controlled via
-the `opensrf.xml` setting `//reporter/setup/parallel`.
-
-Acknowledgments
----------------
-The Evergreen project would like to acknowledge the following
-organizations who commissioned developments in this release of
-Evergreen:
-
- * Butler Public Library, IN, USA
- * British Columbia Libraries Cooperative
- * Carnegie Public Library of Steuben County, IN, USA
- * Centerville-Center Township Public Library, IN, USA
- * Flora Public Library, IN, USA
- * Hagerstown - Jefferson Township Library, IN, USA
- * Howe Library, Hanover, NH, USA
- * Massachusetts Library Network Cooperative
- * Newton County Public Library, IN, USA
- * Noble County Public Library, IN, USA
- * Natural Resources Canada
- * North of Boston Library Exchange
- * Perry County Public Library, IN, USA
- * Plainfield-Guilford Township Public Library, IN, USA
- * Rodgers Memorial Library, Hudson, NH, USA
- * Statistics Canada
- * Union County Public Library, IN, USA
- * Westfield Washington Public Library, IN, USA
-
-We would also like to thank the following individuals who contributed
-code and documentations patches to this release of Evergreen:
-
- * Jason Boyer
- * Galen Charlton
- * Mark Cooper
- * Bill Erickson
- * Jason Etheridge
- * Lebbeous Fogle-Weekley
- * Jeff Godin
- * Pasi Kallinen
- * Mike Rylander
- * Dan Scott
- * Chris Sharp
- * Ben Shum
- * Remington Steed
- * Jason Stephenson
- * Yamil Suarez
- * Elliot Voris
- * Dan Wells
-
-We also thank the following organizations whose employees contributed
-patches:
-
- * Berklee College of Music
- * Bibliomation
- * Calvin College
- * Equinox Software, Inc.
- * Georgia Public Library Service
- * Indiana State Library
- * Laurentian University
- * Merrimack Valley Library Consortium
- * Pohjois-Karjalan Tietotekniikkakeskus Oy
- * Saint Louis Christian College
- * Traverse Area District Library
-
-We regret any omissions. If a contributor has been inadvertently
-missed, please open a bug at http://bugs.launchpad.net/evergreen/
-with a correction.
-
--- /dev/null
+Evergreen 2.7 Release Notes
+===========================
+:toc:
+:numbered:
+
+Upgrade notes
+-------------
+
+New Color in colors.tt2
+~~~~~~~~~~~~~~~~~~~~~~~
+A new color called _mobile_header_text_ has been added to colors.tt2. Evergreen
+sites will need to customize this color so that it fits with their catalog's
+color scheme. The color is used to define new search links that will appear in
+ _My Account_ screens when viewed on screens smaller than 600px wide. It will
+ also be used on any future text that appears in the header area of the catalog.
+
+Record Attributes Reingest Recommended
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+After this update, it is recommended that you reingest your
+bibliographic records to update the fixed field, record attribute
+indexes. This is mainly necessary to make sure that fiction books do
+not also show up as non-fiction.
+
+You can accomplish this by running the following query in your database:
+
+[source,sql]
+--------------------------------------------------------------------
+select metabib.reingest_record_attributes(id)
+from biblio.record_entry;
+--------------------------------------------------------------------
+
+
+
+New features
+------------
+
+
+
+Acquisitions
+~~~~~~~~~~~~
+
+
+
+Acquisitions speed improvements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Improvements to the rendering of the acquisitions fund selector will improve
+the speed at which the purchase order, copy grid, PO/invoice charge creator,
+and distribution formula editor load. These speed improvements will be most
+noticeable for sites that use many funds.
+
+
+
+
+
+
+Differentiate Delayed vs. Canceled Items
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Background
+++++++++++
+Canceled and delayed lineitems and copies in acquisitions are marked as
+canceled in the database. The determining factor of whether an item is
+delayed or canceled is the keep_debits flag on the cancel reason.
+
+The changes below help to differentiate between these two closely-related
+states by improving labels in the interface and providing separate counts
+for delayed vs. canceled.
+
+Changes
++++++++
+
+ * Show number canceled and number delayed in lineitem summary displays
+ ** Includes summary displays in invoices and copy grids
+ * Update stock cancel cause labels to include "Canceled:.." and
+ "Delayed:..." prefixes.
+ * When a lineitem or copy is marked as canceled, show the cancel cause
+ label in the interface instead of the bare (and misleading and non-I18N
+ friendly) string "cancelled".
+ ** Related, for non-canceled states, show a translatable string
+ representing the name of the state instead of the bare state code.
+ * Add cancel cause labels to the print PO and lineitem worksheet templates.
+
+Support Cancellation of Delayed Lineitems
++++++++++++++++++++++++++++++++++++++++++
+
+When a lineitem is marked as delayed (canceled with keep_debits == true),
+allow staff to cancel the lineitem again in the ACQ PO/Selection List interface.
+Once a lineitem is marked as truly canceled, it cannot be canceled again.
+
+
+
+
+Administration
+~~~~~~~~~~~~~~
+
+
+
+Switch to XLSX format for Excel report output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With previous versions of Evergreen, reports generated in the Excel output
+were limited to a maximum of 64,000 rows. This was a limitation due to the
+Excel format ".xls". Now, new report outputs for Excel will use format ".xlsx"
+which allows for much larger report output rows.
+
+
+
+
+
+Report Editing
+^^^^^^^^^^^^^^
+Users may now view and edit existing reports.
+
+With each report in the Reports folder view there are two new links,
+one for viewing (read-only) and one for editing. After changing a
+report, the user has the option to save the modified report
+or create a new report with the new values, in effect cloning
+the original report.
+
+When saving a changed report that has a pending run, the user
+will be warned of this and asked if they would prefer to modify the
+scheduled report or to instead save the changed values as a new
+report, leaving the original report intact.
+
+
+
+
+Reports Documentation Links and Hints
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ * Report templates support a new External URL field, which may
+ contain a link to template-specific, local documentation.
+
+ ** When set, a link to the external documentation will be
+ displayed in a new column in the template list and within
+ the report editor.
+
+ ** URL's are set in the 'Documentation URL' entry.
+
+ * Template display fields and filters support a new Field Hint
+ value. When set, hints are displayed in the report editor.
+
+ ** Values are set via the 'Change Field Hint' option along
+ the bottom of the template editor.
+
+
+
+
+
+
+Secondary Permission Groups
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The patron registration/edit screen now has an interface for adding
+secondary permission groups (profiles) to a user account. This gives
+library staff the ability to assign sets of permissions from multiple
+permission groups to a single user. For example, if you have a
+cataloger who also does acquisitions, and you have separate permission
+groups for Catalogers and Acquisitions, the new UI allows you to add
+acquisitions as a secondary perm group on the cataloger's account, thus
+granting all Acquisitions permissions to that user without changing the
+user's primary profile group.
+
+Library staff require the *CREATE_USER_GROUP_LINK* and
+*REMOVE_USER_GROUP_LINK* permissions (which already exist in Evergreen) in order
+to add or remove a user's secondary permission groups.
+
+
+
+
+
+
+Cataloging
+~~~~~~~~~~
+
+
+
+TPAC Copy View/Edit Links
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Adds 'view' and 'edit' links next to each copy in the TPAC record
+details copy grid when viewed from within the staff client. The 'edit'
+link only appears when the authenticated user has permission to edit the
+specified copy.
+
+Both links open new tabs. When the 'edit' link is used, the 'Unified
+Volume/Item Creator/Editor' org unit setting is inspected to determine
+which style of copy edit interface to display. When the 'view' link is used,
+the copy details display in the Item Status screen.
+
+
+
+
+Display "Imported As" in Vandelay Queue
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This simple new feature appears within the Cataloging *MARC Batch
+Import/Export* screens. When viewing the contents of a Vandelay queue,
+for example when inspecting a queue or right after bib imports, there is
+a new column called _Imported As_. This new column displays the
+record ID, also known as the bib number, of the bib records currently
+listed in the queue. If the bib records listed in the queue have not been
+imported yet, this column is blank until the queued records are imported.
+After import the queued records will display the assigned record ID for
+the listed bib(s).
+
+
+
+
+MARC Stream Importer
+^^^^^^^^^^^^^^^^^^^^
+
+New command line options were added to marc_stream_importer.pl for
+passing additional Vandelay import flags. Prior to this change, only
+auto-overlay-exact was supported.
+
+New options:
+
+ * --auto-overlay-exact
+ ** Overlay/merge on exact 901c matches
+ * --auto-overlay-1match
+ ** Overlay/merge when exactly one match is found
+ * --auto-overlay-best-match
+ ** Overlay/merge on best match
+ * --import-no-match
+ ** Import when no match is found
+
+Like Vandelay, these options can be combined.
+
+
+
+
+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.{nbsp}1++ may have variants
+like ++V.1++, ++Vol{nbsp}1++, or ++{nbsp}Vol.{nbsp}1++ (leading
+space).This feature will allow cataloging staff to collapse the variants into
+one value.
+
+
+
+Circulation
+~~~~~~~~~~~
+
+
+
+Change to Holds Shelf Expire Report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When limiting to Clearable Holds in the Browse Holds Shelf interface, the
+system will no longer display and clear holds expiring today. Instead, it will
+look for holds that expired before today.
+
+
+
+
+Support holds targeting and fulfillment of precats for ILL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Adds support for holds targeting and fulfillment of copy-level holds on
+pre-cat records. This feature makes integration with FulfILLment, NCIP and
+other ILL mediators easier because pre-cat copies can successfully be used for
+the ILL records.
+
+
+
+
+
+Support for a Lost and Paid Status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This feature supports a new, optional, _Lost and Paid_ status that can be used
+by sites that want to distinguish between lost items with outstanding bills and
+those that have been fully paid. A site may want to make this distinction to
+set different OPAC visibility or holdability rules for these items.
+
+If enabled, when a lost item is fully paid, the copy's status will automatically
+change to _Lost and Paid_.
+
+New setting available via the Library Settings Editor
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- Use Lost and Paid copy status (circ.use_lost_paid_copy_status)
+
+
+Client
+~~~~~~
+
+Web client preview
+^^^^^^^^^^^^^^^^^^
+
+The 2.7 release will contain a preview of web client circulation features.
+Circulation is the first step in moving all staff functions from the existing
+XULRunner-based client to a web application that will be based on AngularJS.
+
+Evergreen is moving away from the existing client because XULRunner no longer
+supports features critical to the Evergreen software, including remote XUL,
+multi-part streaming, and XML JavaScript. The new web client is expected to
+show some speed improvements, to provide comprehensive support for
+internationalization/localization, to provide good support for assistive
+technologies, to be easier to customize locally, and to be more mobile friendly.
+
+The intent of the preview is to make it easier for end users at Evergreen sites
+to try the new client, become familiar with its features, and to
+discover/report bugs that are found. Instructions to implement the web client
+can be found in the code in Open-ILS/web/js/ui/default/staff/README.install.
+These will be revised and moved to the full README for 2.7.1.
+
+OPAC
+~~~~
+
+
+
+Added Content by Record ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Template Toolkit OPAC will now load all Added Content by the Record ID, not
+just jacket images. This will allow added content providers that support it to
+load additional content by other identifiers.
+
+
+
+
+Content Cafe Added Content Update
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The OpenILS::WWW::AddedContent::ContentCafe provider has been updated to use the
+newer Content Cafe 2 API in full. With this update the ability to load content
+based on ISBN or UPC is now enabled.
+
+
+"No Image" Images
++++++++++++++++++
+With the updated code the option for displaying a "No Image" image or a 1x1
+pixel image is no longer available. Instead the Apache-level "blank image" rules
+will trigger when no image is available. The configuration option controlling
+this behavior can thus be removed from opensrf.xml entirely.
+
+
+Identifier Selection
+++++++++++++++++++++
+By default the module will prefer ISBNs over UPCs, but will request information
+for both. 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.
+
+
+
+
+More RDA 264 tag support
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The OPAC now displays RDA bib tag 264 information for Producer, Distributor,
+Manufacturer, and Copyright within a full bib record’s summary. This is in
+addition to the RDA bib tag 264 publisher information, indicator 2 equal
+to 1, that was already being displayed in previous versions of Evergreen.
+The OPAC full bib view also now contains the Schema.org copyrightYear value.
+
+Additionally, this information is now available in search results as well
+when viewing more details.
+
+
+
+
+Sitemap generator
+^^^^^^^^^^^^^^^^^
+A http://www.sitemaps.org[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.
+
+
+Bug Fixes
+---------
+
+IMPORTANT SECURITY INFORMATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A serious security flaw that allows unauthorized remote access to
+organizational unit settings is fixed in the following releases of
+Evergreen: 2.5.9, 2.6.7, and 2.7.4. All prior releases of Evergreen
+are vulnerable to exploitation of this flaw to reveal sensitive system
+information. If you are running a vulnerable release of Evergreen you
+are *strongly* encouraged to upgrade to a non-vulnerable release as
+soon as possible.
+
+Set resource limits for Clark Kent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Several parameters are now available for the reporter daemon process
+(`clark-kent.pl`) to control resource usage. These can be used to
+reduce the chances that a malformed report can cause indigestion
+on a database or reports server. The new parameters, which can be
+set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
+
+* `//reporter/setup/statement_timeout` / `--statement-timeout`
+
+Number of minutes to allow a report's underlying SQL query
+to run before it gets cancelled. Default value is
+60 minutes. If a report's query gets cancelled, the
+error_text value will be set to a valid that indicates that
+the allowed time was exceeded.
+
+* `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
+
+Number of rows permitted in the query's output before
+Clark Kent refuses to attempt to draw a graph. Default
+value is 1,000 rows.
+
+* `//reporter/setup/resultset_limit` / `--resultset-limit`
+
+If set, truncates the report's output to the specified
+number of hits. Note that it will not be apparent
+to a staff user if the report's output has been
+truncated. Default value is unlimited.
+
+The report concurrency (i.e., the number of reports that Clark
+Kent will run in parallel) can now also be controlled via
+the `opensrf.xml` setting `//reporter/setup/parallel`.
+
+
+Acknowledgments
+---------------
+The Evergreen project would like to acknowledge the following
+organizations who commissioned developments in this release of
+Evergreen:
+
+ * Bibliomation
+ * British Columbia Libraries Cooperative
+ * Central/Western Massachusetts Automated Resource Sharing
+ * Georgia Public Library Service
+ * Howe Library, Hanover, NH
+ * Massachusetts Library Network Cooperative
+ * NC Cardinal
+ * North of Boston Library Exchange
+ * Pennsylvania Integrated Library System
+ * Pioneer Library System
+ * South Carolina Library Evergreen Network Delivery System
+
+We would also like to thank the following individuals who contributed
+code and documentations patches to this release of Evergreen:
+
+ * Thomas Berezansky
+ * Jason Boyer
+ * Steven Callender
+ * Steven Chan
+ * Galen Charlton
+ * Jeff Davis
+ * Bill Erickson
+ * Jason Etheridge
+ * James Fournie
+ * Jeff Godin
+ * Blake Henderson
+ * Pasi Kallinen
+ * Victoria Lewis
+ * Kathy Lussier
+ * Terran McCanna
+ * Michele Morgan
+ * Suzanne Paterno
+ * Dan Pearl
+ * Jennifer Pringle
+ * Erica Rohlfs
+ * Mike Rylander
+ * Dan Scott
+ * Srey Seng
+ * Chris Sharp
+ * Ben Shum
+ * Robert Soulliere
+ * Remington Steed
+ * Jason Stephenson
+ * Josh Stompro
+ * Yamil Suarez
+ * Kyle Tomita
+ * Elliot Voris
+ * Dan Wells
+ * Liam Whalen
+
+We also thank the following organizations whose employees contributed
+patches:
+
+ * Berklee College of Music
+ * Bibliomation
+ * British Columbia Libraries Cooperative
+ * Calvin College
+ * Catalyst IT Services
+ * Central/Western Massachusetts Automated Resource Sharing
+ * Equinox Software, Inc.
+ * Georgia Public Library Service
+ * Indiana State Library
+ * Lake Agassiz Regional Library
+ * Laurentian University
+ * Massachusetts Library Network Cooperative
+ * Merrimack Valley Library Consortium
+ * MOBIUS
+ * Mohawk College
+ * North of Boston Library Exchange
+ * Pohjois-Karjalan Tietotekniikkakeskus Oy
+ * St. Louis Christian College
+ * Traverse Area District Library
+
+We regret any omissions. If a contributor has been inadvertently
+missed, please open a bug at http://bugs.launchpad.net/evergreen/
+with a correction.
+
+++ /dev/null
-Evergreen 2.7 Release Notes
-===========================
-:toc:
-:numbered:
-
-Upgrade notes
--------------
-
-New Color in colors.tt2
-~~~~~~~~~~~~~~~~~~~~~~~
-A new color called _mobile_header_text_ has been added to colors.tt2. Evergreen
-sites will need to customize this color so that it fits with their catalog's
-color scheme. The color is used to define new search links that will appear in
- _My Account_ screens when viewed on screens smaller than 600px wide. It will
- also be used on any future text that appears in the header area of the catalog.
-
-Record Attributes Reingest Recommended
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-After this update, it is recommended that you reingest your
-bibliographic records to update the fixed field, record attribute
-indexes. This is mainly necessary to make sure that fiction books do
-not also show up as non-fiction.
-
-You can accomplish this by running the following query in your database:
-
-[source,sql]
---------------------------------------------------------------------
-select metabib.reingest_record_attributes(id)
-from biblio.record_entry;
---------------------------------------------------------------------
-
-
-
-New features
-------------
-
-
-
-Acquisitions
-~~~~~~~~~~~~
-
-
-
-Acquisitions speed improvements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Improvements to the rendering of the acquisitions fund selector will improve
-the speed at which the purchase order, copy grid, PO/invoice charge creator,
-and distribution formula editor load. These speed improvements will be most
-noticeable for sites that use many funds.
-
-
-
-
-
-
-Differentiate Delayed vs. Canceled Items
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Background
-++++++++++
-Canceled and delayed lineitems and copies in acquisitions are marked as
-canceled in the database. The determining factor of whether an item is
-delayed or canceled is the keep_debits flag on the cancel reason.
-
-The changes below help to differentiate between these two closely-related
-states by improving labels in the interface and providing separate counts
-for delayed vs. canceled.
-
-Changes
-+++++++
-
- * Show number canceled and number delayed in lineitem summary displays
- ** Includes summary displays in invoices and copy grids
- * Update stock cancel cause labels to include "Canceled:.." and
- "Delayed:..." prefixes.
- * When a lineitem or copy is marked as canceled, show the cancel cause
- label in the interface instead of the bare (and misleading and non-I18N
- friendly) string "cancelled".
- ** Related, for non-canceled states, show a translatable string
- representing the name of the state instead of the bare state code.
- * Add cancel cause labels to the print PO and lineitem worksheet templates.
-
-Support Cancellation of Delayed Lineitems
-+++++++++++++++++++++++++++++++++++++++++
-
-When a lineitem is marked as delayed (canceled with keep_debits == true),
-allow staff to cancel the lineitem again in the ACQ PO/Selection List interface.
-Once a lineitem is marked as truly canceled, it cannot be canceled again.
-
-
-
-
-Administration
-~~~~~~~~~~~~~~
-
-
-
-Switch to XLSX format for Excel report output
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-With previous versions of Evergreen, reports generated in the Excel output
-were limited to a maximum of 64,000 rows. This was a limitation due to the
-Excel format ".xls". Now, new report outputs for Excel will use format ".xlsx"
-which allows for much larger report output rows.
-
-
-
-
-
-Report Editing
-^^^^^^^^^^^^^^
-Users may now view and edit existing reports.
-
-With each report in the Reports folder view there are two new links,
-one for viewing (read-only) and one for editing. After changing a
-report, the user has the option to save the modified report
-or create a new report with the new values, in effect cloning
-the original report.
-
-When saving a changed report that has a pending run, the user
-will be warned of this and asked if they would prefer to modify the
-scheduled report or to instead save the changed values as a new
-report, leaving the original report intact.
-
-
-
-
-Reports Documentation Links and Hints
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- * Report templates support a new External URL field, which may
- contain a link to template-specific, local documentation.
-
- ** When set, a link to the external documentation will be
- displayed in a new column in the template list and within
- the report editor.
-
- ** URL's are set in the 'Documentation URL' entry.
-
- * Template display fields and filters support a new Field Hint
- value. When set, hints are displayed in the report editor.
-
- ** Values are set via the 'Change Field Hint' option along
- the bottom of the template editor.
-
-
-
-
-
-
-Secondary Permission Groups
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The patron registration/edit screen now has an interface for adding
-secondary permission groups (profiles) to a user account. This gives
-library staff the ability to assign sets of permissions from multiple
-permission groups to a single user. For example, if you have a
-cataloger who also does acquisitions, and you have separate permission
-groups for Catalogers and Acquisitions, the new UI allows you to add
-acquisitions as a secondary perm group on the cataloger's account, thus
-granting all Acquisitions permissions to that user without changing the
-user's primary profile group.
-
-Library staff require the *CREATE_USER_GROUP_LINK* and
-*REMOVE_USER_GROUP_LINK* permissions (which already exist in Evergreen) in order
-to add or remove a user's secondary permission groups.
-
-
-
-
-
-
-Cataloging
-~~~~~~~~~~
-
-
-
-TPAC Copy View/Edit Links
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Adds 'view' and 'edit' links next to each copy in the TPAC record
-details copy grid when viewed from within the staff client. The 'edit'
-link only appears when the authenticated user has permission to edit the
-specified copy.
-
-Both links open new tabs. When the 'edit' link is used, the 'Unified
-Volume/Item Creator/Editor' org unit setting is inspected to determine
-which style of copy edit interface to display. When the 'view' link is used,
-the copy details display in the Item Status screen.
-
-
-
-
-Display "Imported As" in Vandelay Queue
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This simple new feature appears within the Cataloging *MARC Batch
-Import/Export* screens. When viewing the contents of a Vandelay queue,
-for example when inspecting a queue or right after bib imports, there is
-a new column called _Imported As_. This new column displays the
-record ID, also known as the bib number, of the bib records currently
-listed in the queue. If the bib records listed in the queue have not been
-imported yet, this column is blank until the queued records are imported.
-After import the queued records will display the assigned record ID for
-the listed bib(s).
-
-
-
-
-MARC Stream Importer
-^^^^^^^^^^^^^^^^^^^^
-
-New command line options were added to marc_stream_importer.pl for
-passing additional Vandelay import flags. Prior to this change, only
-auto-overlay-exact was supported.
-
-New options:
-
- * --auto-overlay-exact
- ** Overlay/merge on exact 901c matches
- * --auto-overlay-1match
- ** Overlay/merge when exactly one match is found
- * --auto-overlay-best-match
- ** Overlay/merge on best match
- * --import-no-match
- ** Import when no match is found
-
-Like Vandelay, these options can be combined.
-
-
-
-
-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.{nbsp}1++ may have variants
-like ++V.1++, ++Vol{nbsp}1++, or ++{nbsp}Vol.{nbsp}1++ (leading
-space).This feature will allow cataloging staff to collapse the variants into
-one value.
-
-
-
-Circulation
-~~~~~~~~~~~
-
-
-
-Change to Holds Shelf Expire Report
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When limiting to Clearable Holds in the Browse Holds Shelf interface, the
-system will no longer display and clear holds expiring today. Instead, it will
-look for holds that expired before today.
-
-
-
-
-Support holds targeting and fulfillment of precats for ILL
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Adds support for holds targeting and fulfillment of copy-level holds on
-pre-cat records. This feature makes integration with FulfILLment, NCIP and
-other ILL mediators easier because pre-cat copies can successfully be used for
-the ILL records.
-
-
-
-
-
-Support for a Lost and Paid Status
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This feature supports a new, optional, _Lost and Paid_ status that can be used
-by sites that want to distinguish between lost items with outstanding bills and
-those that have been fully paid. A site may want to make this distinction to
-set different OPAC visibility or holdability rules for these items.
-
-If enabled, when a lost item is fully paid, the copy's status will automatically
-change to _Lost and Paid_.
-
-New setting available via the Library Settings Editor
-++++++++++++++++++++++++++++++++++++++++++++++++++++++
-- Use Lost and Paid copy status (circ.use_lost_paid_copy_status)
-
-
-Client
-~~~~~~
-
-Web client preview
-^^^^^^^^^^^^^^^^^^
-
-The 2.7 release will contain a preview of web client circulation features.
-Circulation is the first step in moving all staff functions from the existing
-XULRunner-based client to a web application that will be based on AngularJS.
-
-Evergreen is moving away from the existing client because XULRunner no longer
-supports features critical to the Evergreen software, including remote XUL,
-multi-part streaming, and XML JavaScript. The new web client is expected to
-show some speed improvements, to provide comprehensive support for
-internationalization/localization, to provide good support for assistive
-technologies, to be easier to customize locally, and to be more mobile friendly.
-
-The intent of the preview is to make it easier for end users at Evergreen sites
-to try the new client, become familiar with its features, and to
-discover/report bugs that are found. Instructions to implement the web client
-can be found in the code in Open-ILS/web/js/ui/default/staff/README.install.
-These will be revised and moved to the full README for 2.7.1.
-
-OPAC
-~~~~
-
-
-
-Added Content by Record ID
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Template Toolkit OPAC will now load all Added Content by the Record ID, not
-just jacket images. This will allow added content providers that support it to
-load additional content by other identifiers.
-
-
-
-
-Content Cafe Added Content Update
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The OpenILS::WWW::AddedContent::ContentCafe provider has been updated to use the
-newer Content Cafe 2 API in full. With this update the ability to load content
-based on ISBN or UPC is now enabled.
-
-
-"No Image" Images
-+++++++++++++++++
-With the updated code the option for displaying a "No Image" image or a 1x1
-pixel image is no longer available. Instead the Apache-level "blank image" rules
-will trigger when no image is available. The configuration option controlling
-this behavior can thus be removed from opensrf.xml entirely.
-
-
-Identifier Selection
-++++++++++++++++++++
-By default the module will prefer ISBNs over UPCs, but will request information
-for both. 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.
-
-
-
-
-More RDA 264 tag support
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-The OPAC now displays RDA bib tag 264 information for Producer, Distributor,
-Manufacturer, and Copyright within a full bib record’s summary. This is in
-addition to the RDA bib tag 264 publisher information, indicator 2 equal
-to 1, that was already being displayed in previous versions of Evergreen.
-The OPAC full bib view also now contains the Schema.org copyrightYear value.
-
-Additionally, this information is now available in search results as well
-when viewing more details.
-
-
-
-
-Sitemap generator
-^^^^^^^^^^^^^^^^^
-A http://www.sitemaps.org[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.
-
-
-Bug Fixes
----------
-
-IMPORTANT SECURITY INFORMATION
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A serious security flaw that allows unauthorized remote access to
-organizational unit settings is fixed in the following releases of
-Evergreen: 2.5.9, 2.6.7, and 2.7.4. All prior releases of Evergreen
-are vulnerable to exploitation of this flaw to reveal sensitive system
-information. If you are running a vulnerable release of Evergreen you
-are *strongly* encouraged to upgrade to a non-vulnerable release as
-soon as possible.
-
-Set resource limits for Clark Kent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Several parameters are now available for the reporter daemon process
-(`clark-kent.pl`) to control resource usage. These can be used to
-reduce the chances that a malformed report can cause indigestion
-on a database or reports server. The new parameters, which can be
-set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
-
-* `//reporter/setup/statement_timeout` / `--statement-timeout`
-
-Number of minutes to allow a report's underlying SQL query
-to run before it gets cancelled. Default value is
-60 minutes. If a report's query gets cancelled, the
-error_text value will be set to a valid that indicates that
-the allowed time was exceeded.
-
-* `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
-
-Number of rows permitted in the query's output before
-Clark Kent refuses to attempt to draw a graph. Default
-value is 1,000 rows.
-
-* `//reporter/setup/resultset_limit` / `--resultset-limit`
-
-If set, truncates the report's output to the specified
-number of hits. Note that it will not be apparent
-to a staff user if the report's output has been
-truncated. Default value is unlimited.
-
-The report concurrency (i.e., the number of reports that Clark
-Kent will run in parallel) can now also be controlled via
-the `opensrf.xml` setting `//reporter/setup/parallel`.
-
-
-Acknowledgments
----------------
-The Evergreen project would like to acknowledge the following
-organizations who commissioned developments in this release of
-Evergreen:
-
- * Bibliomation
- * British Columbia Libraries Cooperative
- * Central/Western Massachusetts Automated Resource Sharing
- * Georgia Public Library Service
- * Howe Library, Hanover, NH
- * Massachusetts Library Network Cooperative
- * NC Cardinal
- * North of Boston Library Exchange
- * Pennsylvania Integrated Library System
- * Pioneer Library System
- * South Carolina Library Evergreen Network Delivery System
-
-We would also like to thank the following individuals who contributed
-code and documentations patches to this release of Evergreen:
-
- * Thomas Berezansky
- * Jason Boyer
- * Steven Callender
- * Steven Chan
- * Galen Charlton
- * Jeff Davis
- * Bill Erickson
- * Jason Etheridge
- * James Fournie
- * Jeff Godin
- * Blake Henderson
- * Pasi Kallinen
- * Victoria Lewis
- * Kathy Lussier
- * Terran McCanna
- * Michele Morgan
- * Suzanne Paterno
- * Dan Pearl
- * Jennifer Pringle
- * Erica Rohlfs
- * Mike Rylander
- * Dan Scott
- * Srey Seng
- * Chris Sharp
- * Ben Shum
- * Robert Soulliere
- * Remington Steed
- * Jason Stephenson
- * Josh Stompro
- * Yamil Suarez
- * Kyle Tomita
- * Elliot Voris
- * Dan Wells
- * Liam Whalen
-
-We also thank the following organizations whose employees contributed
-patches:
-
- * Berklee College of Music
- * Bibliomation
- * British Columbia Libraries Cooperative
- * Calvin College
- * Catalyst IT Services
- * Central/Western Massachusetts Automated Resource Sharing
- * Equinox Software, Inc.
- * Georgia Public Library Service
- * Indiana State Library
- * Lake Agassiz Regional Library
- * Laurentian University
- * Massachusetts Library Network Cooperative
- * Merrimack Valley Library Consortium
- * MOBIUS
- * Mohawk College
- * North of Boston Library Exchange
- * Pohjois-Karjalan Tietotekniikkakeskus Oy
- * St. Louis Christian College
- * Traverse Area District Library
-
-We regret any omissions. If a contributor has been inadvertently
-missed, please open a bug at http://bugs.launchpad.net/evergreen/
-with a correction.
-
--- /dev/null
+Evergreen 2.8 Release Notes
+=============================
+
+Evergreen 2.8.8
+---------------
+This release contains several bugfixes improving on Evergreen 2.8.7
+
+* Fixes a bug where phrase searching in the catalog failed when the phrase
+started or ended with punctuation.
+* Fixes a bug where changing the sort order in the public catalog to
+"relevance" could fail.
+* Silences unnecessary warnings emitted for libraries using extending grace
+periods.
+* Removes support for Debian Squeeze now that its long-term support period
+has ended.
+
+Evergreen 2.8.7
+---------------
+This release contains several bugfixes improving on Evergreen 2.8.6
+
+Acquisitions
+~~~~~~~~~~~~
+* Adds EDI Cancel Code 85 to the acquisitions cancel reason table.
+* Fixes an issue where the "Expand All" button in selection lists was not
+working.
+
+Cataloging
+~~~~~~~~~~
+* Improves sorting in holdings maintenance so that copies sort first by parts
+then by barcode.
+
+Circulation
+~~~~~~~~~~~
+* Fixes an issue where the wrong last billing type and last billing note were
+displaying for some transactions.
+* Now calculates credit payments as integers to avoid rounding errors with
+large sets of small billings.
+* Fixes an issue in the patron record where staff was unable to retrieve the
+Message Center interface after visiting the Triggered Events page and vice
+versa.
+* Now displays the short version of a title on the Place Holds screen when
+placing metabib holds to reduce instances where the wrong title/format
+displayed.
+
+OPAC
+~~~~
+* Fixes an issue where detailed search results showed parts for items that
+didn't have parts.
+* Changes the e-mail address check on password reset requests so that it is no
+longer case sensitive.
+* Fixes a problem where users were unable to navigate through multiple pages of
+their holds history.
+* Removes undefined values from ISBN and ISSN arrays to prevent empty requests
+from being sent to added content providers.
+* Fixes an issue where the kids catalog was not displaying title information
+after hold placement or after adding a title to a list.
+* Corrects the kids catalog holds notification default preferences to allow for
+SMS text messaging options.
+
+
+Miscelleneous
+~~~~~~~~~~~~~
+* Fixes an issue where the Selfcheck fines receipt templated printed all open
+billable transactions, regardless of whether it had bills associated with it.
+* Fixes an issue that prevented Selfcheck's "Print List" for holds view from
+working.
+
+Evergreen 2.8.6
+---------------
+This release contains several bugfixes improving on Evergreen 2.8.5
+
+Acquisitions / Cataloging
+~~~~~~~~~~~~~~~~~~~~~~~~~
+* Allows the Z39.50 itnerface and the acquisitions MARC Federated Search
+interface to search the UPC index of the local catalog if Z39.50 is configured
+to search that field.
+* Fixes an issue where spaces in a PO name cause the system to improperly
+process EDI response messages.
+
+Circulation
+~~~~~~~~~~~
+* Fixes a problem where the balance owed was miscalculated when a row
+was deleted from money.billing.
+* Fixes an issue where credit card payments made via PayflowPro failed because
+Evergreen does not install the PayflowPro module by default.
+* Changes credit card payment behavior so that the patron's billing address will
+be read when the patron has no mailing address. If all address fields are
+properly set by the API caller except the country and the
+patron has no addresses, the system will attempt to determine the country from
+library settings. If insufficient address data is provided, the system will
+return an invalid params Event.
+
+OPAC
+~~~~
+* Fixes an issue where the reset password link was displaying even on systems
+that had disabled the ability to reset passwords.
+* Fixes an issue where the journal type search did not work when entering it as
+the second or third input on the advanced search screen.
+
+Administration
+~~~~~~~~~~~~~~
+* Changes marc_export to only print "waiting for input" when running
+interactively.
+
+
+
+Evergreen 2.8.5
+---------------
+This release contains several bugfixes improving on Evergreen 2.8.4
+
+Acquisitions
+~~~~~~~~~~~~
+* Protects the stock acquisitions cancel reasons from deletion since they
+are required to properly handle EDI order responses.
+* Changes the copy location dropdown so that users can view and select copy
+locations owned outside the workstation branch if they have permission to do so.
+This fix also adds the copy location's owning org unit to the display.
+
+Administration
+~~~~~~~~~~~~~~
+* Allows use of more special characters, including - and +, when
+entering a library's main email address in the Organizational Units
+editor.
+* Fixes an issue where marc_export attempts to call a non-existent field
+on MARC::Record if an error occurs while exporting authority records.
+
+Cataloging
+~~~~~~~~~~
+* Fixes the mapping between copies and the target part when using "Merge
+Selected" in the Monographic Parts interface.
+* Fixes an issue with the horizontal scrollbar bar in the MARC import
+queue inspector so the focus no longer jumps to the top of the screen
+when attempting to use the scrollbar.
+* Hides the staff-client saved searches header from screen readers when
+using the public catalog in non-staff mode.
+
+Circulation
+~~~~~~~~~~~
+* When placing a hold via the staff client and clicking Advanced Hold
+Options, fixes an issue where the barcode formfield populated with the
+staff member's barcode.
+* Fixes an issue where some holds with a higher proximity were
+preferred over holds with a lower proximity because the list of
+proximities of elgible copies was sorting ASCIIbetically instead of
+numerically.
+* Adds a delete flag for monographic parts, fixes staff client errors that
+were previously caused by deleted parts, and cancels any holds attached to
+those deleted parts.
+* Fixes an internal error that appeared when trying to renew an item on the
+booking resource list through the public catalog. Users will now get a message
+saying they do not have permission to renew the item.
+
+
+Public Catalog
+~~~~~~~~~~~~~~
+* Fixes an issue where unclosed phrase searches returned zero results and
+tied up the open-ils.storage process.
+* Fixes an issue where phrase searches were ignoring modifiers used in relevance
+ranking, leading to poorly-ranked results.
+* Fixes an issue where parameters weren't properly maintained when
+searching by copy location group.
+
+Reports
+~~~~~~~
+* Adds support for UTF-8 in the Reports interface.
+
+Evergreen 2.8.4
+---------------
+This release contains several bugfixes improving on Evergreen 2.8.3
+
+Circulation
+~~~~~~~~~~~
+* Fixes an issue where transactions with checkin-generated fines that
+previously had a balance of zero were prematurely closing.
+* Fixes an issue where empty patron searches lead to heavy queries ending
+in a client error. Empty patron searches will now exit early with no results.
+* Provides validation on the patron self-registration form to prevent users
+from entering the date of birth in the wrong date format.
+
+Cataloging
+~~~~~~~~~~
+* Fixes an issue where all matches were not displaying during a Vandelay
+authority record import. The fix ensures a row is added for every authority
+record match in the Vandelay match grid, even when multiple matches refer to
+the same authority record.
+
+Preventing improper data deletion from subfield $e
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This release contains a fix for LP bug 1484281, "authority data may be
+deleted during propagation with current values of
+authority.control_set_authority_field."
+
+For more details see: https://bugs.launchpad.net/evergreen/+bug/1484281
+
+The related upgrade script from this release removes subfield $e
+in authority tags 100 and 110, but only from the Evergreen default
+"LoC" authority control set configuration. If your Evergreen system is
+set up with additional authority control sets besides the default
+"LoC" one, you will need to run the following pieces of SQL code.
+
+First verify that you have an additional control set besides the
+default of "LoC". Run the following SQL code and write down the ID
+number for your additional control set. The number will be an integer
+like 101.
+
+[source,sql]
+--------------------------------------------------------------------
+select *
+from authority.control_set
+where name != 'LoC'
+order by id
+--------------------------------------------------------------------
+
+In the following code you will need to change the two sections of
+"control_set = XYZ". Change the part labeled with the text "XYZ", with
+the ID number from the above query.
+
+If the above query displayed more than one additional authority
+control set, then you will need to run the code below once for each
+additional control set ID number.
+
+[source,sql]
+--------------------------------------------------------------------
+UPDATE authority.control_set_authority_field
+SET sf_list = REGEXP_REPLACE( sf_list, 'e', '', 'i')
+WHERE tag = '100' AND control_set = XYZ AND sf_list ILIKE '%e%';
+
+UPDATE authority.control_set_authority_field
+SET sf_list = REGEXP_REPLACE( sf_list, 'e', '', 'i')
+WHERE tag = '110' AND control_set = XYZ AND sf_list ILIKE '%e%';
+--------------------------------------------------------------------
+
+Evergreen 2.8.3
+---------------
+This release contains several bugfixes improving on Evergreen 2.8.2
+
+Circulation
+~~~~~~~~~~~
+* Restores sort order in the patron's Items Out display so that overdue items
+sort to the top.
+* Changes the behavior of the checkin API so that future backdates are
+successfully ignored.
+* Fixes a problem where amnesty mode was ignored when backdating checkins.
+* Allows SIP to honor floating copy checkin locations.
+
+Cataloging
+~~~~~~~~~~
+
+* Changes the behavior of the authority linker to now ignore $e and $4 in bib
+name headings.
+
+Acquisitions
+~~~~~~~~~~~~
+
+* Changes the behavior of the end-of-year process so that fund tags will now
+remain on propagated funds.
+* Allows staff with the CREAT_PURCHSE_ORDER permission to view distribution
+formulas, making it possible to use them for PO batch update operations.
+
+Public Catalog
+~~~~~~~~~~~~~~
+
+* Improves performance of OPAC searches using format filters.
+* Removes opac_invisible copies from consideration when displaying copies
+on the search results page.
+* Fixes a UTF8 encoding issue with the SuperCat SRU service.
+
+
+Reports
+~~~~~~~
+* Optimizes the extend_reporter.full_circ_count view to improve performance
+for sites with large datasets.
+
+
+Admin
+~~~~~
+
+* Fixes a JS TypeError that prevents stat cats from displaying in the stat cat
+editor.
+* Fixes a problem where where the Collections API would crash when encountering
+users with null card values.
+* Updates the XULRunner URL in Makefile.am, allowing makefile to continue
+building the staff client.
+* Fixes a problem where the added content handler was not properly closing
+sockets.
+* Fixes a problem where the Library Settings History was not properly
+keeping the latest five settings per org unit.
+* Expands safe token generation to include user ID in the cached data, which
+can be retrieved later for activity logging.
+* Makes xpath-based record attribute definitions work.
+
+Evergreen 2.8.2
+---------------
+
+This release contains several bugfixes improving on Evergreen 2.8.1
+
+Circulation
+~~~~~~~~~~~
+
+* Fixes an issue where a double-scan at checkin causes two holds to capture for
+the same item.
+* In patron registration, fixes a broken link in the alert informing staff that
+a patron with the same name already exists.
+* Fixes an issue where fully-paid long overdue items still appeared in the
+Other/Special Circulations window.
+* Fixes an error that appeared when staff tried to renew lost, claims returned
+or long overdue item.
+* Fixes a "Return to Record" link on the call number texting confirmation
+screen. The link previously broke in cases when the user was prompted to
+authenticate before texting.
+* Removes long overdue circs from the total items out count in My Account.
+
+Public Catalog
+~~~~~~~~~~~~~~
+
+* Changes the behavior of the "Add Rows" link on the advanced search screen
+so that it no longer opens duplicate rows.
+* Removes the Bib Call Number from the query type selector.
+* Removes publication-specific information from a metarecord search results
+page
+* Prevents the "you have permission to override some of the failed holds"
+message from appearing when the user does not have permission to override holds.
+* Removes a stray semicolon that was appearing in browse search entries.
+
+Client
+~~~~~~
+
+* Prevents security warnings in the staff client when Google Analytics is
+enabled in the catalog.
+* Adds scrollbars when necessary to the item status alternate view tab.
+
+Reports
+~~~~~~~
+
+* Fixes an issue where strings with apostrophes could no longer be used to
+filter reports.
+
+Administration
+~~~~~~~~~~~~~~
+
+* Creates a script allowing EDI Ruby dependency installation on Ubuntu 14.04.
+* Fixes compatibility issues with Debian Jessie.
+* Removes "Safe" CPAN dependency from Debian/Ubuntu Makefile.install files.
+* Removes the ability for staff to edit their own user accounts.
+* Adds an index on authority.simple_heading.record so that full table scans
+aren't needed during authority record reingest.
+
+Evergreen 2.8.1
+----------------
+This release contains several bugfixes improving on Evergreen 2.8.0.
+
+Acquisitions
+~~~~~~~~~~~~
+
+* Fixes an issue where direct charges were not disencumbered when the charge
+was removed from the PO or the PO was canceled.
+* Fixes an issue where direct charges were not calculated in the PO estimated price.
+* Refreshes the PO summary ammounts (spent, encumbered, estimated) each time
+an amount-changing event occurs.
+
+Patron message center fixes and improvements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Fixes an issue where the user didn't receive an ackowledgement after
+deleting a message.
+* Displays the unread message count in the page title for increased visibility.
+* Repositions the patron messages link to the dashboard button bar.
+* For messages that originate from public notes, adjusts the sending library to be the workstation library, not the home library of the note creator.
+* Improves styling for messages by using pre-wrap, which allows longer messages
+to wrap properly.
+* Fixes an issue where users already viewing a message cannot return to the message list by clicking on the 'Message" button in the patron dashboard.
+
+Fine generator fixes
+~~~~~~~~~~~~~~~~~~~~~
+
+* Fixes an issue where payment for a lost-then-returned item was not applied to overdues.
+* Fixes an issue where overdue fines could be doubled if both
+restore-overdue-on-lost-return and generate-new-overdues-on-lost-return
+are enabled.
+
+Clear hold shelf checkin modifier fix
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Fixes a network error that occurred when using the Clear Hold Shelf checkin modifier.
+
+Fix Crash in Collections User Balance Summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Previously a patron in collections that paid off all transactions would cause a
+crash and stop processing any balance summary file that they are supposed to
+appear in. Now user balance summaries can be created in full even if some users
+have a 0 balance.
+
+Remove the ‡biblios.net Z39.50 target from seed data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Z39.50 target at z3950.biblios.net/bibliographic has not worked
+for years, so its service definition is no longer provided in the
+seed data for new installations of Evergreen.
+
+Users of existing Evergreen systems should consider removing
+the Z39.50 definition for ‡biblios.net. This can be done from
+Admin | Server Administration | Z39.50 Servers in the staff
+client.
+
+Set resource limits for Clark Kent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Several parameters are now available for the reporter daemon process
+(`clark-kent.pl`) to control resource usage. These can be used to
+reduce the chances that a malformed report can cause indigestion
+on a database or reports server. The new parameters, which can be
+set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
+
+* `//reporter/setup/statement_timeout` / `--statement-timeout`
+
+Number of minutes to allow a report's underlying SQL query
+to run before it gets cancelled. Default value is
+60 minutes. If a report's query gets cancelled, the
+error_text value will be set to a valid that indicates that
+the allowed time was exceeded.
+
+* `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
+
+Number of rows permitted in the query's output before
+Clark Kent refuses to attempt to draw a graph. Default
+value is 1,000 rows.
+
+* `//reporter/setup/resultset_limit` / `--resultset-limit`
+
+If set, truncates the report's output to the specified
+number of hits. Note that it will not be apparent
+to a staff user if the report's output has been
+truncated. Default value is unlimited.
+
+The report concurrency (i.e., the number of reports that Clark
+Kent will run in parallel) can now also be controlled via
+the `opensrf.xml` setting `//reporter/setup/parallel`.
+
+Install purge_pending_users.srfsh to /openils/bin by default
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since purge_pending_users.srfsh is in the example crontab, it should
+be installed to the Evergreen binaries directory (typically /openils/bin)
+by default.
+
+
+Evergreen 2.8.0 Release Notes
+=============================
+:toc:
+:numbered:
+
+New Features
+------------
+
+
+
+Acquisitions
+~~~~~~~~~~~~
+
+
+
+==== Duplicate Order Detection Improvements ====
+
+Provides tools to make it more clear to staff when a purchase order or
+items on an order have been ordered before.
+
+===== Prevent Duplicate PO Names =====
+
+Staff now have the option to specify a PO name during PO creation.
+If the selected name is already in use by another PO at or below
+the ordering agency for the PO, the user is warned, the save/submit
+operations are disabled, and a link to the existing PO is display. The
+link opens the related PO in a new tab when clicked.
+
+Selecting a name which is not yet used or clearing the name field
+(which defaults upon creation to the PO ID) will clear the warning and
+re-enable the submit/save operation.
+
+Similarly, when editing a PO, if the user attempts to use a name already
+used, the user will be warned and a link to the offending PO will be
+displayed.
+
+===== Show Existing Copies =====
+
+In the select list and PO view interfaces, beside the lineitem ID #, we
+now also display the number of catalog copies already owned at or below
+the ordering agency for the bib record in question.
+
+The count does not include copies linked to the lineitem in question
+nor does it include copies that are in some form of lost, missing, or
+discard status.
+
+==== Sticky Org Unit Selector ====
+
+The Context Org Unit Selector on the Funds screen will now remember and default
+to the most-recently selected org unit. On first use, the selector will
+continue to default to the workstation org unit.
+
+
+Administration
+~~~~~~~~~~~~~~
+
+Apache Access Handler: OpenILS::WWW::AccessHandler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This 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)
+
+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 you can serve with Apache.
+
+Use Cases
++++++++++
+The general use of this module is to protect access to something else.
+Here are some examples of what you can protect:
+
+ * Apache features
+ ** Automatic Directory Indexes
+ ** Proxies
+ *** 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
+
+
+Deleted flag for copy locations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A deleted flag is now available for copy locations, allowing them to be
+"deleted" without losing statistical information for circulations in a given
+copy location. It also allows copy locations that are only used by deleted
+items to be deleted.
+
+When a copy location is deleted, it will remain in the database, but will be
+removed from display in the staff client and the catalog.
+
+
+
+
+
+New TPAC config option: Show more details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There is a new option for TPAC to show more details by default.
+
+The option to show full details as a default may be especially
+important for e-content. Valid values are 'true', 'false' and 'hide'.
+
+Setting this to 'true' shows full details by default but allows the link
+to appear for 'Show Fewer Details'. The 'hide' option shows full details
+and also suppresses the link from displaying at all.
+
+Look for "show_more_details.default" in config.tt2.
+
+
+
+
+Cataloging
+~~~~~~~~~~
+
+
+
+==== Vandelay Authority Record Match Sets ====
+
+Vandelay MARC Batch Import/Export now supports match sets for authority
+record import matching. Matches can be made against MARC tag/subfield
+entries and against a record's normalized heading + thesaurus. Internal
+identifier (901c) matches are also supported.
+
+===== UI Modifications =====
+
+ * Authority matches display the normalized heading/thesuarus for each
+ match.
+ * Item import summary is not displayed for authority queues, since
+ items cannot be imported with authority records.
+
+
+
+
+
+Circulation
+~~~~~~~~~~~
+
+
+
+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.
+
+
+
+
+Option to stop billing activity on zero-balance billed transactions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new setting is available via the Library Settings Editor to stop any billing
+activity on fully-paid lost or longoverdue transactions. When the _Do not
+change fines/fees on zero-balance LOST transaction_ setting is enabled, once a
+lost of long overdue transaction
+has been fully paid, no more lost fees will be voided or overdue fines restored
+or generated if the item is returned. The setting will reduce, though not
+eliminate, negative balances in the system.
+
+New Library Setting
++++++++++++++++++++
+ * Do not change fines/fees on zero-balance LOST transaction (circ.checkin.lost_zero_balance.do_not_change') - 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 circ.void_lost_on_checkin and/or
+circ.void_lost_proc_fee_on_checkin are enabled.
+
+
+
+
+Patron Message Center
+^^^^^^^^^^^^^^^^^^^^^
+There is now a new mechanism via which messages can be sent to
+patrons for them to read while logged into the public catalog.
+
+Patron messages can be generated in two ways: when a new public
+note is added to the patron's record, and when an A/T event
+that is configured to generate messages is processed. Three
+new default A/T event definitions are added to generate
+patron messages when a hold is canceled due to lack of a target,
+staff action, or the item expiring on the shelf.
+
+In the public catalog, patrons can read their messages, mark
+one or more messages as read or unread, or delete messages that
+they do not want to see again. The XUL staff client has a new
+menu option on the patron display, "Message Center", that allows
+staff to view messages. Messages are intentionally not meant
+to be editable by patrons or library staff.
+
+During upgrade, existing public patron notes that are marked
+public are copied over as new patron messages that are marked
+as read.
+
+There are four new fields available in the A/T event definition:
+
+ * Message Title
+ * Message Template
+ * Message Library Path
+ * Message User Path
+
+If these four fields are set, when the A/T event is processed,
+a message is generated in addition to whatever reactor is
+specified by the event definition. This means that, for example,
+an email overdue notice can also generate a message that the
+patron can view in the public catalog.
+
+
+
+
+Void Lost and Long Overdue Bills on Claims Returned
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Four new settings have been added to allow sites to void lost item and long
+overdue billings and processing fees when an item is marked as Claims Returned.
+
+New Library Settings
+++++++++++++++++++++
+ * Void lost item billing when claims returned (circ.void_lost_on_claimsreturned)
+ * Void lost item processing fee when claims returned (circ.void_lost_proc_fee_on_claimsreturned)
+ * Void long overdue item billing when claims returned (circ.void_longoverdue_on_claimsreturned)
+ * Void long overdue item processing fee when claims returned (circ.void_longoverdue_proc_fee_on_claimsreturned)
+
+
+
+Staff option to place another hold on same title
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When a hold is successful in the client, staff will now see a link
+to place another hold on the same title. This link provides some workflow
+improvement for times when staff are placing holds for multiple patrons on a
+newly-added title or when they are placing holds for book clubs.
+
+
+
+OPAC
+~~~~
+
+
+
+TPAC Discoverability Enhancements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A number of discoverability enhancements have been made to the catalog
+to better support search engines:
+
+ * Titles of catalog pages now follow a "Page title - Library name" pattern
+ to provide more specific titles in search results, bookmarks, and browser
+ tabs.
+ * The OpenSearch title now specifies the library name instead of the generic
+ "Evergreen OpenSearch" at every scope.
+ * Subject headings are now exposed as http://schema.org/about[schema:about]
+ properties instead of http://schema.org/keyword[schema:keyword].
+ * Electronic resources are now assigned a http://schema.org/url[schema:url]
+ property, and any notes or link text are assigned a
+ http://schema.org/description[schema:description] property.
+ * Given a Library of Congress relator code for 1xx and 7xx fields, we now
+ surface the URL for that relator code along with
+ the http://schema.org/contributor[schema:contributor] property to give
+ machines a better chance of understanding how the person or organization
+ actually contributed to this work.
+ * Linking out to related records:
+ ** Given an LCCN (010 field), we link to the corresponding Library of Congress
+ record using http://schema.org/sameAs[schema:sameAs].
+ ** Given an OCLC number (035 field, subfield `a` beginning with `(OCoLC)`), we
+ link to the corresponding WorldCat record using
+ http://schema.org/sameAs[schema:sameAs].
+ ** Given a URI (024 field, subfield 2 = `'uri'`), we link to the
+ corresponding OCLC Work Entity record using
+ http://schema.org/exampleOfWork[schema:exampleOfWork].
+ * The sitemap generator script now includes located URIs as well as copies
+ listed in the `asset.opac_visible_copies` materialized view, and checks
+ the children or ancestors of the requested libraries for holdings as well.
+ * Links that robots should not crawl, such as search result links, are now
+ marked with the https://support.google.com/webmasters/answer/96569?hl=en[@rel="nofollow"]
+ property.
+ * Catalog pages for record details and for library descriptions now express
+ a https://support.google.com/webmasters/answer/139066?hl=en[@rel="canonical"]
+ link to simplify the number of variations of page URLs that could otherwise
+ have been derived from different search parameters.
+ * Catalog pages that do not exist now return a proper 404 "HTTP_NOT_FOUND"
+ HTTP status code, and record detail pages for records that have been deleted
+ now return a proper 410 "HTTP_GONE" HTTP status code, instead of returning a
+ misleading 200 "OK" HTTP status code.
+ * Record detail and library pages now include http://ogp.me/[Open Graph Protocol]
+ markup.
+
+
+
+
+Add new link to My Lists in My Account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There is now a direct link to "My Lists" from the "My Account" area in the
+top upper-right part of the screen. This gives users the ability to quickly
+access their lists while logged into the catalog.
+
+
+Permalinks
+^^^^^^^^^^
+The record summary page will now offer 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.
+
+
+
+Removal of Bib Call Number Search
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The Bib Call Number Search has been removed as a default numeric search in
+the catalog. Evergreen sites that wish to restore this search to the catalog
+can add the following to the numeric_qtype menu in the numeric.tt2 file.
+
+----
+ <option value="identifier|bibcn">[% l('Bib Call Number') %]</option>
+----
+
+
+
+
+Improved styling on Text call number screen
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+New styling on the _Text call number_ screen has added highlighting to the
+displayed message, makes the font consistent with other text on the screen, and
+displays better on mobile devices.
+
+
+
+
+Bug Fixes
+---------
+
+IMPORTANT SECURITY INFORMATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A serious security flaw that allows unauthorized remote access to
+organizational unit settings is fixed in the following releases of
+Evergreen: 2.5.9, 2.6.7, and 2.7.4. All prior releases of Evergreen
+are vulnerable to exploitation of this flaw to reveal sensitive system
+information. If you are running a vulnerable release of Evergreen you
+are *strongly* encouraged to upgrade to a non-vulnerable release as
+soon as possible.
+
+
+Acknowledgments
+---------------
+The Evergreen project would like to acknowledge the following
+organizations who commissioned developments in this release of
+Evergreen:
+
+ * Central/Western Massachusetts Automated Resource Sharing
+ * Georgia Public Library Service
+ * Massachusetts Library Network Cooperative
+ * NC Cardinal
+
+We would also like to thank the following individuals who contributed
+code and documentations patches to this release of Evergreen:
+
+ * Adam Bowling
+ * Thomas Berezansky
+ * Matthew Berowski
+ * Bradley Bonner
+ * Adam Bowling
+ * Jason Boyer
+ * Kate Butler
+ * Steven Chan
+ * Galen Charlton
+ * Bill Erickson
+ * Jason Etheridge
+ * Blake Henderson
+ * Pasi Kallinen
+ * Jake Litrell
+ * Kathy Lussier
+ * Terran McCanna
+ * Christine Morgan
+ * Bill Ott
+ * Michael Peters
+ * Art Rhyno
+ * Mike Rylander
+ * Dan Scott
+ * Chris Sharp
+ * Ben Shum
+ * Remington Steed
+ * Jason Stephenson
+ * Josh Stompro
+ * Yamil Suarez
+ * Dan Wells
+ * Liam Whalen
+
+We also thank the following organizations whose employees contributed
+patches:
+
+ * Berklee College of Music
+ * Bibliomation
+ * British Columbia Libraries Cooperative
+ * Calvin College
+ * Emerald Data Networks, Inc.
+ * Equinox Software, Inc.
+ * Georgia Public Library Service
+ * Grand Rapids Public Library
+ * Indiana State Library
+ * King County Library System
+ * Laurentian University
+ * Lake Agassiz Regional Library
+ * Massachusetts Library Network Cooperative
+ * Merrimack Valley Library Consortium
+ * MOBIUS
+ * North of Boston Library Exchange
+ * Northwest Regional Library System
+ * Pohjois-Karjalan Tietotekniikkakeskus Oy
+ * Rodgers Memorial Library
+ * Sigio
+ * University of Windsor
+
+We regret any omissions. If a contributor has been inadvertantly
+missed, please open a bug at http://bugs.launchpad.net/evergreen/
+with a correction.
+
+++ /dev/null
-Evergreen 2.8 Release Notes
-=============================
-
-Evergreen 2.8.8
----------------
-This release contains several bugfixes improving on Evergreen 2.8.7
-
-* Fixes a bug where phrase searching in the catalog failed when the phrase
-started or ended with punctuation.
-* Fixes a bug where changing the sort order in the public catalog to
-"relevance" could fail.
-* Silences unnecessary warnings emitted for libraries using extending grace
-periods.
-* Removes support for Debian Squeeze now that its long-term support period
-has ended.
-
-Evergreen 2.8.7
----------------
-This release contains several bugfixes improving on Evergreen 2.8.6
-
-Acquisitions
-~~~~~~~~~~~~
-* Adds EDI Cancel Code 85 to the acquisitions cancel reason table.
-* Fixes an issue where the "Expand All" button in selection lists was not
-working.
-
-Cataloging
-~~~~~~~~~~
-* Improves sorting in holdings maintenance so that copies sort first by parts
-then by barcode.
-
-Circulation
-~~~~~~~~~~~
-* Fixes an issue where the wrong last billing type and last billing note were
-displaying for some transactions.
-* Now calculates credit payments as integers to avoid rounding errors with
-large sets of small billings.
-* Fixes an issue in the patron record where staff was unable to retrieve the
-Message Center interface after visiting the Triggered Events page and vice
-versa.
-* Now displays the short version of a title on the Place Holds screen when
-placing metabib holds to reduce instances where the wrong title/format
-displayed.
-
-OPAC
-~~~~
-* Fixes an issue where detailed search results showed parts for items that
-didn't have parts.
-* Changes the e-mail address check on password reset requests so that it is no
-longer case sensitive.
-* Fixes a problem where users were unable to navigate through multiple pages of
-their holds history.
-* Removes undefined values from ISBN and ISSN arrays to prevent empty requests
-from being sent to added content providers.
-* Fixes an issue where the kids catalog was not displaying title information
-after hold placement or after adding a title to a list.
-* Corrects the kids catalog holds notification default preferences to allow for
-SMS text messaging options.
-
-
-Miscelleneous
-~~~~~~~~~~~~~
-* Fixes an issue where the Selfcheck fines receipt templated printed all open
-billable transactions, regardless of whether it had bills associated with it.
-* Fixes an issue that prevented Selfcheck's "Print List" for holds view from
-working.
-
-Evergreen 2.8.6
----------------
-This release contains several bugfixes improving on Evergreen 2.8.5
-
-Acquisitions / Cataloging
-~~~~~~~~~~~~~~~~~~~~~~~~~
-* Allows the Z39.50 itnerface and the acquisitions MARC Federated Search
-interface to search the UPC index of the local catalog if Z39.50 is configured
-to search that field.
-* Fixes an issue where spaces in a PO name cause the system to improperly
-process EDI response messages.
-
-Circulation
-~~~~~~~~~~~
-* Fixes a problem where the balance owed was miscalculated when a row
-was deleted from money.billing.
-* Fixes an issue where credit card payments made via PayflowPro failed because
-Evergreen does not install the PayflowPro module by default.
-* Changes credit card payment behavior so that the patron's billing address will
-be read when the patron has no mailing address. If all address fields are
-properly set by the API caller except the country and the
-patron has no addresses, the system will attempt to determine the country from
-library settings. If insufficient address data is provided, the system will
-return an invalid params Event.
-
-OPAC
-~~~~
-* Fixes an issue where the reset password link was displaying even on systems
-that had disabled the ability to reset passwords.
-* Fixes an issue where the journal type search did not work when entering it as
-the second or third input on the advanced search screen.
-
-Administration
-~~~~~~~~~~~~~~
-* Changes marc_export to only print "waiting for input" when running
-interactively.
-
-
-
-Evergreen 2.8.5
----------------
-This release contains several bugfixes improving on Evergreen 2.8.4
-
-Acquisitions
-~~~~~~~~~~~~
-* Protects the stock acquisitions cancel reasons from deletion since they
-are required to properly handle EDI order responses.
-* Changes the copy location dropdown so that users can view and select copy
-locations owned outside the workstation branch if they have permission to do so.
-This fix also adds the copy location's owning org unit to the display.
-
-Administration
-~~~~~~~~~~~~~~
-* Allows use of more special characters, including - and +, when
-entering a library's main email address in the Organizational Units
-editor.
-* Fixes an issue where marc_export attempts to call a non-existent field
-on MARC::Record if an error occurs while exporting authority records.
-
-Cataloging
-~~~~~~~~~~
-* Fixes the mapping between copies and the target part when using "Merge
-Selected" in the Monographic Parts interface.
-* Fixes an issue with the horizontal scrollbar bar in the MARC import
-queue inspector so the focus no longer jumps to the top of the screen
-when attempting to use the scrollbar.
-* Hides the staff-client saved searches header from screen readers when
-using the public catalog in non-staff mode.
-
-Circulation
-~~~~~~~~~~~
-* When placing a hold via the staff client and clicking Advanced Hold
-Options, fixes an issue where the barcode formfield populated with the
-staff member's barcode.
-* Fixes an issue where some holds with a higher proximity were
-preferred over holds with a lower proximity because the list of
-proximities of elgible copies was sorting ASCIIbetically instead of
-numerically.
-* Adds a delete flag for monographic parts, fixes staff client errors that
-were previously caused by deleted parts, and cancels any holds attached to
-those deleted parts.
-* Fixes an internal error that appeared when trying to renew an item on the
-booking resource list through the public catalog. Users will now get a message
-saying they do not have permission to renew the item.
-
-
-Public Catalog
-~~~~~~~~~~~~~~
-* Fixes an issue where unclosed phrase searches returned zero results and
-tied up the open-ils.storage process.
-* Fixes an issue where phrase searches were ignoring modifiers used in relevance
-ranking, leading to poorly-ranked results.
-* Fixes an issue where parameters weren't properly maintained when
-searching by copy location group.
-
-Reports
-~~~~~~~
-* Adds support for UTF-8 in the Reports interface.
-
-Evergreen 2.8.4
----------------
-This release contains several bugfixes improving on Evergreen 2.8.3
-
-Circulation
-~~~~~~~~~~~
-* Fixes an issue where transactions with checkin-generated fines that
-previously had a balance of zero were prematurely closing.
-* Fixes an issue where empty patron searches lead to heavy queries ending
-in a client error. Empty patron searches will now exit early with no results.
-* Provides validation on the patron self-registration form to prevent users
-from entering the date of birth in the wrong date format.
-
-Cataloging
-~~~~~~~~~~
-* Fixes an issue where all matches were not displaying during a Vandelay
-authority record import. The fix ensures a row is added for every authority
-record match in the Vandelay match grid, even when multiple matches refer to
-the same authority record.
-
-Preventing improper data deletion from subfield $e
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This release contains a fix for LP bug 1484281, "authority data may be
-deleted during propagation with current values of
-authority.control_set_authority_field."
-
-For more details see: https://bugs.launchpad.net/evergreen/+bug/1484281
-
-The related upgrade script from this release removes subfield $e
-in authority tags 100 and 110, but only from the Evergreen default
-"LoC" authority control set configuration. If your Evergreen system is
-set up with additional authority control sets besides the default
-"LoC" one, you will need to run the following pieces of SQL code.
-
-First verify that you have an additional control set besides the
-default of "LoC". Run the following SQL code and write down the ID
-number for your additional control set. The number will be an integer
-like 101.
-
-[source,sql]
---------------------------------------------------------------------
-select *
-from authority.control_set
-where name != 'LoC'
-order by id
---------------------------------------------------------------------
-
-In the following code you will need to change the two sections of
-"control_set = XYZ". Change the part labeled with the text "XYZ", with
-the ID number from the above query.
-
-If the above query displayed more than one additional authority
-control set, then you will need to run the code below once for each
-additional control set ID number.
-
-[source,sql]
---------------------------------------------------------------------
-UPDATE authority.control_set_authority_field
-SET sf_list = REGEXP_REPLACE( sf_list, 'e', '', 'i')
-WHERE tag = '100' AND control_set = XYZ AND sf_list ILIKE '%e%';
-
-UPDATE authority.control_set_authority_field
-SET sf_list = REGEXP_REPLACE( sf_list, 'e', '', 'i')
-WHERE tag = '110' AND control_set = XYZ AND sf_list ILIKE '%e%';
---------------------------------------------------------------------
-
-Evergreen 2.8.3
----------------
-This release contains several bugfixes improving on Evergreen 2.8.2
-
-Circulation
-~~~~~~~~~~~
-* Restores sort order in the patron's Items Out display so that overdue items
-sort to the top.
-* Changes the behavior of the checkin API so that future backdates are
-successfully ignored.
-* Fixes a problem where amnesty mode was ignored when backdating checkins.
-* Allows SIP to honor floating copy checkin locations.
-
-Cataloging
-~~~~~~~~~~
-
-* Changes the behavior of the authority linker to now ignore $e and $4 in bib
-name headings.
-
-Acquisitions
-~~~~~~~~~~~~
-
-* Changes the behavior of the end-of-year process so that fund tags will now
-remain on propagated funds.
-* Allows staff with the CREAT_PURCHSE_ORDER permission to view distribution
-formulas, making it possible to use them for PO batch update operations.
-
-Public Catalog
-~~~~~~~~~~~~~~
-
-* Improves performance of OPAC searches using format filters.
-* Removes opac_invisible copies from consideration when displaying copies
-on the search results page.
-* Fixes a UTF8 encoding issue with the SuperCat SRU service.
-
-
-Reports
-~~~~~~~
-* Optimizes the extend_reporter.full_circ_count view to improve performance
-for sites with large datasets.
-
-
-Admin
-~~~~~
-
-* Fixes a JS TypeError that prevents stat cats from displaying in the stat cat
-editor.
-* Fixes a problem where where the Collections API would crash when encountering
-users with null card values.
-* Updates the XULRunner URL in Makefile.am, allowing makefile to continue
-building the staff client.
-* Fixes a problem where the added content handler was not properly closing
-sockets.
-* Fixes a problem where the Library Settings History was not properly
-keeping the latest five settings per org unit.
-* Expands safe token generation to include user ID in the cached data, which
-can be retrieved later for activity logging.
-* Makes xpath-based record attribute definitions work.
-
-Evergreen 2.8.2
----------------
-
-This release contains several bugfixes improving on Evergreen 2.8.1
-
-Circulation
-~~~~~~~~~~~
-
-* Fixes an issue where a double-scan at checkin causes two holds to capture for
-the same item.
-* In patron registration, fixes a broken link in the alert informing staff that
-a patron with the same name already exists.
-* Fixes an issue where fully-paid long overdue items still appeared in the
-Other/Special Circulations window.
-* Fixes an error that appeared when staff tried to renew lost, claims returned
-or long overdue item.
-* Fixes a "Return to Record" link on the call number texting confirmation
-screen. The link previously broke in cases when the user was prompted to
-authenticate before texting.
-* Removes long overdue circs from the total items out count in My Account.
-
-Public Catalog
-~~~~~~~~~~~~~~
-
-* Changes the behavior of the "Add Rows" link on the advanced search screen
-so that it no longer opens duplicate rows.
-* Removes the Bib Call Number from the query type selector.
-* Removes publication-specific information from a metarecord search results
-page
-* Prevents the "you have permission to override some of the failed holds"
-message from appearing when the user does not have permission to override holds.
-* Removes a stray semicolon that was appearing in browse search entries.
-
-Client
-~~~~~~
-
-* Prevents security warnings in the staff client when Google Analytics is
-enabled in the catalog.
-* Adds scrollbars when necessary to the item status alternate view tab.
-
-Reports
-~~~~~~~
-
-* Fixes an issue where strings with apostrophes could no longer be used to
-filter reports.
-
-Administration
-~~~~~~~~~~~~~~
-
-* Creates a script allowing EDI Ruby dependency installation on Ubuntu 14.04.
-* Fixes compatibility issues with Debian Jessie.
-* Removes "Safe" CPAN dependency from Debian/Ubuntu Makefile.install files.
-* Removes the ability for staff to edit their own user accounts.
-* Adds an index on authority.simple_heading.record so that full table scans
-aren't needed during authority record reingest.
-
-Evergreen 2.8.1
-----------------
-This release contains several bugfixes improving on Evergreen 2.8.0.
-
-Acquisitions
-~~~~~~~~~~~~
-
-* Fixes an issue where direct charges were not disencumbered when the charge
-was removed from the PO or the PO was canceled.
-* Fixes an issue where direct charges were not calculated in the PO estimated price.
-* Refreshes the PO summary ammounts (spent, encumbered, estimated) each time
-an amount-changing event occurs.
-
-Patron message center fixes and improvements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* Fixes an issue where the user didn't receive an ackowledgement after
-deleting a message.
-* Displays the unread message count in the page title for increased visibility.
-* Repositions the patron messages link to the dashboard button bar.
-* For messages that originate from public notes, adjusts the sending library to be the workstation library, not the home library of the note creator.
-* Improves styling for messages by using pre-wrap, which allows longer messages
-to wrap properly.
-* Fixes an issue where users already viewing a message cannot return to the message list by clicking on the 'Message" button in the patron dashboard.
-
-Fine generator fixes
-~~~~~~~~~~~~~~~~~~~~~
-
-* Fixes an issue where payment for a lost-then-returned item was not applied to overdues.
-* Fixes an issue where overdue fines could be doubled if both
-restore-overdue-on-lost-return and generate-new-overdues-on-lost-return
-are enabled.
-
-Clear hold shelf checkin modifier fix
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fixes a network error that occurred when using the Clear Hold Shelf checkin modifier.
-
-Fix Crash in Collections User Balance Summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Previously a patron in collections that paid off all transactions would cause a
-crash and stop processing any balance summary file that they are supposed to
-appear in. Now user balance summaries can be created in full even if some users
-have a 0 balance.
-
-Remove the ‡biblios.net Z39.50 target from seed data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The Z39.50 target at z3950.biblios.net/bibliographic has not worked
-for years, so its service definition is no longer provided in the
-seed data for new installations of Evergreen.
-
-Users of existing Evergreen systems should consider removing
-the Z39.50 definition for ‡biblios.net. This can be done from
-Admin | Server Administration | Z39.50 Servers in the staff
-client.
-
-Set resource limits for Clark Kent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Several parameters are now available for the reporter daemon process
-(`clark-kent.pl`) to control resource usage. These can be used to
-reduce the chances that a malformed report can cause indigestion
-on a database or reports server. The new parameters, which can be
-set in `opensrf.xml` or as command-line switches for `clark-kent.pl` are
-
-* `//reporter/setup/statement_timeout` / `--statement-timeout`
-
-Number of minutes to allow a report's underlying SQL query
-to run before it gets cancelled. Default value is
-60 minutes. If a report's query gets cancelled, the
-error_text value will be set to a valid that indicates that
-the allowed time was exceeded.
-
-* `//reporter/setup/max_rows_for_charts` / `--max-rows-for-charts`
-
-Number of rows permitted in the query's output before
-Clark Kent refuses to attempt to draw a graph. Default
-value is 1,000 rows.
-
-* `//reporter/setup/resultset_limit` / `--resultset-limit`
-
-If set, truncates the report's output to the specified
-number of hits. Note that it will not be apparent
-to a staff user if the report's output has been
-truncated. Default value is unlimited.
-
-The report concurrency (i.e., the number of reports that Clark
-Kent will run in parallel) can now also be controlled via
-the `opensrf.xml` setting `//reporter/setup/parallel`.
-
-Install purge_pending_users.srfsh to /openils/bin by default
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Since purge_pending_users.srfsh is in the example crontab, it should
-be installed to the Evergreen binaries directory (typically /openils/bin)
-by default.
-
-
-Evergreen 2.8.0 Release Notes
-=============================
-:toc:
-:numbered:
-
-New Features
-------------
-
-
-
-Acquisitions
-~~~~~~~~~~~~
-
-
-
-==== Duplicate Order Detection Improvements ====
-
-Provides tools to make it more clear to staff when a purchase order or
-items on an order have been ordered before.
-
-===== Prevent Duplicate PO Names =====
-
-Staff now have the option to specify a PO name during PO creation.
-If the selected name is already in use by another PO at or below
-the ordering agency for the PO, the user is warned, the save/submit
-operations are disabled, and a link to the existing PO is display. The
-link opens the related PO in a new tab when clicked.
-
-Selecting a name which is not yet used or clearing the name field
-(which defaults upon creation to the PO ID) will clear the warning and
-re-enable the submit/save operation.
-
-Similarly, when editing a PO, if the user attempts to use a name already
-used, the user will be warned and a link to the offending PO will be
-displayed.
-
-===== Show Existing Copies =====
-
-In the select list and PO view interfaces, beside the lineitem ID #, we
-now also display the number of catalog copies already owned at or below
-the ordering agency for the bib record in question.
-
-The count does not include copies linked to the lineitem in question
-nor does it include copies that are in some form of lost, missing, or
-discard status.
-
-==== Sticky Org Unit Selector ====
-
-The Context Org Unit Selector on the Funds screen will now remember and default
-to the most-recently selected org unit. On first use, the selector will
-continue to default to the workstation org unit.
-
-
-Administration
-~~~~~~~~~~~~~~
-
-Apache Access Handler: OpenILS::WWW::AccessHandler
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-This 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)
-
-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 you can serve with Apache.
-
-Use Cases
-+++++++++
-The general use of this module is to protect access to something else.
-Here are some examples of what you can protect:
-
- * Apache features
- ** Automatic Directory Indexes
- ** Proxies
- *** 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
-
-
-Deleted flag for copy locations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A deleted flag is now available for copy locations, allowing them to be
-"deleted" without losing statistical information for circulations in a given
-copy location. It also allows copy locations that are only used by deleted
-items to be deleted.
-
-When a copy location is deleted, it will remain in the database, but will be
-removed from display in the staff client and the catalog.
-
-
-
-
-
-New TPAC config option: Show more details
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There is a new option for TPAC to show more details by default.
-
-The option to show full details as a default may be especially
-important for e-content. Valid values are 'true', 'false' and 'hide'.
-
-Setting this to 'true' shows full details by default but allows the link
-to appear for 'Show Fewer Details'. The 'hide' option shows full details
-and also suppresses the link from displaying at all.
-
-Look for "show_more_details.default" in config.tt2.
-
-
-
-
-Cataloging
-~~~~~~~~~~
-
-
-
-==== Vandelay Authority Record Match Sets ====
-
-Vandelay MARC Batch Import/Export now supports match sets for authority
-record import matching. Matches can be made against MARC tag/subfield
-entries and against a record's normalized heading + thesaurus. Internal
-identifier (901c) matches are also supported.
-
-===== UI Modifications =====
-
- * Authority matches display the normalized heading/thesuarus for each
- match.
- * Item import summary is not displayed for authority queues, since
- items cannot be imported with authority records.
-
-
-
-
-
-Circulation
-~~~~~~~~~~~
-
-
-
-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.
-
-
-
-
-Option to stop billing activity on zero-balance billed transactions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new setting is available via the Library Settings Editor to stop any billing
-activity on fully-paid lost or longoverdue transactions. When the _Do not
-change fines/fees on zero-balance LOST transaction_ setting is enabled, once a
-lost of long overdue transaction
-has been fully paid, no more lost fees will be voided or overdue fines restored
-or generated if the item is returned. The setting will reduce, though not
-eliminate, negative balances in the system.
-
-New Library Setting
-+++++++++++++++++++
- * Do not change fines/fees on zero-balance LOST transaction (circ.checkin.lost_zero_balance.do_not_change') - 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 circ.void_lost_on_checkin and/or
-circ.void_lost_proc_fee_on_checkin are enabled.
-
-
-
-
-Patron Message Center
-^^^^^^^^^^^^^^^^^^^^^
-There is now a new mechanism via which messages can be sent to
-patrons for them to read while logged into the public catalog.
-
-Patron messages can be generated in two ways: when a new public
-note is added to the patron's record, and when an A/T event
-that is configured to generate messages is processed. Three
-new default A/T event definitions are added to generate
-patron messages when a hold is canceled due to lack of a target,
-staff action, or the item expiring on the shelf.
-
-In the public catalog, patrons can read their messages, mark
-one or more messages as read or unread, or delete messages that
-they do not want to see again. The XUL staff client has a new
-menu option on the patron display, "Message Center", that allows
-staff to view messages. Messages are intentionally not meant
-to be editable by patrons or library staff.
-
-During upgrade, existing public patron notes that are marked
-public are copied over as new patron messages that are marked
-as read.
-
-There are four new fields available in the A/T event definition:
-
- * Message Title
- * Message Template
- * Message Library Path
- * Message User Path
-
-If these four fields are set, when the A/T event is processed,
-a message is generated in addition to whatever reactor is
-specified by the event definition. This means that, for example,
-an email overdue notice can also generate a message that the
-patron can view in the public catalog.
-
-
-
-
-Void Lost and Long Overdue Bills on Claims Returned
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Four new settings have been added to allow sites to void lost item and long
-overdue billings and processing fees when an item is marked as Claims Returned.
-
-New Library Settings
-++++++++++++++++++++
- * Void lost item billing when claims returned (circ.void_lost_on_claimsreturned)
- * Void lost item processing fee when claims returned (circ.void_lost_proc_fee_on_claimsreturned)
- * Void long overdue item billing when claims returned (circ.void_longoverdue_on_claimsreturned)
- * Void long overdue item processing fee when claims returned (circ.void_longoverdue_proc_fee_on_claimsreturned)
-
-
-
-Staff option to place another hold on same title
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When a hold is successful in the client, staff will now see a link
-to place another hold on the same title. This link provides some workflow
-improvement for times when staff are placing holds for multiple patrons on a
-newly-added title or when they are placing holds for book clubs.
-
-
-
-OPAC
-~~~~
-
-
-
-TPAC Discoverability Enhancements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A number of discoverability enhancements have been made to the catalog
-to better support search engines:
-
- * Titles of catalog pages now follow a "Page title - Library name" pattern
- to provide more specific titles in search results, bookmarks, and browser
- tabs.
- * The OpenSearch title now specifies the library name instead of the generic
- "Evergreen OpenSearch" at every scope.
- * Subject headings are now exposed as http://schema.org/about[schema:about]
- properties instead of http://schema.org/keyword[schema:keyword].
- * Electronic resources are now assigned a http://schema.org/url[schema:url]
- property, and any notes or link text are assigned a
- http://schema.org/description[schema:description] property.
- * Given a Library of Congress relator code for 1xx and 7xx fields, we now
- surface the URL for that relator code along with
- the http://schema.org/contributor[schema:contributor] property to give
- machines a better chance of understanding how the person or organization
- actually contributed to this work.
- * Linking out to related records:
- ** Given an LCCN (010 field), we link to the corresponding Library of Congress
- record using http://schema.org/sameAs[schema:sameAs].
- ** Given an OCLC number (035 field, subfield `a` beginning with `(OCoLC)`), we
- link to the corresponding WorldCat record using
- http://schema.org/sameAs[schema:sameAs].
- ** Given a URI (024 field, subfield 2 = `'uri'`), we link to the
- corresponding OCLC Work Entity record using
- http://schema.org/exampleOfWork[schema:exampleOfWork].
- * The sitemap generator script now includes located URIs as well as copies
- listed in the `asset.opac_visible_copies` materialized view, and checks
- the children or ancestors of the requested libraries for holdings as well.
- * Links that robots should not crawl, such as search result links, are now
- marked with the https://support.google.com/webmasters/answer/96569?hl=en[@rel="nofollow"]
- property.
- * Catalog pages for record details and for library descriptions now express
- a https://support.google.com/webmasters/answer/139066?hl=en[@rel="canonical"]
- link to simplify the number of variations of page URLs that could otherwise
- have been derived from different search parameters.
- * Catalog pages that do not exist now return a proper 404 "HTTP_NOT_FOUND"
- HTTP status code, and record detail pages for records that have been deleted
- now return a proper 410 "HTTP_GONE" HTTP status code, instead of returning a
- misleading 200 "OK" HTTP status code.
- * Record detail and library pages now include http://ogp.me/[Open Graph Protocol]
- markup.
-
-
-
-
-Add new link to My Lists in My Account
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There is now a direct link to "My Lists" from the "My Account" area in the
-top upper-right part of the screen. This gives users the ability to quickly
-access their lists while logged into the catalog.
-
-
-Permalinks
-^^^^^^^^^^
-The record summary page will now offer 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.
-
-
-
-Removal of Bib Call Number Search
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Bib Call Number Search has been removed as a default numeric search in
-the catalog. Evergreen sites that wish to restore this search to the catalog
-can add the following to the numeric_qtype menu in the numeric.tt2 file.
-
-----
- <option value="identifier|bibcn">[% l('Bib Call Number') %]</option>
-----
-
-
-
-
-Improved styling on Text call number screen
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-New styling on the _Text call number_ screen has added highlighting to the
-displayed message, makes the font consistent with other text on the screen, and
-displays better on mobile devices.
-
-
-
-
-Bug Fixes
----------
-
-IMPORTANT SECURITY INFORMATION
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A serious security flaw that allows unauthorized remote access to
-organizational unit settings is fixed in the following releases of
-Evergreen: 2.5.9, 2.6.7, and 2.7.4. All prior releases of Evergreen
-are vulnerable to exploitation of this flaw to reveal sensitive system
-information. If you are running a vulnerable release of Evergreen you
-are *strongly* encouraged to upgrade to a non-vulnerable release as
-soon as possible.
-
-
-Acknowledgments
----------------
-The Evergreen project would like to acknowledge the following
-organizations who commissioned developments in this release of
-Evergreen:
-
- * Central/Western Massachusetts Automated Resource Sharing
- * Georgia Public Library Service
- * Massachusetts Library Network Cooperative
- * NC Cardinal
-
-We would also like to thank the following individuals who contributed
-code and documentations patches to this release of Evergreen:
-
- * Adam Bowling
- * Thomas Berezansky
- * Matthew Berowski
- * Bradley Bonner
- * Adam Bowling
- * Jason Boyer
- * Kate Butler
- * Steven Chan
- * Galen Charlton
- * Bill Erickson
- * Jason Etheridge
- * Blake Henderson
- * Pasi Kallinen
- * Jake Litrell
- * Kathy Lussier
- * Terran McCanna
- * Christine Morgan
- * Bill Ott
- * Michael Peters
- * Art Rhyno
- * Mike Rylander
- * Dan Scott
- * Chris Sharp
- * Ben Shum
- * Remington Steed
- * Jason Stephenson
- * Josh Stompro
- * Yamil Suarez
- * Dan Wells
- * Liam Whalen
-
-We also thank the following organizations whose employees contributed
-patches:
-
- * Berklee College of Music
- * Bibliomation
- * British Columbia Libraries Cooperative
- * Calvin College
- * Emerald Data Networks, Inc.
- * Equinox Software, Inc.
- * Georgia Public Library Service
- * Grand Rapids Public Library
- * Indiana State Library
- * King County Library System
- * Laurentian University
- * Lake Agassiz Regional Library
- * Massachusetts Library Network Cooperative
- * Merrimack Valley Library Consortium
- * MOBIUS
- * North of Boston Library Exchange
- * Northwest Regional Library System
- * Pohjois-Karjalan Tietotekniikkakeskus Oy
- * Rodgers Memorial Library
- * Sigio
- * University of Windsor
-
-We regret any omissions. If a contributor has been inadvertantly
-missed, please open a bug at http://bugs.launchpad.net/evergreen/
-with a correction.
-
--- /dev/null
+Evergreen 2.9 Release Notes
+===========================
+:toc:
+:numbered:
+
+Evergreen 2.9.8
+---------------
+This release contains several bugfixes improving on Evergreen 2.9.7
+
+* When adding a price to the Acquisitions Brief Record price field, it will
+now propogate to the lineitem estimated price field.
+* Declares UTF-8 encoding when printing from the catalog to resolve issues
+where non_ASCII characters printed incorrectly in some browsers.
+* Fixes an issue where the circ module sometimes skipped over booking logic
+even when booking was running on a system.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed code,
+testing and documentation patches to the 2.9.8 point release of
+Evergreen:
+
+* Bill Erickson
+* Mike Rylander
+* Dan Scott
+
+Evergreen 2.9.7
+---------------
+This release contains several bugfixes improving on Evergreen 2.9.6
+
+* The claims never checked out counter on the patron record is now
+ incremented correctly when marking a lost loan as
+ claims-never-checked-out.
+* When a transit is canceled, the copy's status is changed only
+ if its status was previously "In Transit".
+* Retrieving records with embedded holdings via SRU and Z39.50 is now
+ faster.
+* The hold status message in the public catalog now uses
+ better grammar.
+* The error message displayed when a patron attempts to place
+ a hold but is prevented from doing so due to policy reasons
+ is now more likely to be useful
+* The public catalog now draws the edition statement only
+ from the 250 field; it no longer tries to check the 534
+ and 775 fields.
+* Embedded schema.org microdata now uses "offeredBy" rather
+ than "seller".
+* The ContentCafe added content plugin now handles the "fake"
+ ISBNs that Baker and Taylor assigns to media items.
+* Attempting to renew a rental or deposit item in the public
+ catalog no longer causes an internal server errorr.
+* Various format icons now have transparent backgrounds (as opposed
+ to white).
+* The staff client will no longer wait indefinitely for Novelist
+ to supply added content, improving its responsiveness.
+* A few additional strings are now marked as translatable.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed code,
+testing and documentation patches to the 2.9.6 point release of
+Evergreen:
+
+* Thomas Berezansky
+* Jason Boyer
+* Galen Charlton
+* Jeff Davis
+* Blake Graham-Henderson
+* Jim Keenan
+* Kathy Lussier
+* Mike Rylander
+* Dan Scott
+* Ben Shum
+* Remington Steed
+* Jason Stephenson
+* Josh Stompro
+* Yamil Suarez
+
+Evergreen 2.9.6
+---------------
+This release contains several bugfixes improving on Evergreen 2.9.5
+
+* Fixes a bug where Action Triggers could select an inactive event definition
+when running.
+* Fixes an issue where previously-checked-out items did not display in
+metarecord searches when the Tag Circulated Items Library Setting is enabled.
+* Fixes an error that occurred when the system attempted to display a translated
+string for the "Has Local Copy" hold placement error message.
+* Fixes an issue where the Show More/Show Fewer Details button didn't work in
+catalogs that default to showing more details.
+* Removes Social Security Number as a stock patron identification type for
+new installations. This fix does not change patron identification types for
+existing Evergreen systems.
+* Adds two missing link fields (patron profile and patron home library) to
+the fm_idl.xml for the Combined Active and Aged Circulations (combcirc)
+reporter source.
+* Adds a performance improvement for the "Clear Holds Shelf" checkin modifier.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed
+code, testing and documentation patches to the 2.9.6 point release of Evergreen:
+
+* Galen Charlton
+* Codey Kolasinski
+* Jeanette Lundgren
+* Kathy Lussier
+* Terran McCanna
+* Michele Morgan
+* Jason Stephenson
+* Josh Stompro
+
+Evergreen 2.9.5
+---------------
+This release contains several bugixes improving on Evergreen 2.9.4
+
+* Emails sent using the Action Trigger SendEmail reactor now always MIME-encode
+the From, To, Subject, Bcc, Cc, Reply-To, and Sender headers. As a consequence,
+non-ASCII character in those fields are more likely to be displayed correctly
+in email clients.
+* Fixes the responsive view of the My Account Items Out screen so that _Title_
+and _Author_ are now in separate columns.
+* Fixes an incorrect link for the MVF field definition and adds a new link to
+BRE in fm_IDL.xml.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed
+code and documentation patches to the 2.9.5 point release of Evergreen:
+
+* Blake Henderson
+* Pasi Kallinen
+* Dan Scott
+* Dan Wells
+
+We also thank the following organizations whose employees contributed
+patches:
+
+* Calvin College
+* Laurentian University
+* MOBIUS
+* Pohjois-Karjalan Tietotekniikkakeskus Oy
+
+Evergreen 2.9.4
+---------------
+This release contains several bugfixes improving on Evergreen 2.9.3
+
+* Fixes a bug where phrase searching in the catalog failed when the phrase
+started or ended with punctuation.
+* Fixes a bug where changing the sort order in the public catalog to
+"relevance" could fail.
+* Fixes a bug that prevented users from recreating a monograph part that
+had previously been deleted.
+* Silences unnecessary warnings emitted for libraries using extending grace
+periods.
+* Removes support for Debian Squeeze now that its long-term support period
+has ended.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed
+code and documentation patches to the 2.9.4 point release of Evergreen:
+
+* Jason Boyer
+* Steve Callender
+* Galen Charlton
+* Mike Rylander
+* Yamil Suarez
+
+We also thank the following organizations whose employees contributed
+patches:
+
+* Berklee College of Music
+* Equinox Software, Inc.
+* Evergreen Indiana
+
+
+Evergreen 2.9.3
+---------------
+This release contains several bugfixes improving on Evergreen 2.9.2.
+
+Acquisitions
+~~~~~~~~~~~~
+* Adds EDI Cancel Code 85 to the acquisitions cancel reason table.
+* Fixes an issue where the "Expand All" button in selection lists was not
+working.
+* Fixes an issue where deletable reasons from the acquisitions Cancel Reasons
+table could not be deleted.
+
+Cataloging
+~~~~~~~~~~
+* Improves sorting in holdings maintenance so that copies sort first by parts
+then by barcode.
+
+Circulation
+~~~~~~~~~~~
+* Fixes an issue where the wrong last billing type and last billing note were
+displaying for some transactions.
+* Now calculates credit payments as integers to avoid rounding errors with
+large sets of small billings.
+* Fixes an issue in the patron record where staff was unable to retrieve the
+Message Center interface after visiting the Triggered Events page and vice
+versa.
+* Now displays the short version of a title on the Place Holds screen when
+placing metabib holds to reduce instances where the wrong title/format
+displayed.
+
+OPAC
+~~~~
+* Fixes an issue where detailed search results showed parts for items that
+didn't have parts.
+* Changes the e-mail address check on password reset requests so that it is no
+longer case sensitive.
+* Fixes a problem where users were unable to navigate through multiple pages of
+their holds history.
+* Removes undefined values from ISBN and ISSN arrays to prevent empty requests
+from being sent to added content providers.
+* Fixes an issue where the kids catalog was not displaying title information
+after hold placement or after adding a title to a list.
+* Corrects the kids catalog holds notification default preferences to allow for
+SMS text messaging options.
+
+
+Miscelleneous
+~~~~~~~~~~~~~
+* Modifies the way SIP2 clients parse dates so that a patron's date of birth is
+returned correctly.
+* Fixes an issue where the Selfcheck fines receipt templated printed all open
+billable transactions, regardless of whether it had bills associated with it.
+* Fixes an issue that prevented Selfcheck's "Print List" for holds view from
+working.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed
+code and documentation patches to the 2.9.3 point release of Evergreen:
+
+* Thomas Berezansky
+* Jason Boyer
+* Galen Charlton
+* Bill Erickson
+* Blake Henderson
+* Terran McCanna
+* Chris Sharp
+* Remington Steed
+* Jason Stephenson
+* Josh Stompro
+* Dan Wells
+
+
+
+We also thank the following organizations whose employees contributed
+patches:
+
+* Calvin College
+* Equinox Software, Inc.
+* Evergreen Indiana
+* Georgia Public Library Service
+* King County Library System
+* Lake Agassiz Regional Library
+* Merrimack Valley Library Consortium
+* MOBIUS
+* Northwest Regional Library System
+
+Evergreen 2.9.2
+---------------
+This release contains several bugfixes improving on Evergreen 2.9.1.
+
+Acquisitions / Cataloging
+~~~~~~~~~~~~~~~~~~~~~~~~~
+* Allows the Z39.50 itnerface and the acquisitions MARC Federated Search
+interface to search the UPC index of the local catalog if Z39.50 is configured
+to search that field.
+* Fixes an issue where spaces in a PO name cause the system to improperly
+process EDI response messages.
+
+Circulation
+~~~~~~~~~~~
+* Fixes a problem where the balance owed was miscalculated when a row
+was deleted from money.billing.
+* Fixes an issue where credit card payments made via PayflowPro failed because
+Evergreen does not install the PayflowPro module by default.
+* Changes credit card payment behavior so that the patron's billing address will
+be read when the patron has no mailing address. If all address fields are
+properly set by the API caller except the country and the
+patron has no addresses, the system will attempt to determine the country from
+library settings. If insufficient address data is provided, the system will
+return an invalid params Event.
+* Modifies the reasons for various void/adjust events to more accurately reflect
+the reason why a fine/fee was removed from a patron's record.
+
+OPAC
+~~~~
+* Fixes an issue where the reset password link was displaying even on systems
+that had disabled the ability to reset passwords.
+* Fixes an issue where the journal type search did not work when entering it as
+the second or third input on the advanced search screen.
+* Fixes an issue where catalog translations were broken by creating separate
+directories for the catalog and web staff client translations.
+
+Administration
+~~~~~~~~~~~~~~
+* Changes marc_export to only print "waiting for input" when running
+interactively.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed
+code and documentation patches to the 2.9.2 point release of Evergreen:
+
+* Galen Charlton
+* Bill Erickson
+* Blake Henderson
+* Mike Rylander
+* Ben Shum
+* Jason Stephenson
+* Dan Wells
+
+We also thank the following organizations whose employees contributed
+patches:
+
+* Calvin College
+* Equinox Software, Inc.
+* King County Library System
+* Merrimack Valley Library Consortium
+* MOBIUS
+
+Evergreen 2.9.1
+----------------
+This release contains several bugfixes improving on Evergreen 2.9.0.
+
+Acquisitions
+~~~~~~~~~~~~
+* Protects the stock acquisitions cancel reasons from deletion since they
+are required to properly handle EDI order responses.
+* Changes the copy location dropdown so that users can view and select copy
+locations owned outside the workstation branch if they have permission to do so.
+This fix also adds the copy location's owning org unit to the display.
+
+Administration
+~~~~~~~~~~~~~~
+* Allows use of more special characters, including - and +, when
+entering a library's main email address in the Organizational Units
+editor.
+* Fixes an issue where marc_export attempts to call a non-existent field
+on MARC::Record if an error occurs while exporting authority records.
+
+Cataloging
+~~~~~~~~~~
+* Fixes the mapping between copies and the target part when using "Merge
+Selected" in the Monographic Parts interface.
+* Fixes an issue with the horizontal scrollbar bar in the MARC import
+queue inspector so the focus no longer jumps to the top of the screen
+when attempting to use the scrollbar.
+* Hides the staff-client saved searches header from screen readers when
+using the public catalog in non-staff mode.
+
+Circulation
+~~~~~~~~~~~
+* When placing a hold via the staff client and clicking Advanced Hold
+Options, fixes an issue where the barcode field populated with the
+staff member's barcode.
+* Fixes an issue where some holds with a higher proximity were
+preferred over holds with a lower proximity because the list of
+proximities of elgible copies was sorting ASCIIbetically instead of
+numerically.
+* Adds a delete flag for monographic parts, fixes staff client errors that
+were previously caused by deleted parts, and cancels any holds attached to
+those deleted parts.
+* Fixes an internal error that appeared when trying to renew an item on the
+booking resource list through the public catalog. Users will now get a message
+saying they do not have permission to renew the item.
+
+
+Public Catalog
+~~~~~~~~~~~~~~
+* Fixes an issue where unclosed phrase searches returned zero results and
+tied up the open-ils.storage process.
+* Fixes an issue where phrase searches were ignoring modifiers used in relevance
+ranking, leading to poorly-ranked results.
+* Fixes an issue where parameters weren't properly maintained when
+searching by copy location group.
+
+Reports
+~~~~~~~
+* Adds support for UTF-8 in the Reports interface.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+We would like to thank the following individuals who contributed
+code and documentation patches to the 2.9.1 point release of Evergreen:
+
+* Adam Bowling
+* Kate Butler
+* Steven Chan
+* Galen Charlton
+* Blake Henderson
+* Pasi Kallinen
+* Jake Litrell
+* Kathy Lussier
+* Mike Rylander
+* Dan Scott
+* Chris Sharp
+* Ben Shum
+* Remington Steed
+* Jason Stephenson
+* Josh Stompro
+* Yamil Suarez
+
+We also thank the following organizations whose employees contributed
+patches:
+
+* Berklee College of Music
+* Bibliomation
+* British Columbia Libraries Cooperative
+* Calvin College
+* Emerald Data Networks, Inc.
+* Equinox Software, Inc.
+* Georgia Public Library Service
+* Lake Agassiz Regional Library
+* Laurentian University
+* Massachusetts Library Network Cooperative
+* Merrimack Valley Library Consortium
+* MOBIUS
+* Northwest Regional Library System
+* Pohjois-Karjalan Tietotekniikkakeskus Oy
+* Rodgers Memorial Library
+
+We regret any omissions. If a contributor has been inadvertantly
+missed, please open a bug at http://bugs.launchpad.net/evergreen/
+with a correction.
+
+2.9.0 Upgrade notes
+-------------------
+
+Remove Script-Based Circulation Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Evergreen no longer supports script-based circulation policies. All
+policies must now be managed within the Local Administration ->
+Circulation Policies, Hold Policies, and related interfaces.
+
+
+Remove open-ils.penalty service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Evergreen no longer uses the 'open-ils.penalty' service. It is safe
+(though not required) to remove the following XML chunks from
+/openils/conf/opensrf.xml after stopping services.
+
+[source,xml]
+----------------------------------------------------------------------------
+
+<!-- first element -->
+
+<open-ils.penalty>
+ <keepalive>3</keepalive>
+ <stateless>1</stateless>
+ <language>perl</language>
+ <implementation>OpenILS::Application::Penalty</implementation>
+ <max_requests>99</max_requests>
+ <unix_config>
+ <max_requests>1000</max_requests>
+ <unix_log>open-ils.penalty_unix.log</unix_log>
+ <unix_sock>open-ils.penalty_unix.sock</unix_sock>
+ <unix_pid>open-ils.penalty_unix.pid</unix_pid>
+ <min_children>1</min_children>
+ <max_children>15</max_children>
+ <min_spare_children>1</min_spare_children>
+ <max_spare_children>5</max_spare_children>
+ </unix_config>
+ <app_settings>
+ <patron_penalty>penalty/patron_penalty.js</patron_penalty>
+ <script_path>LIBDIR/javascript</script_path>
+ <script_path>LOCALSTATEDIR</script_path>
+ <script_path>LOCALSTATEDIR/catalog</script_path>
+ </app_settings>
+</open-ils.penalty>
+
+<!-- second element -->
+
+<appname>open-ils.penalty</appname>
+----------------------------------------------------------------------------
+
+
+Removal of deprecated "JSPAC" interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The deprecated Javascript OPAC interface known as "JSPAC" is no
+longer included in Evergreen as of this release.
+
+With the understanding that local sites may have made use of
+existing parts of the old JSPAC interface -- especially images and
+CSS -- no attempt is made at upgrade time to automatically remove
+the existing files from disk.
+
+When upgrading, you may wish to remove "index.xml" from your Apache
+DirectoryIndex directives.
+
+The following directories, xml, js, and css files were formerly part
+of JSPAC, and you may be able to safely remove them from your system
+after verifying that they and their contents are no longer required:
+
+- web/opac/common/css/
+- web/opac/common/js/dtree.js
+- web/opac/common/xml/
+- web/opac/extras/bbags.js
+- web/opac/extras/bbags.xml
+- web/opac/skin/default/js/
+- web/opac/skin/default/xml/
+- web/opac/theme/
+
+The list of images removed in this change is lengthy, and not
+included here.
+
+
+Removal of legacy selfcheck interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The legacy selfcheck interface is no longer included in Evergreen as
+of this release.
+
+This interface was formerly located at a URL ending in
+extras/selfcheck/selfcheck.xml
+
+No attempt is made at upgrade time to automatically remove this
+interface.
+
+It is recommended that you remove this interface and its associated
+configuration after performing an upgrade:
+
+(paths relative to Evergreen web root)
+
+- opac/extras/selfcheck/selfcheck.css
+- opac/extras/selfcheck/selfcheck.js
+- opac/extras/selfcheck/selfcheck.xml
+- opac/extras/selfcheck/selfcheck_print.css
+
+You can also remove the related Apache configuration block starting
+with:
+
+[source, conf]
+<LocationMatch .*/selfcheck.xml>
+
+
+
+2.9.0 New Features
+------------------
+
+Acquisitions
+~~~~~~~~~~~~
+
+
+
+Improved reporting of progress during purchase order activation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The progress dialog that is displayed when activating a purchase
+order now displays more information, particularly during the asset
+creation phase. It is now also updated in a more linear fashion;
+making it less likely for it to appear that the activation has
+stalled.
+
+
+
+
+==== "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.
+
+===== 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.
+
+===== New Components/Terminology/Concepts
+
+ * Invoice Item Types have a new flag called 'blanket', available under
+ Admin -> Server Administration -> Acq -> Invoice Item Types in the
+ staff client.
+ * 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.
+
+
+
+
+
+
+Administration
+~~~~~~~~~~~~~~
+
+
+
+Examples in Apache configuration for "No Image"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are now commented out examples for custom images to be used when
+"no image" is present in the catalog for cover art. The included examples
+are for small/medium/large jacket image art in the event they are not
+found by the configured Added Content module.
+
+
+
+
+Pre-Expiration A/T Event Definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A new Action Trigger event definition ("30 Day Account Expiration Courtesy
+Notice") for sending alerts to users before their accounts are expired has
+been added. This is intended to give users time to renew their account before
+they lose access to library services.
+
+
+
+
+Improved caching of web server templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Template Toolkit processors used by Apache are now cached for
+better performance (by virtue of thereby being able to take advantage
+of Template Toolkit's internal caching mechanism). In addition, the
+*compiled* versions of the templates themselves can be cached to
+provide an additional performance boost.
+
+Two Apache virtualhost configuration variables are added to
+control caching of compiled templates:
+
+ * `OILSWebCompiledTemplateCache` - specifies location on the
+ web server filesystem to store compiled templates.
+ * `OILSWebTemplateStatTTL` - specifies number of seconds before
+ checking to see if a newer version of a cached template is
+ available.
+
+As a result of the caching changes, it is now necessary for
+Evergreen administrators to reload Apache to ensure that a change
+to (say) TPAC templates becomes visible.
+
+
+
+
+Cataloging
+~~~~~~~~~~
+
+
+
+Display Authority Subject Heading Thesaurus Value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is now a new column in the *Manage Authorities* search results. Each result row now displays each authority's thesaurus value with a "Thes: " prefix. In the authority MARC editor interface the thesaurus value corresponds to the "Subject Heading Thesaurus" fixed field (http://www.loc.gov/marc/authority/ad008.html) labeled “Subj”. For example, a value of "Thes: a" means that the authority is a Library of Congress Subject Heading, and a value of "Thes: k" means the authority is a Canadian Subject Heading.
+
+*A 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
+
+
+
+
+Importing Statistical Categories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can now retrieve statistical categories (stat cats) from the MARC
+record and apply them to the items in Evergreen. When importing or
+overlaying items through the Vandelay MARC batch import process, edit
+your Holdings Import Profile to tell Evergreen which subfield contains
+your stat cat data. That subfield in your MARC records should be
+formatted like the following:
+
+----
+CATEGORY 1|VALUE 1||CATEGORY 2|VALUE 2
+----
+
+Notice that the pipe character '|' is used to separate each category
+from its value, and two pipes separate each pair of category values.
+
+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.
+
+
+
+
+Remove the ‡biblios.net Z39.50 target from seed data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The Z39.50 target at z3950.biblios.net/bibliographic has not worked
+for years, so its service definition is no longer provided in the
+seed data for new installations of Evergreen.
+
+Users of existing Evergreen systems should consider removing
+the Z39.50 definition for ‡biblios.net. This can be done from
+Admin | Server Administration | Z39.50 Servers in the staff
+client.
+
+
+
+
+SKOS for coded values
+^^^^^^^^^^^^^^^^^^^^^
+Some vocabularies used (or which could be used) for stock
+record attributes and coded value maps in Evergreen are
+published on the web using SKOS. The record attributes system
+can now associate Linked Data URIs with specific attribute
+values. In particular, seed data supplying URIs for the
+RDA Content Type, Media Type, and Carrier Type in this release.
+
+This is an experimental, "under-the-hood" feature that will be built
+upon in subsuquent releases.
+
+
+
+
+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.
+
+
+
+
+Web staff client cataloging preview
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The web staff client now includes additional functionality
+to support cataloging and item maintenance, including:
+
+- a new MARC editor
+- the service backing the authority headings chooser now
+ has the ability to filter the browse by subject thesaurus
+- Z39.50 search and record import
+- improvements to copy and record bucket functionality
+- embedding the link checker interface
+- embedding the MARC batch import/export interface
+- the web staff volume/copy editor
+
+Nearly all of the cataloging functionality available in the XUL
+staff client is now present in the web staff client with the
+exception of printing spine labels. Nonetheless, the web staff
+client remains a preview and is not recommended for production use.
+
+
+
+
+Circulation
+~~~~~~~~~~~
+
+
+
+Conditional Negative Balances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Evergreen sites will now have more control over whether a negative balance can
+be applied to a user's billing record and when that negative balance can be
+applied. Through a series of Library Settings, a site can prohibit negative
+balances on bills or can allow those negative balances to be applied for a
+specific period of time after a lost or overdue bill is charged to the user.
+Sites can set a default for all types of bills or can apply distinct settings
+for lost bills and for overdue fines. The more specific settings will override
+the default.
+
+Sites that opt to allow negative balances for a specific period of time must
+1) enable the relevant "prohibit negative balances" setting(s) and 2) specify
+the time period in the relevant Negative Balance Interval setting(s).
+
+In addition to the new library settings, the system now has a new account
+adjustment payment type. This payment type will be utilized for libraries
+prohibiting negative balances to replace the previous voiding behavior that
+caused the negative balances to occur. The account adjustment payment type will
+also be used for all libraries, regardless of the state of negative balance
+settings, in cases where overdue fines are adjusted when an overdue item is
+marked lost.
+
+An _Adjust to Zero_ option has been added to the bills interface of the patron
+record. This option will always adjust the selected bill to a zero balance.
+It can also be used to easily clear a negative balance from the patron's
+record. A user must have the new ADJUST_BILLS permission to see and use this
+option.
+
+This new feature also changes the behavior for the client option to void a bill
+from the patron record. If a user does not have the VOID_BILLING permission, the
+option to void bills will be hidden in the bills interface and in the Full
+Details view of a specific bill.
+
+To truly remove the ability to produce negative balances on a transaction,
+administrators need to 1) enable the relevant setting in the Library Settings
+Editor and 2) remove the VOID_BILLING permission from staff accounts since
+manual voiding will continue to produce negative balances.
+
+New Library Settings
+++++++++++++++++++++
+ * Negative Balance Interval (Default) (bill.negative_balance_interval_default)
+ * Negative Balance Interval for Lost (bill.negative_balance_interval_on_lost) -
+ * Negative Balance Interval for Overdues (bill.negative_balance_interval_on_overdues
+ * Prohibit negative balance on bills (Default) (bill.prohibit_negative_balance_default)
+ * Prohibit negative balance on bills for lost materials (bill.prohibit_negative_balance_on_lost)
+ * Prohibit negative balance on bills for overdue materials (bill.prohibit_negative_balance_on_overdues)
+
+New Permissions
++++++++++++++++
+ * ADJUST_BILLS
+
+
+
+
+Selfcheck Inactivity Warning
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Selfcheck interface now warns patrons when they are about to be
+logged out due to inactivity 20 seconds prior to logging them out.
+
+The inactivity timeout is also reset with each checkout to avoid timeouts
+while checking out lots of items.
+
+
+
+
+User Registration Includes Inactive Accounts in Dupe Search
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When registering a user, the system checks to see if there are already exiting users with the same name, address, email, etc. Now this duplicate user search includes inactive users so that matches can be re-activated if desired, rather than creating duplicate accounts.
+
+
+
+
+Client
+~~~~~~
+
+
+
+Link in catalog to clear Added Content cache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On the catalog's record summary page, there is now a link for staff that
+allow them to forcibly clear the cache for the Added Content for that
+record. This is helpful if the Added Content retrieved the wrong
+cover jacket art, summary, etc. and caches the wrong result.
+
+
+
+
+Disable Google Analytics in Staff Client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In the staff client interface, Google Analytics for the web catalog is
+now disabled by default. This was a preventive measure to reduce the
+potential risks for leaking patron information.
+
+
+
+
+Move Acquisitions Admin Menu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In the staff client interface, the Acquisitions Administration menu is
+now directly accessible from the main "Admin" menu instead of
+living under "Server Administration". It has also been renamed as "Acquisitions
+Administration".
+
+
+
+
+OPAC
+~~~~
+
+
+
+Account Expiration Date in My Account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The Account Expiration Date has been added to the catalog's My Account display
+on the main Account Summary page and the Account Preferences page. This should
+help patrons with figuring out when their accounts are due to expire before
+they actually expire.
+
+
+
+Change to Available Copies Display
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The _Show_ link in the available copies area of the record summary will now
+display for any org unit that owns a copy of a particular title, even if all
+those copies are unavailable. The _Show_ link will not display if a) the copy
+display is already scoped to that org unit or b) the org unit does not own
+copies of the title.
+
+The language has also been changed to read "x of y copies available at z
+library."
+
+
+
+
+
+Column sorting in circulation screens
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sorting of selected columns is now available in the *Items Checked Out*, *Check Out History*,
+and *Holds* screens.
+
+* Clicking on the appropriate column heads now 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.
+
+* The combined *Title/Author* column in the *Items Checked Out* screen is now separated into two
+independently sortable columns (Title and Author).
+
+* Title sorting is done with the non-filing characters (leading ``the'', ``a'',
+``an'', and other langugage equivalents) removed. The leading articles are rendered in
+a smaller font, so as to keep the main entry prominent. In
+addition to the non-filing characters removed for the sort, leading
+non-alphanumeric characters are ignored in the sort.
+
+
+
+
+New bib source variable for catalog customization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For bibliographic records, there is a "bib source" that can be
+associated with every record. This source is now available as a
+variable that can be used behind the scenes when customizing
+the online catalog. The new bib source variables do not present
+themselves in the catalog display by default.
+
+
+
+
+New class attribute for e-resource links
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In the catalog, links to electronic resources now have a link class
+attribute of "uri_link" to make them easier to customize or build
+additional services upon.
+
+
+
+
+
+Removal of deprecated "JSPAC" interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The deprecated Javascript OPAC interface known as "JSPAC" is no
+longer included in Evergreen as of this release.
+
+With the understanding that local sites may have made use of
+existing parts of the old JSPAC interface -- especially images and
+CSS -- no attempt is made at upgrade time to automatically remove
+the existing files from disk.
+
+When upgrading, you may wish to remove "index.xml" from your Apache
+DirectoryIndex directives.
+
+The following directories, xml, js, and css files were formerly part
+of JSPAC, and you may be able to safely remove them from your system
+after verifying that they and their contents are no longer required:
+
+- web/opac/common/css/
+- web/opac/common/js/dtree.js
+- web/opac/common/xml/
+- web/opac/extras/bbags.js
+- web/opac/extras/bbags.xml
+- web/opac/skin/default/js/
+- web/opac/skin/default/xml/
+- web/opac/theme/
+
+The list of images removed in this change is lengthy, and not
+included here.
+
+
+
+
+Removal of legacy selfcheck interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The legacy selfcheck interface is no longer included in Evergreen as
+of this release.
+
+This interface was formerly located at a URL ending in
+extras/selfcheck/selfcheck.xml
+
+No attempt is made at upgrade time to automatically remove this
+interface.
+
+It is recommended that you remove this interface and its associated
+configuration after performing an upgrade:
+
+(paths relative to Evergreen web root)
+
+- opac/extras/selfcheck/selfcheck.css
+- opac/extras/selfcheck/selfcheck.js
+- opac/extras/selfcheck/selfcheck.xml
+- opac/extras/selfcheck/selfcheck_print.css
+
+You can also remove the related Apache configuration block starting
+with:
+
+[source, conf]
+<LocationMatch .*/selfcheck.xml>
+
+
+
+
+Acknowledgments
+~~~~~~~~~~~~~~~
+The Evergreen project would like to acknowledge the following
+organizations who commissioned developments in this release of
+Evergreen:
+
+ * Georgia Public Library Service
+ * Grand Rapids Public Library
+ * Kenton County Public Library
+ * King County Library System
+ * Massachusetts Library Network Cooperative
+ * NC Cardinal
+ * OhioNet
+ * Pennsylvania Integrated Library System
+
+We would also like to thank the following individuals who contributed
+code, documentation patches and tests to this release of Evergreen:
+
+ * Thomas Berezansky
+ * Matt Berowski
+ * Adam Bowling
+ * Jason Boyer
+ * Christine Burns
+ * Galen Charlton
+ * Bill Erickson
+ * Jason Etheridge
+ * Jeff Davis
+ * Lynn Floyd
+ * Jeff Godin
+ * Angela Kilsdonk
+ * Doug Kyle
+ * Debbie Luchenbill
+ * Kathy Lussier
+ * Terran McCanna
+ * Stephen Moss
+ * Dan Pearl
+ * Michael Peters
+ * Mike Rylander
+ * Jane Sandberg
+ * Dan Scott
+ * Ben Shum
+ * Josh Stompro
+ * Remington Steed
+ * Jason Stephenson
+ * Yamil Suarez
+ * Dan Wells
+ * Liam Whalen
+
+We also thank the following organizations whose employees contributed
+patches:
+
+ * Anderson County Library
+ * Berklee College of Music
+ * Bibliomation
+ * British Columbia Libraries Cooperative
+ * Calvin College
+ * Catalyst Dev Works
+ * Central/Western Massachusetts Automated Resource Sharing
+ * Emerald Data Networks, Inc.
+ * Equinox Software, Inc.
+ * Georgia Public Library Service
+ * Grand Rapids Public Library
+ * Indiana State Library
+ * King County Library System
+ * Lake Agassiz Regional Library
+ * Laurentian University
+ * Linn-Benton Community College
+ * Massachusetts Library Network Cooperative
+ * Merrimack Valley Library Consortium
+ * MOBIUS
+ * Northwest Regional Library System
+ * Sigio
+ * Traverse Area District Library
+
+We regret any omissions. If a contributor has been inadvertantly
+missed, please open a bug at http://bugs.launchpad.net/evergreen/
+with a correction.
+
+++ /dev/null
-Evergreen 2.9 Release Notes
-===========================
-:toc:
-:numbered:
-
-Evergreen 2.9.8
----------------
-This release contains several bugfixes improving on Evergreen 2.9.7
-
-* When adding a price to the Acquisitions Brief Record price field, it will
-now propogate to the lineitem estimated price field.
-* Declares UTF-8 encoding when printing from the catalog to resolve issues
-where non_ASCII characters printed incorrectly in some browsers.
-* Fixes an issue where the circ module sometimes skipped over booking logic
-even when booking was running on a system.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed code,
-testing and documentation patches to the 2.9.8 point release of
-Evergreen:
-
-* Bill Erickson
-* Mike Rylander
-* Dan Scott
-
-Evergreen 2.9.7
----------------
-This release contains several bugfixes improving on Evergreen 2.9.6
-
-* The claims never checked out counter on the patron record is now
- incremented correctly when marking a lost loan as
- claims-never-checked-out.
-* When a transit is canceled, the copy's status is changed only
- if its status was previously "In Transit".
-* Retrieving records with embedded holdings via SRU and Z39.50 is now
- faster.
-* The hold status message in the public catalog now uses
- better grammar.
-* The error message displayed when a patron attempts to place
- a hold but is prevented from doing so due to policy reasons
- is now more likely to be useful
-* The public catalog now draws the edition statement only
- from the 250 field; it no longer tries to check the 534
- and 775 fields.
-* Embedded schema.org microdata now uses "offeredBy" rather
- than "seller".
-* The ContentCafe added content plugin now handles the "fake"
- ISBNs that Baker and Taylor assigns to media items.
-* Attempting to renew a rental or deposit item in the public
- catalog no longer causes an internal server errorr.
-* Various format icons now have transparent backgrounds (as opposed
- to white).
-* The staff client will no longer wait indefinitely for Novelist
- to supply added content, improving its responsiveness.
-* A few additional strings are now marked as translatable.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed code,
-testing and documentation patches to the 2.9.6 point release of
-Evergreen:
-
-* Thomas Berezansky
-* Jason Boyer
-* Galen Charlton
-* Jeff Davis
-* Blake Graham-Henderson
-* Jim Keenan
-* Kathy Lussier
-* Mike Rylander
-* Dan Scott
-* Ben Shum
-* Remington Steed
-* Jason Stephenson
-* Josh Stompro
-* Yamil Suarez
-
-Evergreen 2.9.6
----------------
-This release contains several bugfixes improving on Evergreen 2.9.5
-
-* Fixes a bug where Action Triggers could select an inactive event definition
-when running.
-* Fixes an issue where previously-checked-out items did not display in
-metarecord searches when the Tag Circulated Items Library Setting is enabled.
-* Fixes an error that occurred when the system attempted to display a translated
-string for the "Has Local Copy" hold placement error message.
-* Fixes an issue where the Show More/Show Fewer Details button didn't work in
-catalogs that default to showing more details.
-* Removes Social Security Number as a stock patron identification type for
-new installations. This fix does not change patron identification types for
-existing Evergreen systems.
-* Adds two missing link fields (patron profile and patron home library) to
-the fm_idl.xml for the Combined Active and Aged Circulations (combcirc)
-reporter source.
-* Adds a performance improvement for the "Clear Holds Shelf" checkin modifier.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed
-code, testing and documentation patches to the 2.9.6 point release of Evergreen:
-
-* Galen Charlton
-* Codey Kolasinski
-* Jeanette Lundgren
-* Kathy Lussier
-* Terran McCanna
-* Michele Morgan
-* Jason Stephenson
-* Josh Stompro
-
-Evergreen 2.9.5
----------------
-This release contains several bugixes improving on Evergreen 2.9.4
-
-* Emails sent using the Action Trigger SendEmail reactor now always MIME-encode
-the From, To, Subject, Bcc, Cc, Reply-To, and Sender headers. As a consequence,
-non-ASCII character in those fields are more likely to be displayed correctly
-in email clients.
-* Fixes the responsive view of the My Account Items Out screen so that _Title_
-and _Author_ are now in separate columns.
-* Fixes an incorrect link for the MVF field definition and adds a new link to
-BRE in fm_IDL.xml.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed
-code and documentation patches to the 2.9.5 point release of Evergreen:
-
-* Blake Henderson
-* Pasi Kallinen
-* Dan Scott
-* Dan Wells
-
-We also thank the following organizations whose employees contributed
-patches:
-
-* Calvin College
-* Laurentian University
-* MOBIUS
-* Pohjois-Karjalan Tietotekniikkakeskus Oy
-
-Evergreen 2.9.4
----------------
-This release contains several bugfixes improving on Evergreen 2.9.3
-
-* Fixes a bug where phrase searching in the catalog failed when the phrase
-started or ended with punctuation.
-* Fixes a bug where changing the sort order in the public catalog to
-"relevance" could fail.
-* Fixes a bug that prevented users from recreating a monograph part that
-had previously been deleted.
-* Silences unnecessary warnings emitted for libraries using extending grace
-periods.
-* Removes support for Debian Squeeze now that its long-term support period
-has ended.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed
-code and documentation patches to the 2.9.4 point release of Evergreen:
-
-* Jason Boyer
-* Steve Callender
-* Galen Charlton
-* Mike Rylander
-* Yamil Suarez
-
-We also thank the following organizations whose employees contributed
-patches:
-
-* Berklee College of Music
-* Equinox Software, Inc.
-* Evergreen Indiana
-
-
-Evergreen 2.9.3
----------------
-This release contains several bugfixes improving on Evergreen 2.9.2.
-
-Acquisitions
-~~~~~~~~~~~~
-* Adds EDI Cancel Code 85 to the acquisitions cancel reason table.
-* Fixes an issue where the "Expand All" button in selection lists was not
-working.
-* Fixes an issue where deletable reasons from the acquisitions Cancel Reasons
-table could not be deleted.
-
-Cataloging
-~~~~~~~~~~
-* Improves sorting in holdings maintenance so that copies sort first by parts
-then by barcode.
-
-Circulation
-~~~~~~~~~~~
-* Fixes an issue where the wrong last billing type and last billing note were
-displaying for some transactions.
-* Now calculates credit payments as integers to avoid rounding errors with
-large sets of small billings.
-* Fixes an issue in the patron record where staff was unable to retrieve the
-Message Center interface after visiting the Triggered Events page and vice
-versa.
-* Now displays the short version of a title on the Place Holds screen when
-placing metabib holds to reduce instances where the wrong title/format
-displayed.
-
-OPAC
-~~~~
-* Fixes an issue where detailed search results showed parts for items that
-didn't have parts.
-* Changes the e-mail address check on password reset requests so that it is no
-longer case sensitive.
-* Fixes a problem where users were unable to navigate through multiple pages of
-their holds history.
-* Removes undefined values from ISBN and ISSN arrays to prevent empty requests
-from being sent to added content providers.
-* Fixes an issue where the kids catalog was not displaying title information
-after hold placement or after adding a title to a list.
-* Corrects the kids catalog holds notification default preferences to allow for
-SMS text messaging options.
-
-
-Miscelleneous
-~~~~~~~~~~~~~
-* Modifies the way SIP2 clients parse dates so that a patron's date of birth is
-returned correctly.
-* Fixes an issue where the Selfcheck fines receipt templated printed all open
-billable transactions, regardless of whether it had bills associated with it.
-* Fixes an issue that prevented Selfcheck's "Print List" for holds view from
-working.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed
-code and documentation patches to the 2.9.3 point release of Evergreen:
-
-* Thomas Berezansky
-* Jason Boyer
-* Galen Charlton
-* Bill Erickson
-* Blake Henderson
-* Terran McCanna
-* Chris Sharp
-* Remington Steed
-* Jason Stephenson
-* Josh Stompro
-* Dan Wells
-
-
-
-We also thank the following organizations whose employees contributed
-patches:
-
-* Calvin College
-* Equinox Software, Inc.
-* Evergreen Indiana
-* Georgia Public Library Service
-* King County Library System
-* Lake Agassiz Regional Library
-* Merrimack Valley Library Consortium
-* MOBIUS
-* Northwest Regional Library System
-
-Evergreen 2.9.2
----------------
-This release contains several bugfixes improving on Evergreen 2.9.1.
-
-Acquisitions / Cataloging
-~~~~~~~~~~~~~~~~~~~~~~~~~
-* Allows the Z39.50 itnerface and the acquisitions MARC Federated Search
-interface to search the UPC index of the local catalog if Z39.50 is configured
-to search that field.
-* Fixes an issue where spaces in a PO name cause the system to improperly
-process EDI response messages.
-
-Circulation
-~~~~~~~~~~~
-* Fixes a problem where the balance owed was miscalculated when a row
-was deleted from money.billing.
-* Fixes an issue where credit card payments made via PayflowPro failed because
-Evergreen does not install the PayflowPro module by default.
-* Changes credit card payment behavior so that the patron's billing address will
-be read when the patron has no mailing address. If all address fields are
-properly set by the API caller except the country and the
-patron has no addresses, the system will attempt to determine the country from
-library settings. If insufficient address data is provided, the system will
-return an invalid params Event.
-* Modifies the reasons for various void/adjust events to more accurately reflect
-the reason why a fine/fee was removed from a patron's record.
-
-OPAC
-~~~~
-* Fixes an issue where the reset password link was displaying even on systems
-that had disabled the ability to reset passwords.
-* Fixes an issue where the journal type search did not work when entering it as
-the second or third input on the advanced search screen.
-* Fixes an issue where catalog translations were broken by creating separate
-directories for the catalog and web staff client translations.
-
-Administration
-~~~~~~~~~~~~~~
-* Changes marc_export to only print "waiting for input" when running
-interactively.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed
-code and documentation patches to the 2.9.2 point release of Evergreen:
-
-* Galen Charlton
-* Bill Erickson
-* Blake Henderson
-* Mike Rylander
-* Ben Shum
-* Jason Stephenson
-* Dan Wells
-
-We also thank the following organizations whose employees contributed
-patches:
-
-* Calvin College
-* Equinox Software, Inc.
-* King County Library System
-* Merrimack Valley Library Consortium
-* MOBIUS
-
-Evergreen 2.9.1
-----------------
-This release contains several bugfixes improving on Evergreen 2.9.0.
-
-Acquisitions
-~~~~~~~~~~~~
-* Protects the stock acquisitions cancel reasons from deletion since they
-are required to properly handle EDI order responses.
-* Changes the copy location dropdown so that users can view and select copy
-locations owned outside the workstation branch if they have permission to do so.
-This fix also adds the copy location's owning org unit to the display.
-
-Administration
-~~~~~~~~~~~~~~
-* Allows use of more special characters, including - and +, when
-entering a library's main email address in the Organizational Units
-editor.
-* Fixes an issue where marc_export attempts to call a non-existent field
-on MARC::Record if an error occurs while exporting authority records.
-
-Cataloging
-~~~~~~~~~~
-* Fixes the mapping between copies and the target part when using "Merge
-Selected" in the Monographic Parts interface.
-* Fixes an issue with the horizontal scrollbar bar in the MARC import
-queue inspector so the focus no longer jumps to the top of the screen
-when attempting to use the scrollbar.
-* Hides the staff-client saved searches header from screen readers when
-using the public catalog in non-staff mode.
-
-Circulation
-~~~~~~~~~~~
-* When placing a hold via the staff client and clicking Advanced Hold
-Options, fixes an issue where the barcode field populated with the
-staff member's barcode.
-* Fixes an issue where some holds with a higher proximity were
-preferred over holds with a lower proximity because the list of
-proximities of elgible copies was sorting ASCIIbetically instead of
-numerically.
-* Adds a delete flag for monographic parts, fixes staff client errors that
-were previously caused by deleted parts, and cancels any holds attached to
-those deleted parts.
-* Fixes an internal error that appeared when trying to renew an item on the
-booking resource list through the public catalog. Users will now get a message
-saying they do not have permission to renew the item.
-
-
-Public Catalog
-~~~~~~~~~~~~~~
-* Fixes an issue where unclosed phrase searches returned zero results and
-tied up the open-ils.storage process.
-* Fixes an issue where phrase searches were ignoring modifiers used in relevance
-ranking, leading to poorly-ranked results.
-* Fixes an issue where parameters weren't properly maintained when
-searching by copy location group.
-
-Reports
-~~~~~~~
-* Adds support for UTF-8 in the Reports interface.
-
-Acknowledgements
-~~~~~~~~~~~~~~~~
-We would like to thank the following individuals who contributed
-code and documentation patches to the 2.9.1 point release of Evergreen:
-
-* Adam Bowling
-* Kate Butler
-* Steven Chan
-* Galen Charlton
-* Blake Henderson
-* Pasi Kallinen
-* Jake Litrell
-* Kathy Lussier
-* Mike Rylander
-* Dan Scott
-* Chris Sharp
-* Ben Shum
-* Remington Steed
-* Jason Stephenson
-* Josh Stompro
-* Yamil Suarez
-
-We also thank the following organizations whose employees contributed
-patches:
-
-* Berklee College of Music
-* Bibliomation
-* British Columbia Libraries Cooperative
-* Calvin College
-* Emerald Data Networks, Inc.
-* Equinox Software, Inc.
-* Georgia Public Library Service
-* Lake Agassiz Regional Library
-* Laurentian University
-* Massachusetts Library Network Cooperative
-* Merrimack Valley Library Consortium
-* MOBIUS
-* Northwest Regional Library System
-* Pohjois-Karjalan Tietotekniikkakeskus Oy
-* Rodgers Memorial Library
-
-We regret any omissions. If a contributor has been inadvertantly
-missed, please open a bug at http://bugs.launchpad.net/evergreen/
-with a correction.
-
-2.9.0 Upgrade notes
--------------------
-
-Remove Script-Based Circulation Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Evergreen no longer supports script-based circulation policies. All
-policies must now be managed within the Local Administration ->
-Circulation Policies, Hold Policies, and related interfaces.
-
-
-Remove open-ils.penalty service
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Evergreen no longer uses the 'open-ils.penalty' service. It is safe
-(though not required) to remove the following XML chunks from
-/openils/conf/opensrf.xml after stopping services.
-
-[source,xml]
-----------------------------------------------------------------------------
-
-<!-- first element -->
-
-<open-ils.penalty>
- <keepalive>3</keepalive>
- <stateless>1</stateless>
- <language>perl</language>
- <implementation>OpenILS::Application::Penalty</implementation>
- <max_requests>99</max_requests>
- <unix_config>
- <max_requests>1000</max_requests>
- <unix_log>open-ils.penalty_unix.log</unix_log>
- <unix_sock>open-ils.penalty_unix.sock</unix_sock>
- <unix_pid>open-ils.penalty_unix.pid</unix_pid>
- <min_children>1</min_children>
- <max_children>15</max_children>
- <min_spare_children>1</min_spare_children>
- <max_spare_children>5</max_spare_children>
- </unix_config>
- <app_settings>
- <patron_penalty>penalty/patron_penalty.js</patron_penalty>
- <script_path>LIBDIR/javascript</script_path>
- <script_path>LOCALSTATEDIR</script_path>
- <script_path>LOCALSTATEDIR/catalog</script_path>
- </app_settings>
-</open-ils.penalty>
-
-<!-- second element -->
-
-<appname>open-ils.penalty</appname>
-----------------------------------------------------------------------------
-
-
-Removal of deprecated "JSPAC" interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The deprecated Javascript OPAC interface known as "JSPAC" is no
-longer included in Evergreen as of this release.
-
-With the understanding that local sites may have made use of
-existing parts of the old JSPAC interface -- especially images and
-CSS -- no attempt is made at upgrade time to automatically remove
-the existing files from disk.
-
-When upgrading, you may wish to remove "index.xml" from your Apache
-DirectoryIndex directives.
-
-The following directories, xml, js, and css files were formerly part
-of JSPAC, and you may be able to safely remove them from your system
-after verifying that they and their contents are no longer required:
-
-- web/opac/common/css/
-- web/opac/common/js/dtree.js
-- web/opac/common/xml/
-- web/opac/extras/bbags.js
-- web/opac/extras/bbags.xml
-- web/opac/skin/default/js/
-- web/opac/skin/default/xml/
-- web/opac/theme/
-
-The list of images removed in this change is lengthy, and not
-included here.
-
-
-Removal of legacy selfcheck interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The legacy selfcheck interface is no longer included in Evergreen as
-of this release.
-
-This interface was formerly located at a URL ending in
-extras/selfcheck/selfcheck.xml
-
-No attempt is made at upgrade time to automatically remove this
-interface.
-
-It is recommended that you remove this interface and its associated
-configuration after performing an upgrade:
-
-(paths relative to Evergreen web root)
-
-- opac/extras/selfcheck/selfcheck.css
-- opac/extras/selfcheck/selfcheck.js
-- opac/extras/selfcheck/selfcheck.xml
-- opac/extras/selfcheck/selfcheck_print.css
-
-You can also remove the related Apache configuration block starting
-with:
-
-[source, conf]
-<LocationMatch .*/selfcheck.xml>
-
-
-
-2.9.0 New Features
-------------------
-
-Acquisitions
-~~~~~~~~~~~~
-
-
-
-Improved reporting of progress during purchase order activation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The progress dialog that is displayed when activating a purchase
-order now displays more information, particularly during the asset
-creation phase. It is now also updated in a more linear fashion;
-making it less likely for it to appear that the activation has
-stalled.
-
-
-
-
-==== "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.
-
-===== 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.
-
-===== New Components/Terminology/Concepts
-
- * Invoice Item Types have a new flag called 'blanket', available under
- Admin -> Server Administration -> Acq -> Invoice Item Types in the
- staff client.
- * 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.
-
-
-
-
-
-
-Administration
-~~~~~~~~~~~~~~
-
-
-
-Examples in Apache configuration for "No Image"
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are now commented out examples for custom images to be used when
-"no image" is present in the catalog for cover art. The included examples
-are for small/medium/large jacket image art in the event they are not
-found by the configured Added Content module.
-
-
-
-
-Pre-Expiration A/T Event Definition
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A new Action Trigger event definition ("30 Day Account Expiration Courtesy
-Notice") for sending alerts to users before their accounts are expired has
-been added. This is intended to give users time to renew their account before
-they lose access to library services.
-
-
-
-
-Improved caching of web server templates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Template Toolkit processors used by Apache are now cached for
-better performance (by virtue of thereby being able to take advantage
-of Template Toolkit's internal caching mechanism). In addition, the
-*compiled* versions of the templates themselves can be cached to
-provide an additional performance boost.
-
-Two Apache virtualhost configuration variables are added to
-control caching of compiled templates:
-
- * `OILSWebCompiledTemplateCache` - specifies location on the
- web server filesystem to store compiled templates.
- * `OILSWebTemplateStatTTL` - specifies number of seconds before
- checking to see if a newer version of a cached template is
- available.
-
-As a result of the caching changes, it is now necessary for
-Evergreen administrators to reload Apache to ensure that a change
-to (say) TPAC templates becomes visible.
-
-
-
-
-Cataloging
-~~~~~~~~~~
-
-
-
-Display Authority Subject Heading Thesaurus Value
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There is now a new column in the *Manage Authorities* search results. Each result row now displays each authority's thesaurus value with a "Thes: " prefix. In the authority MARC editor interface the thesaurus value corresponds to the "Subject Heading Thesaurus" fixed field (http://www.loc.gov/marc/authority/ad008.html) labeled “Subj”. For example, a value of "Thes: a" means that the authority is a Library of Congress Subject Heading, and a value of "Thes: k" means the authority is a Canadian Subject Heading.
-
-*A 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
-
-
-
-
-Importing Statistical Categories
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can now retrieve statistical categories (stat cats) from the MARC
-record and apply them to the items in Evergreen. When importing or
-overlaying items through the Vandelay MARC batch import process, edit
-your Holdings Import Profile to tell Evergreen which subfield contains
-your stat cat data. That subfield in your MARC records should be
-formatted like the following:
-
-----
-CATEGORY 1|VALUE 1||CATEGORY 2|VALUE 2
-----
-
-Notice that the pipe character '|' is used to separate each category
-from its value, and two pipes separate each pair of category values.
-
-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.
-
-
-
-
-Remove the ‡biblios.net Z39.50 target from seed data
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Z39.50 target at z3950.biblios.net/bibliographic has not worked
-for years, so its service definition is no longer provided in the
-seed data for new installations of Evergreen.
-
-Users of existing Evergreen systems should consider removing
-the Z39.50 definition for ‡biblios.net. This can be done from
-Admin | Server Administration | Z39.50 Servers in the staff
-client.
-
-
-
-
-SKOS for coded values
-^^^^^^^^^^^^^^^^^^^^^
-Some vocabularies used (or which could be used) for stock
-record attributes and coded value maps in Evergreen are
-published on the web using SKOS. The record attributes system
-can now associate Linked Data URIs with specific attribute
-values. In particular, seed data supplying URIs for the
-RDA Content Type, Media Type, and Carrier Type in this release.
-
-This is an experimental, "under-the-hood" feature that will be built
-upon in subsuquent releases.
-
-
-
-
-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.
-
-
-
-
-Web staff client cataloging preview
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The web staff client now includes additional functionality
-to support cataloging and item maintenance, including:
-
-- a new MARC editor
-- the service backing the authority headings chooser now
- has the ability to filter the browse by subject thesaurus
-- Z39.50 search and record import
-- improvements to copy and record bucket functionality
-- embedding the link checker interface
-- embedding the MARC batch import/export interface
-- the web staff volume/copy editor
-
-Nearly all of the cataloging functionality available in the XUL
-staff client is now present in the web staff client with the
-exception of printing spine labels. Nonetheless, the web staff
-client remains a preview and is not recommended for production use.
-
-
-
-
-Circulation
-~~~~~~~~~~~
-
-
-
-Conditional Negative Balances
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Evergreen sites will now have more control over whether a negative balance can
-be applied to a user's billing record and when that negative balance can be
-applied. Through a series of Library Settings, a site can prohibit negative
-balances on bills or can allow those negative balances to be applied for a
-specific period of time after a lost or overdue bill is charged to the user.
-Sites can set a default for all types of bills or can apply distinct settings
-for lost bills and for overdue fines. The more specific settings will override
-the default.
-
-Sites that opt to allow negative balances for a specific period of time must
-1) enable the relevant "prohibit negative balances" setting(s) and 2) specify
-the time period in the relevant Negative Balance Interval setting(s).
-
-In addition to the new library settings, the system now has a new account
-adjustment payment type. This payment type will be utilized for libraries
-prohibiting negative balances to replace the previous voiding behavior that
-caused the negative balances to occur. The account adjustment payment type will
-also be used for all libraries, regardless of the state of negative balance
-settings, in cases where overdue fines are adjusted when an overdue item is
-marked lost.
-
-An _Adjust to Zero_ option has been added to the bills interface of the patron
-record. This option will always adjust the selected bill to a zero balance.
-It can also be used to easily clear a negative balance from the patron's
-record. A user must have the new ADJUST_BILLS permission to see and use this
-option.
-
-This new feature also changes the behavior for the client option to void a bill
-from the patron record. If a user does not have the VOID_BILLING permission, the
-option to void bills will be hidden in the bills interface and in the Full
-Details view of a specific bill.
-
-To truly remove the ability to produce negative balances on a transaction,
-administrators need to 1) enable the relevant setting in the Library Settings
-Editor and 2) remove the VOID_BILLING permission from staff accounts since
-manual voiding will continue to produce negative balances.
-
-New Library Settings
-++++++++++++++++++++
- * Negative Balance Interval (Default) (bill.negative_balance_interval_default)
- * Negative Balance Interval for Lost (bill.negative_balance_interval_on_lost) -
- * Negative Balance Interval for Overdues (bill.negative_balance_interval_on_overdues
- * Prohibit negative balance on bills (Default) (bill.prohibit_negative_balance_default)
- * Prohibit negative balance on bills for lost materials (bill.prohibit_negative_balance_on_lost)
- * Prohibit negative balance on bills for overdue materials (bill.prohibit_negative_balance_on_overdues)
-
-New Permissions
-+++++++++++++++
- * ADJUST_BILLS
-
-
-
-
-Selfcheck Inactivity Warning
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Selfcheck interface now warns patrons when they are about to be
-logged out due to inactivity 20 seconds prior to logging them out.
-
-The inactivity timeout is also reset with each checkout to avoid timeouts
-while checking out lots of items.
-
-
-
-
-User Registration Includes Inactive Accounts in Dupe Search
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When registering a user, the system checks to see if there are already exiting users with the same name, address, email, etc. Now this duplicate user search includes inactive users so that matches can be re-activated if desired, rather than creating duplicate accounts.
-
-
-
-
-Client
-~~~~~~
-
-
-
-Link in catalog to clear Added Content cache
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-On the catalog's record summary page, there is now a link for staff that
-allow them to forcibly clear the cache for the Added Content for that
-record. This is helpful if the Added Content retrieved the wrong
-cover jacket art, summary, etc. and caches the wrong result.
-
-
-
-
-Disable Google Analytics in Staff Client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In the staff client interface, Google Analytics for the web catalog is
-now disabled by default. This was a preventive measure to reduce the
-potential risks for leaking patron information.
-
-
-
-
-Move Acquisitions Admin Menu
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In the staff client interface, the Acquisitions Administration menu is
-now directly accessible from the main "Admin" menu instead of
-living under "Server Administration". It has also been renamed as "Acquisitions
-Administration".
-
-
-
-
-OPAC
-~~~~
-
-
-
-Account Expiration Date in My Account
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The Account Expiration Date has been added to the catalog's My Account display
-on the main Account Summary page and the Account Preferences page. This should
-help patrons with figuring out when their accounts are due to expire before
-they actually expire.
-
-
-
-Change to Available Copies Display
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The _Show_ link in the available copies area of the record summary will now
-display for any org unit that owns a copy of a particular title, even if all
-those copies are unavailable. The _Show_ link will not display if a) the copy
-display is already scoped to that org unit or b) the org unit does not own
-copies of the title.
-
-The language has also been changed to read "x of y copies available at z
-library."
-
-
-
-
-
-Column sorting in circulation screens
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Sorting of selected columns is now available in the *Items Checked Out*, *Check Out History*,
-and *Holds* screens.
-
-* Clicking on the appropriate column heads now 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.
-
-* The combined *Title/Author* column in the *Items Checked Out* screen is now separated into two
-independently sortable columns (Title and Author).
-
-* Title sorting is done with the non-filing characters (leading ``the'', ``a'',
-``an'', and other langugage equivalents) removed. The leading articles are rendered in
-a smaller font, so as to keep the main entry prominent. In
-addition to the non-filing characters removed for the sort, leading
-non-alphanumeric characters are ignored in the sort.
-
-
-
-
-New bib source variable for catalog customization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-For bibliographic records, there is a "bib source" that can be
-associated with every record. This source is now available as a
-variable that can be used behind the scenes when customizing
-the online catalog. The new bib source variables do not present
-themselves in the catalog display by default.
-
-
-
-
-New class attribute for e-resource links
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In the catalog, links to electronic resources now have a link class
-attribute of "uri_link" to make them easier to customize or build
-additional services upon.
-
-
-
-
-
-Removal of deprecated "JSPAC" interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The deprecated Javascript OPAC interface known as "JSPAC" is no
-longer included in Evergreen as of this release.
-
-With the understanding that local sites may have made use of
-existing parts of the old JSPAC interface -- especially images and
-CSS -- no attempt is made at upgrade time to automatically remove
-the existing files from disk.
-
-When upgrading, you may wish to remove "index.xml" from your Apache
-DirectoryIndex directives.
-
-The following directories, xml, js, and css files were formerly part
-of JSPAC, and you may be able to safely remove them from your system
-after verifying that they and their contents are no longer required:
-
-- web/opac/common/css/
-- web/opac/common/js/dtree.js
-- web/opac/common/xml/
-- web/opac/extras/bbags.js
-- web/opac/extras/bbags.xml
-- web/opac/skin/default/js/
-- web/opac/skin/default/xml/
-- web/opac/theme/
-
-The list of images removed in this change is lengthy, and not
-included here.
-
-
-
-
-Removal of legacy selfcheck interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The legacy selfcheck interface is no longer included in Evergreen as
-of this release.
-
-This interface was formerly located at a URL ending in
-extras/selfcheck/selfcheck.xml
-
-No attempt is made at upgrade time to automatically remove this
-interface.
-
-It is recommended that you remove this interface and its associated
-configuration after performing an upgrade:
-
-(paths relative to Evergreen web root)
-
-- opac/extras/selfcheck/selfcheck.css
-- opac/extras/selfcheck/selfcheck.js
-- opac/extras/selfcheck/selfcheck.xml
-- opac/extras/selfcheck/selfcheck_print.css
-
-You can also remove the related Apache configuration block starting
-with:
-
-[source, conf]
-<LocationMatch .*/selfcheck.xml>
-
-
-
-
-Acknowledgments
-~~~~~~~~~~~~~~~
-The Evergreen project would like to acknowledge the following
-organizations who commissioned developments in this release of
-Evergreen:
-
- * Georgia Public Library Service
- * Grand Rapids Public Library
- * Kenton County Public Library
- * King County Library System
- * Massachusetts Library Network Cooperative
- * NC Cardinal
- * OhioNet
- * Pennsylvania Integrated Library System
-
-We would also like to thank the following individuals who contributed
-code, documentation patches and tests to this release of Evergreen:
-
- * Thomas Berezansky
- * Matt Berowski
- * Adam Bowling
- * Jason Boyer
- * Christine Burns
- * Galen Charlton
- * Bill Erickson
- * Jason Etheridge
- * Jeff Davis
- * Lynn Floyd
- * Jeff Godin
- * Angela Kilsdonk
- * Doug Kyle
- * Debbie Luchenbill
- * Kathy Lussier
- * Terran McCanna
- * Stephen Moss
- * Dan Pearl
- * Michael Peters
- * Mike Rylander
- * Jane Sandberg
- * Dan Scott
- * Ben Shum
- * Josh Stompro
- * Remington Steed
- * Jason Stephenson
- * Yamil Suarez
- * Dan Wells
- * Liam Whalen
-
-We also thank the following organizations whose employees contributed
-patches:
-
- * Anderson County Library
- * Berklee College of Music
- * Bibliomation
- * British Columbia Libraries Cooperative
- * Calvin College
- * Catalyst Dev Works
- * Central/Western Massachusetts Automated Resource Sharing
- * Emerald Data Networks, Inc.
- * Equinox Software, Inc.
- * Georgia Public Library Service
- * Grand Rapids Public Library
- * Indiana State Library
- * King County Library System
- * Lake Agassiz Regional Library
- * Laurentian University
- * Linn-Benton Community College
- * Massachusetts Library Network Cooperative
- * Merrimack Valley Library Consortium
- * MOBIUS
- * Northwest Regional Library System
- * Sigio
- * Traverse Area District Library
-
-We regret any omissions. If a contributor has been inadvertantly
-missed, please open a bug at http://bugs.launchpad.net/evergreen/
-with a correction.
-
--- /dev/null
+Calculated Proximity Adjustments
+================================
+
+Summary
+-------
+
+Today in Evergreen, the way in which organizational hierarchy can be taken into account during hold targeting and capture is through the evaluation of Org Unit Proximity. This is defined as the number of graph edges between Org Units, and for holds, specifically the distance between the capturing library and the pickup library. This value is used to rank sets of potential copies for holds based on their apparent nearness or proximity to the pickup lib at targeting time and to the checkin lib at op-capture time (in certain configurations).
+
+Evergreen needs a mechanism by which the proximity between libraries can be adjusted for the purpose of effecting hold capture. This will support several use cases, including, but not limited to:
+
+ * Causing a specific library to be targeted for holds in preference to all others.
+ * Causing a specific library to be targeted for holds in preference to all others except for the pickup library.
+ * Allowing transit distance to be more accurately reflected in hold order choice, for instance, causing nearby systems to have lower effective transit distances than widely separated systems.
+ * Reporting on the true cost of transiting items in a broadly distributed consortium.
+
+Overview
+--------
+
+Evergreen can be made to provide a way to specify two types of proximity adjustment: Relative and Absolute.
+
+Relative proximity adjustment will allow Org Units, and descendants thereof, to be treated as closer or farther from one another than the simple edge distance describes by adding or subtracting full or partial edge distance amounts to the baseline edge distance under configured circumstances.
+
+Absolute proximity adjustment will allow Org Units, and descendants thereof, to be viewed as having a specific distance from one another that replaces the baseline edge distance under configure circumstances. This will naturally have an impact on how potential copies are evaluated for their 'proximity' when targeting holds and capturing copies for holds.
+
+Plan
+----
+
+Create a configuration interface allowing certain item- and hold-level criteria to be evaluated at targeting time. Among the criteria would be:
+
+ * Item circ library (or ancestor thereof)
+ * Item owning library (or ancestor thereof)
+ * Hold pickup library (or ancestor thereof)
+ * Hold request library (or ancestor thereof)
+ * Item circ modifier
+ * Item shelving location
+
+At least one criterion must be supplied. These criteria would be ranked by order, and reordering allowed.
+
+In addition to these criteria, an Absolute or Relative proximity adjustment would be supplied. For Absolute proximity adjustments, the highest-ranked criteria-matching rule would be used for the copy. For Relative proximity adjustments, all applicable adjustments would be summed. In the case that both Absolute and Relative adjustments are found for the currently evaluated item and hold, the Absolute proximity adjustment will replace the baseline edge distance and then be modified by the Relative proximity adjustment calculation.
+
+To support both targeting-time and capture-time use of this derived proximity information, the calculated value will be stored on the hold-copy map. In conjunction with the Custom Best-hold Sort Order proposal, this information would then be available for use in choosing the hold to be filled by a particular copy.
+
+
+////
+vim: ft=asciidoc
+////
+++ /dev/null
-Calculated Proximity Adjustments
-================================
-
-Summary
--------
-
-Today in Evergreen, the way in which organizational hierarchy can be taken into account during hold targeting and capture is through the evaluation of Org Unit Proximity. This is defined as the number of graph edges between Org Units, and for holds, specifically the distance between the capturing library and the pickup library. This value is used to rank sets of potential copies for holds based on their apparent nearness or proximity to the pickup lib at targeting time and to the checkin lib at op-capture time (in certain configurations).
-
-Evergreen needs a mechanism by which the proximity between libraries can be adjusted for the purpose of effecting hold capture. This will support several use cases, including, but not limited to:
-
- * Causing a specific library to be targeted for holds in preference to all others.
- * Causing a specific library to be targeted for holds in preference to all others except for the pickup library.
- * Allowing transit distance to be more accurately reflected in hold order choice, for instance, causing nearby systems to have lower effective transit distances than widely separated systems.
- * Reporting on the true cost of transiting items in a broadly distributed consortium.
-
-Overview
---------
-
-Evergreen can be made to provide a way to specify two types of proximity adjustment: Relative and Absolute.
-
-Relative proximity adjustment will allow Org Units, and descendants thereof, to be treated as closer or farther from one another than the simple edge distance describes by adding or subtracting full or partial edge distance amounts to the baseline edge distance under configured circumstances.
-
-Absolute proximity adjustment will allow Org Units, and descendants thereof, to be viewed as having a specific distance from one another that replaces the baseline edge distance under configure circumstances. This will naturally have an impact on how potential copies are evaluated for their 'proximity' when targeting holds and capturing copies for holds.
-
-Plan
-----
-
-Create a configuration interface allowing certain item- and hold-level criteria to be evaluated at targeting time. Among the criteria would be:
-
- * Item circ library (or ancestor thereof)
- * Item owning library (or ancestor thereof)
- * Hold pickup library (or ancestor thereof)
- * Hold request library (or ancestor thereof)
- * Item circ modifier
- * Item shelving location
-
-At least one criterion must be supplied. These criteria would be ranked by order, and reordering allowed.
-
-In addition to these criteria, an Absolute or Relative proximity adjustment would be supplied. For Absolute proximity adjustments, the highest-ranked criteria-matching rule would be used for the copy. For Relative proximity adjustments, all applicable adjustments would be summed. In the case that both Absolute and Relative adjustments are found for the currently evaluated item and hold, the Absolute proximity adjustment will replace the baseline edge distance and then be modified by the Relative proximity adjustment calculation.
-
-To support both targeting-time and capture-time use of this derived proximity information, the calculated value will be stored on the hold-copy map. In conjunction with the Custom Best-hold Sort Order proposal, this information would then be available for use in choosing the hold to be filled by a particular copy.
-
-
-////
-vim: ft=asciidoc
-////
--- /dev/null
+Custom Best-Hold Selection
+==========================
+
+Background
+----------
+
+In the Evergreen ILS, during opportunistic capture (which occurs at copy
+checkin time), the copy being checked in is evaluated by the system for its
+fitness to fulfill outstanding holds. When the copy might fulfill more than
+one hold, a set of 'determinants' are used to rank the possible holds that
+might be fulfilled, so that the best hold may be chosen.
+
+Evergreen currently uses one of two possible sets of 'determinants' to rank
+the holds that a given copy might fulfill. An org-unit setting determines
+which set of 'determinants' is used.
+
+We will call these sets the "best-hold selection sort orders". The best-hold
+selection sort orders available for use at hold capture time are:
+
+Traditional
+~~~~~~~~~~~
+ . 'pprox' - Proximity of capturing location to pickup library
+ . 'priority' - Group hold priority
+ . 'cut' - Hold cut-in-line
+ . 'depth' - Hold selection depth (deeper/narrower first)
+ . 'rtime' - Hold request time
+
+FIFO
+~~~~
+ . 'priority' - Group hold priority
+ . 'cut' - Hold cut-in-line
+ . 'rtime' - Hold request time
+ . 'depth' - Hold selection depth (deeper/narrower first)
+ . 'pprox' - Proximity of capturing location to pickup library
+
+In either of these scenarios, a case could be made for changing the order of
+several fields. However, the use of these is currently controlled only by a
+single org-unit setting to turn on or off FIFO (if FIFO is "off," the
+Traditional set is used).
+
+Adding more org-unit settings to control yet more hard-coded orderings is a
+path to madness, and therefore we should support custom field ordering for
+best-hold selection.
+
+Proposal
+--------
+
+To that end, we propose a new table to define field importance, and a new org-
+unit setting to replace "FIFO Holds" and select the appropriate definition for
+the capturing location. The UI for creating or editing hold order definitions
+should consist of a list for ordering the options, controlled by up-and-down
+buttons both clickable and accessible by keyboard. There will also be a field
+for naming the definition and a save button.
+
+This org-unit setting will be retrieved at capture time, instead of the FIFO
+setting, and inspected by open-ils.storage.action.hold_request.nearest_hold.
+If no value is set, the equivalent of the "traditional" order will be used.
+
+An upgrade script will change all FIFO settings to version of the new setting
+which points to the system-supplied definition that implements FIFO as it
+stands today, thus avoiding functional changes and configuration problems.
+
+Design
+------
+
+Database Sketch
+~~~~~~~~~~~~~~~
+
+The 'config.best_hold_order' database table will have two metadata columns
+and eight data columns.
+
+Each of the eight data columns corresponds to a similarly named column used for
+ranking in the best-hold selection process (i.e., the 'determinants'). In a
+given row, the value of each of these columns corresponds to its relative
+priority in the ranking decision (lowest value representing the highest
+priority).
+
+Data columns with a null value have the effect of omitting the corresponding
+determinant in the ORDER BY clause for best-hold selection when the given
+best-hold selector order set is in play.
+
+One of the 'determinants', *aprox*, depends on the Calculated Proximity
+Adjustment enhancement (documented elsewhere).
+
+The 'determinant' *rtime*, which in practice is virtually unique among the
+set of all holds at a site, will always terminate the list of determinants
+used in constructing the ORDER BY clause whenever it appears. In other words,
+because *rtime* will never tie anyway, no more comparisons after rtime have
+any meaning.
+
+The default best-hold order sets sketched here are subject to refinement and
+are not guaranteed to represent the final product.
+
+[source,sql]
+------------------------------------------------------------------------------
+
+CREATE TABLE config.best_hold_order(
+ id SERIAL PRIMARY KEY, -- (metadata)
+ name TEXT UNIQUE, -- i18n (metadata)
+ pprox INT, -- copy capture <-> pickup lib prox
+ hprox INT, -- copy circ lib <-> request lib prox
+ aprox INT, -- copy circ lib <-> pickup lib ADJUSTED prox on ahcm
+ priority INT, -- group hold priority
+ cut INT, -- cut-in-line
+ depth INT, -- selection depth
+ htime INT, -- time since last home-lib circ exceeds org-unit setting
+ rtime INT -- request time
+);
+
+-- At least one of these columns must contain a non-null value
+ALTER TABLE config.best_hold_order ADD CHECK ((
+ pprox IS NOT NULL OR
+ hprox IS NOT NULL OR
+ aprox IS NOT NULL OR
+ priority IS NOT NULL OR
+ cut IS NOT NULL OR
+ depth IS NOT NULL OR
+ htime IS NOT NULL OR
+ rtime IS NOT NULL
+));
+
+INSERT INTO config.best_hold_order (
+ name,
+ pprox, aprox, priority, cut, depth, rtime, htime, hprox
+) VALUES (
+ 'Traditional',
+ 1, 2, 3, 4, 5, 6, 7, 8
+);
+
+INSERT INTO config.best_hold_order (
+ name,
+ hprox, pprox, aprox, priority, cut, depth, rtime, htime
+) VALUES (
+ 'Traditional with Holds-always-go-to-home-patrons',
+ 1, 2, 3, 4, 5, 6, 7, 8
+);
+
+INSERT INTO config.best_hold_order (
+ name,
+ htime, hprox, pprox, aprox, priority, cut, depth, rtime
+) VALUES (
+ 'Traditional with Holds-go-home',
+ 1, 2, 3, 4, 5, 6, 7, 8
+);
+
+INSERT INTO config.best_hold_order (
+ name,
+ priority, cut, rtime, depth, pprox, hprox, aprox, htime
+) VALUES (
+ 'FIFO',
+ 1, 2, 3, 4, 5, 6, 7, 8
+);
+
+INSERT INTO config.best_hold_order (
+ name,
+ hprox, priority, cut, rtime, depth, pprox, aprox, htime
+) VALUES (
+ 'FIFO with Holds-always-go-to-home-patrons',
+ 1, 2, 3, 4, 5, 6, 7, 8
+);
+
+INSERT INTO config.best_hold_order (
+ name,
+ htime, priority, cut, rtime, depth, pprox, aprox, hprox
+) VALUES (
+ 'FIFO with Holds-go-home',
+ 1, 2, 3, 4, 5, 6, 7, 8
+);
+
+INSERT INTO config.org_unit_setting_type (
+ name, label, description, datatype, fm_class, update_perm
+) VALUES (
+ 'circ.hold_capture_order',
+ 'Best-hold selection precedence',
+ 'Defines the sort order of holds when selecting a hold to fill using a given copy at capture time',
+ 'link',
+ 'cbho',
+ 'ADMIN_HOLD_CAPTURE_SORT'
+);
+
+INSERT INTO config.org_unit_setting_type (
+ name, label, description, datatype, update_perm
+) VALUES (
+ 'circ.hold_go_home_interval',
+ 'Max foreign-circulation time',
+ 'Time a copy can spend circulating away from its circ lib before returning there to fill a hold (if one exists there)',
+ 'interval',
+ 'ADMIN_HOLD_CAPTURE_SORT'
+);
+
+INSERT INTO actor.org_unit_setting (
+ org_unit, name, value
+) VALUES (
+ 1,
+ 'circ.hold_go_home_interval',
+ '6 months'
+);
+
+UPDATE actor.org_unit_setting SET
+ name = 'circ.hold_capture_order',
+ value = (SELECT id FROM config.hold_capture_sort WHERE name = 'FIFO')
+WHERE
+ name = 'circ.holds_fifo';
+------------------------------------------------------------------------------
+
+
+When constructing ORDER BY clauses, the *htime* determinant will be
+represented by a more complex expression than the other determinants. The
+likely form of this will be as follows:
+
+[source,sql]
+-----------------------------------------------
+CASE WHEN
+ ['value of org setting circ.hold_go_home_interval'] <
+ NOW() - ['timestamp of last circulation at copy circ lib']
+ THEN hprox -- sic
+ ELSE 999
+END
+
+-----------------------------------------------
+
+Middle Layer
+~~~~~~~~~~~~
+
+The 'open-ils.storage.action.hold_request.nearest_hold' method issues a query
+with an ORDER BY clause.
+
+This clause, previously selected from two hard-coded choices based on a
+boolean value indicating use- or don't-use-FIFO, will now be
+dynamically prepared based on the order specified in the
+'circ.hold_capture_order' org-unit setting.
+
+User Interface
+~~~~~~~~~~~~~~
+
+A user interface will allow the creation of new best-hold orders and the
+editing of existing ones, given sufficient user permission.
+
+The name field (metadata) will be editable with a free-form text widget, and
+the remaining (data) fields will be represented by objects that the user
+manipulates via clickable buttons (also keyboard accessible) to indicate order.
+
+////
+vim: ft=asciidoc
+////
+
+
+++ /dev/null
-Custom Best-Hold Selection
-==========================
-
-Background
-----------
-
-In the Evergreen ILS, during opportunistic capture (which occurs at copy
-checkin time), the copy being checked in is evaluated by the system for its
-fitness to fulfill outstanding holds. When the copy might fulfill more than
-one hold, a set of 'determinants' are used to rank the possible holds that
-might be fulfilled, so that the best hold may be chosen.
-
-Evergreen currently uses one of two possible sets of 'determinants' to rank
-the holds that a given copy might fulfill. An org-unit setting determines
-which set of 'determinants' is used.
-
-We will call these sets the "best-hold selection sort orders". The best-hold
-selection sort orders available for use at hold capture time are:
-
-Traditional
-~~~~~~~~~~~
- . 'pprox' - Proximity of capturing location to pickup library
- . 'priority' - Group hold priority
- . 'cut' - Hold cut-in-line
- . 'depth' - Hold selection depth (deeper/narrower first)
- . 'rtime' - Hold request time
-
-FIFO
-~~~~
- . 'priority' - Group hold priority
- . 'cut' - Hold cut-in-line
- . 'rtime' - Hold request time
- . 'depth' - Hold selection depth (deeper/narrower first)
- . 'pprox' - Proximity of capturing location to pickup library
-
-In either of these scenarios, a case could be made for changing the order of
-several fields. However, the use of these is currently controlled only by a
-single org-unit setting to turn on or off FIFO (if FIFO is "off," the
-Traditional set is used).
-
-Adding more org-unit settings to control yet more hard-coded orderings is a
-path to madness, and therefore we should support custom field ordering for
-best-hold selection.
-
-Proposal
---------
-
-To that end, we propose a new table to define field importance, and a new org-
-unit setting to replace "FIFO Holds" and select the appropriate definition for
-the capturing location. The UI for creating or editing hold order definitions
-should consist of a list for ordering the options, controlled by up-and-down
-buttons both clickable and accessible by keyboard. There will also be a field
-for naming the definition and a save button.
-
-This org-unit setting will be retrieved at capture time, instead of the FIFO
-setting, and inspected by open-ils.storage.action.hold_request.nearest_hold.
-If no value is set, the equivalent of the "traditional" order will be used.
-
-An upgrade script will change all FIFO settings to version of the new setting
-which points to the system-supplied definition that implements FIFO as it
-stands today, thus avoiding functional changes and configuration problems.
-
-Design
-------
-
-Database Sketch
-~~~~~~~~~~~~~~~
-
-The 'config.best_hold_order' database table will have two metadata columns
-and eight data columns.
-
-Each of the eight data columns corresponds to a similarly named column used for
-ranking in the best-hold selection process (i.e., the 'determinants'). In a
-given row, the value of each of these columns corresponds to its relative
-priority in the ranking decision (lowest value representing the highest
-priority).
-
-Data columns with a null value have the effect of omitting the corresponding
-determinant in the ORDER BY clause for best-hold selection when the given
-best-hold selector order set is in play.
-
-One of the 'determinants', *aprox*, depends on the Calculated Proximity
-Adjustment enhancement (documented elsewhere).
-
-The 'determinant' *rtime*, which in practice is virtually unique among the
-set of all holds at a site, will always terminate the list of determinants
-used in constructing the ORDER BY clause whenever it appears. In other words,
-because *rtime* will never tie anyway, no more comparisons after rtime have
-any meaning.
-
-The default best-hold order sets sketched here are subject to refinement and
-are not guaranteed to represent the final product.
-
-[source,sql]
-------------------------------------------------------------------------------
-
-CREATE TABLE config.best_hold_order(
- id SERIAL PRIMARY KEY, -- (metadata)
- name TEXT UNIQUE, -- i18n (metadata)
- pprox INT, -- copy capture <-> pickup lib prox
- hprox INT, -- copy circ lib <-> request lib prox
- aprox INT, -- copy circ lib <-> pickup lib ADJUSTED prox on ahcm
- priority INT, -- group hold priority
- cut INT, -- cut-in-line
- depth INT, -- selection depth
- htime INT, -- time since last home-lib circ exceeds org-unit setting
- rtime INT -- request time
-);
-
--- At least one of these columns must contain a non-null value
-ALTER TABLE config.best_hold_order ADD CHECK ((
- pprox IS NOT NULL OR
- hprox IS NOT NULL OR
- aprox IS NOT NULL OR
- priority IS NOT NULL OR
- cut IS NOT NULL OR
- depth IS NOT NULL OR
- htime IS NOT NULL OR
- rtime IS NOT NULL
-));
-
-INSERT INTO config.best_hold_order (
- name,
- pprox, aprox, priority, cut, depth, rtime, htime, hprox
-) VALUES (
- 'Traditional',
- 1, 2, 3, 4, 5, 6, 7, 8
-);
-
-INSERT INTO config.best_hold_order (
- name,
- hprox, pprox, aprox, priority, cut, depth, rtime, htime
-) VALUES (
- 'Traditional with Holds-always-go-to-home-patrons',
- 1, 2, 3, 4, 5, 6, 7, 8
-);
-
-INSERT INTO config.best_hold_order (
- name,
- htime, hprox, pprox, aprox, priority, cut, depth, rtime
-) VALUES (
- 'Traditional with Holds-go-home',
- 1, 2, 3, 4, 5, 6, 7, 8
-);
-
-INSERT INTO config.best_hold_order (
- name,
- priority, cut, rtime, depth, pprox, hprox, aprox, htime
-) VALUES (
- 'FIFO',
- 1, 2, 3, 4, 5, 6, 7, 8
-);
-
-INSERT INTO config.best_hold_order (
- name,
- hprox, priority, cut, rtime, depth, pprox, aprox, htime
-) VALUES (
- 'FIFO with Holds-always-go-to-home-patrons',
- 1, 2, 3, 4, 5, 6, 7, 8
-);
-
-INSERT INTO config.best_hold_order (
- name,
- htime, priority, cut, rtime, depth, pprox, aprox, hprox
-) VALUES (
- 'FIFO with Holds-go-home',
- 1, 2, 3, 4, 5, 6, 7, 8
-);
-
-INSERT INTO config.org_unit_setting_type (
- name, label, description, datatype, fm_class, update_perm
-) VALUES (
- 'circ.hold_capture_order',
- 'Best-hold selection precedence',
- 'Defines the sort order of holds when selecting a hold to fill using a given copy at capture time',
- 'link',
- 'cbho',
- 'ADMIN_HOLD_CAPTURE_SORT'
-);
-
-INSERT INTO config.org_unit_setting_type (
- name, label, description, datatype, update_perm
-) VALUES (
- 'circ.hold_go_home_interval',
- 'Max foreign-circulation time',
- 'Time a copy can spend circulating away from its circ lib before returning there to fill a hold (if one exists there)',
- 'interval',
- 'ADMIN_HOLD_CAPTURE_SORT'
-);
-
-INSERT INTO actor.org_unit_setting (
- org_unit, name, value
-) VALUES (
- 1,
- 'circ.hold_go_home_interval',
- '6 months'
-);
-
-UPDATE actor.org_unit_setting SET
- name = 'circ.hold_capture_order',
- value = (SELECT id FROM config.hold_capture_sort WHERE name = 'FIFO')
-WHERE
- name = 'circ.holds_fifo';
-------------------------------------------------------------------------------
-
-
-When constructing ORDER BY clauses, the *htime* determinant will be
-represented by a more complex expression than the other determinants. The
-likely form of this will be as follows:
-
-[source,sql]
------------------------------------------------
-CASE WHEN
- ['value of org setting circ.hold_go_home_interval'] <
- NOW() - ['timestamp of last circulation at copy circ lib']
- THEN hprox -- sic
- ELSE 999
-END
-
------------------------------------------------
-
-Middle Layer
-~~~~~~~~~~~~
-
-The 'open-ils.storage.action.hold_request.nearest_hold' method issues a query
-with an ORDER BY clause.
-
-This clause, previously selected from two hard-coded choices based on a
-boolean value indicating use- or don't-use-FIFO, will now be
-dynamically prepared based on the order specified in the
-'circ.hold_capture_order' org-unit setting.
-
-User Interface
-~~~~~~~~~~~~~~
-
-A user interface will allow the creation of new best-hold orders and the
-editing of existing ones, given sufficient user permission.
-
-The name field (metadata) will be editable with a free-form text widget, and
-the remaining (data) fields will be represented by objects that the user
-manipulates via clickable buttons (also keyboard accessible) to indicate order.
-
-////
-vim: ft=asciidoc
-////
-
-
--- /dev/null
+Holds Go Home
+=============
+
+Outline
+-------
+
+A copy prefers to fulfill a hold near its home when:
+
+ - The last event for a copy was NOT at home *and* ...
+ - The copy has not circulated from home within the defined period *and* ...
+ - The copy has neither departed from home by transit nor arrived at home
+ by transit within the defined period.
+
+Definitions
+-----------
+
+In the preceding section, some terms are used that want explanation.
+
+_Event_ refers to either a circulation or a transit related to a copy. An
+event has only two qualities we care about: moment and place.
+
+ - When the event comes from a circulation, _moment_ is checkin_time if
+ we have it, otherwise xact_start. When the event comes from a transit,
+ moment is dest_recv_time if we have it, otherwise source_send_time.
+
+ - When the event comes from a circulation, _place_ is checkin_lib if we
+ have it, otherwise circ_lib. When the event comes from a transit,
+ place is dest, *always*.
+
+ - When the copy in question has neither any transit history nor any
+ circulation history, we produce a synthetic event with _moment_ equal
+ to the present time, and _place_ equal to the copy's call number's
+ owning_lib (see 'home' below).
+
+_Home_ is the value of the copy's call number's owning_lib field, which
+incidentally is usually equal to the copy's circ_lib field except where
+floating is in use.
+
+_The defined period_ is the time between the present moment (_NOW()_
+to the database) and the present moment less the value of the interval
+defined in the _circ.hold_go_home_interval_ org unit setting at a scope
+of the copy's _home_. E.g., if the setting contains the string "6 months",
+the defined period is the last 6 months before the present moment, or
+anything greater than _NOW() - '6 months'::INTERVAL_.
+
+Logic
+-----
+
+............................................
+
+ -------
+| Event |
+ -------
+ |
+ |
+ v
+ ------------------------- -----------------------
+| Was last event at home? | -----Yes.-----> | Don't try to go home. |
+ ------------------------- -----------------------
+ | ^ ^
+ | No. | |
+ v | |
+ ------------------------------------------------ | |
+| Did copy circ from home during defined period? |--Yes.--/ |
+ ------------------------------------------------ |
+ | |
+ | No. |
+ | |
+ v |
+ ------------------------------------------------------ |
+| Did copy leave or arrive home during defined period? |--Yes.---/
+ ------------------------------------------------------
+ |
+ | No.
+ |
+ v
+ ----------
+| Go home. |
+ ----------
+
+............................................
+
+
+Implications in Best-Hold Selection Sort Order
+----------------------------------------------
+
+The calculations described above are all embodied in the best-hold selection
+sort order determinant _shtime_.
+
+_htime_ is a simpler version of the same, with all reference to transits
+removed, considering only circulations. This means events become thin
+circulations, the "Did a transit bring copy home..." step in the flow chart
+goes away, etc. etc.
+++ /dev/null
-Holds Go Home
-=============
-
-Outline
--------
-
-A copy prefers to fulfill a hold near its home when:
-
- - The last event for a copy was NOT at home *and* ...
- - The copy has not circulated from home within the defined period *and* ...
- - The copy has neither departed from home by transit nor arrived at home
- by transit within the defined period.
-
-Definitions
------------
-
-In the preceding section, some terms are used that want explanation.
-
-_Event_ refers to either a circulation or a transit related to a copy. An
-event has only two qualities we care about: moment and place.
-
- - When the event comes from a circulation, _moment_ is checkin_time if
- we have it, otherwise xact_start. When the event comes from a transit,
- moment is dest_recv_time if we have it, otherwise source_send_time.
-
- - When the event comes from a circulation, _place_ is checkin_lib if we
- have it, otherwise circ_lib. When the event comes from a transit,
- place is dest, *always*.
-
- - When the copy in question has neither any transit history nor any
- circulation history, we produce a synthetic event with _moment_ equal
- to the present time, and _place_ equal to the copy's call number's
- owning_lib (see 'home' below).
-
-_Home_ is the value of the copy's call number's owning_lib field, which
-incidentally is usually equal to the copy's circ_lib field except where
-floating is in use.
-
-_The defined period_ is the time between the present moment (_NOW()_
-to the database) and the present moment less the value of the interval
-defined in the _circ.hold_go_home_interval_ org unit setting at a scope
-of the copy's _home_. E.g., if the setting contains the string "6 months",
-the defined period is the last 6 months before the present moment, or
-anything greater than _NOW() - '6 months'::INTERVAL_.
-
-Logic
------
-
-............................................
-
- -------
-| Event |
- -------
- |
- |
- v
- ------------------------- -----------------------
-| Was last event at home? | -----Yes.-----> | Don't try to go home. |
- ------------------------- -----------------------
- | ^ ^
- | No. | |
- v | |
- ------------------------------------------------ | |
-| Did copy circ from home during defined period? |--Yes.--/ |
- ------------------------------------------------ |
- | |
- | No. |
- | |
- v |
- ------------------------------------------------------ |
-| Did copy leave or arrive home during defined period? |--Yes.---/
- ------------------------------------------------------
- |
- | No.
- |
- v
- ----------
-| Go home. |
- ----------
-
-............................................
-
-
-Implications in Best-Hold Selection Sort Order
-----------------------------------------------
-
-The calculations described above are all embodied in the best-hold selection
-sort order determinant _shtime_.
-
-_htime_ is a simpler version of the same, with all reference to transits
-removed, considering only circulations. This means events become thin
-circulations, the "Did a transit bring copy home..." step in the flow chart
-goes away, etc. etc.
--- /dev/null
+Deep-data Flattening Service
+============================
+Mike Rylander
+with Lebbeous Fogle-Weekley
+
+[abstract]
+Purpose
+-------
+Evergreen supplies a broad API for accessing, processing and interacting with library data. Because of the relatively complex nature of the underlying database schema, and the flexibility required by clients when, in the simplest case, performing CRUD operations, focus has been given to providing a nearly direct view of various data source. When, however, the verbosity or complexity of full object access gets in the way of performant or straight-forward UIs, there has been a tendency to create one-off data simplification calls targeting specific use cases.
+
+A generalized API which accepts a simplified query structure and field mapping, calculates the required backend query, and flattens the hierarchical data returned for each top level row into a would facilitate the simplification of existing UIs and provide for new UIs based on simple, reusable components.
+
+Overview
+--------
+The existing, public open-ils.fielder server will be extended with two new OpenSRF methods, contained in a separate package so that they will be reusable in a private service which does not require authentication.
+
+These methods will be supported by code which takes simplified cstore/pcrud search and order-by hashes and computes the full data structure required for the query. The simplification will leverage the IDL to discover links between classes.
+
+Underlying the simplified search grammar will be a path-field mapping structure. This will describe the layout of fields, how they are to collapse from fleshed objects, and how the shape of both the query and result data structures should be interpreted by and presented to the caller.
+
+Mapping Structure
+-----------------
+Implemented as a JSON object, each property name will represent a data element that can be displayed, filtered or sorted, and each property value will represent either a simple path (in which case it is usable for display, filtering or sorting), or an object providing the path and available uses.
+
+Example Map
+~~~~~~~~~~~
+Assuming a core class of acp:
+
+--------------------------------------------------------------------------------
+{
+ "barcode": "barcode",
+ "circ_lib_name": "circ_lib.name",
+ "circ_lib": "circ_lib.shortname",
+ "call_number": { "path": "call_number.label", "sort": true, "display": true },
+ "tcn": { "path": "call_number.record.tcn_value", "filter": true, "sort": true }
+}
+--------------------------------------------------------------------------------
+
+'Yes I realize that this example ignores call number prefixes and suffixes, but it's just an example.'
+
+Based on this mapping structure simplified queries can be constructed by the caller, which will then be expanded in the flattening service to produce join and where clauses that can be used by open-ils.pcrud.
+
+Example Query
+~~~~~~~~~~~~~
+Assuming the above example map:
+
+-------------------------------------
+{ "tcn": { ">": "100" },
+ "circ_lib": "BR1"
+}
+-------------------------------------
+
+This example would expand to a PCrud query based on the map provided above, containing not only the complex where clause, but a join tree and the necessary fleshing structure.
+
+
+Expanded PCrud Query
+~~~~~~~~~~~~~~~~~~~~
+
+---------------------------------------
+{
+ "+__circ_lib_aou": {"shortname":"BR1"},
+ "+__tcn_bre":{"tcn_value":{">":"100"}}
+}, {
+ "flesh_fields": {
+ "acp":["call_number", "circ_lib"]
+ },"flesh":1,
+ "join": {
+ "__circ_lib_name_aou": {
+ "fkey":"circ_lib",
+ "class":"aou",
+ "field":"id"
+ },
+ "__call_number_acn":{
+ "fkey":"call_number",
+ "class":"acn",
+ "field":"id"
+ },
+ "__tcn_acn":{
+ "fkey":"call_number",
+ "class":"acn",
+ "field":"id",
+ "join":{
+ "__tcn_bre":{
+ "fkey":"record",
+ "class":"bre",
+ "field":"id"
+ }
+ }
+ },
+ "__circ_lib_aou":{
+ "fkey":"circ_lib",
+ "class":"aou",
+ "field":"id"
+ }
+ }
+}
+---------------------------------------
+
+
+API
+---
+
+OpenSRF Method name: open-ils.fielder.flattened_search
+
+Parameters:
+
+- Authentication token (as for pcrud)
+- IDL class
+ * e.g. "acp"
+- Path map hash
+ * e.g. { "barcode": "barcode", "circ_lib_name": "circ_lib.name", "circ_lib": "circ_lib.shortname", "call_number": { "path": "call_number.label", "sort": true, "display": true }, "id": "id", "tcn": { "path": "call_number.record.tcn_value", "filter": true, "sort": true } }
+- Simplified query hash
+ * e.g. {"tcn": {">": "100" }, "circ_lib": "BR1"}
+- Simplified sort/limit/offset hash
+ * e.g. { "sort":[{"circ_lib":"desc"},{"call_number":"asc"}],"limit":10 }
+ * or {"sort":{"call_number":"desc"}}
+ * or {"sort": "circ_lib"}
+ * or {"sort": ["circ_lib", {"checkin_time": "desc"}]}
+
+Returns:
+
+- stream (or array, for .atomic) of hashes having the shape described in the path map
+ * e.g. { "call_number":"PR3533.B61994", "circ_lib_name":"Example Branch 1", "barcode":"23624564258", "id":7, "circ_lib":"BR1" }
+
+++ /dev/null
-Deep-data Flattening Service
-============================
-Mike Rylander
-with Lebbeous Fogle-Weekley
-
-[abstract]
-Purpose
--------
-Evergreen supplies a broad API for accessing, processing and interacting with library data. Because of the relatively complex nature of the underlying database schema, and the flexibility required by clients when, in the simplest case, performing CRUD operations, focus has been given to providing a nearly direct view of various data source. When, however, the verbosity or complexity of full object access gets in the way of performant or straight-forward UIs, there has been a tendency to create one-off data simplification calls targeting specific use cases.
-
-A generalized API which accepts a simplified query structure and field mapping, calculates the required backend query, and flattens the hierarchical data returned for each top level row into a would facilitate the simplification of existing UIs and provide for new UIs based on simple, reusable components.
-
-Overview
---------
-The existing, public open-ils.fielder server will be extended with two new OpenSRF methods, contained in a separate package so that they will be reusable in a private service which does not require authentication.
-
-These methods will be supported by code which takes simplified cstore/pcrud search and order-by hashes and computes the full data structure required for the query. The simplification will leverage the IDL to discover links between classes.
-
-Underlying the simplified search grammar will be a path-field mapping structure. This will describe the layout of fields, how they are to collapse from fleshed objects, and how the shape of both the query and result data structures should be interpreted by and presented to the caller.
-
-Mapping Structure
------------------
-Implemented as a JSON object, each property name will represent a data element that can be displayed, filtered or sorted, and each property value will represent either a simple path (in which case it is usable for display, filtering or sorting), or an object providing the path and available uses.
-
-Example Map
-~~~~~~~~~~~
-Assuming a core class of acp:
-
---------------------------------------------------------------------------------
-{
- "barcode": "barcode",
- "circ_lib_name": "circ_lib.name",
- "circ_lib": "circ_lib.shortname",
- "call_number": { "path": "call_number.label", "sort": true, "display": true },
- "tcn": { "path": "call_number.record.tcn_value", "filter": true, "sort": true }
-}
---------------------------------------------------------------------------------
-
-'Yes I realize that this example ignores call number prefixes and suffixes, but it's just an example.'
-
-Based on this mapping structure simplified queries can be constructed by the caller, which will then be expanded in the flattening service to produce join and where clauses that can be used by open-ils.pcrud.
-
-Example Query
-~~~~~~~~~~~~~
-Assuming the above example map:
-
--------------------------------------
-{ "tcn": { ">": "100" },
- "circ_lib": "BR1"
-}
--------------------------------------
-
-This example would expand to a PCrud query based on the map provided above, containing not only the complex where clause, but a join tree and the necessary fleshing structure.
-
-
-Expanded PCrud Query
-~~~~~~~~~~~~~~~~~~~~
-
----------------------------------------
-{
- "+__circ_lib_aou": {"shortname":"BR1"},
- "+__tcn_bre":{"tcn_value":{">":"100"}}
-}, {
- "flesh_fields": {
- "acp":["call_number", "circ_lib"]
- },"flesh":1,
- "join": {
- "__circ_lib_name_aou": {
- "fkey":"circ_lib",
- "class":"aou",
- "field":"id"
- },
- "__call_number_acn":{
- "fkey":"call_number",
- "class":"acn",
- "field":"id"
- },
- "__tcn_acn":{
- "fkey":"call_number",
- "class":"acn",
- "field":"id",
- "join":{
- "__tcn_bre":{
- "fkey":"record",
- "class":"bre",
- "field":"id"
- }
- }
- },
- "__circ_lib_aou":{
- "fkey":"circ_lib",
- "class":"aou",
- "field":"id"
- }
- }
-}
----------------------------------------
-
-
-API
----
-
-OpenSRF Method name: open-ils.fielder.flattened_search
-
-Parameters:
-
-- Authentication token (as for pcrud)
-- IDL class
- * e.g. "acp"
-- Path map hash
- * e.g. { "barcode": "barcode", "circ_lib_name": "circ_lib.name", "circ_lib": "circ_lib.shortname", "call_number": { "path": "call_number.label", "sort": true, "display": true }, "id": "id", "tcn": { "path": "call_number.record.tcn_value", "filter": true, "sort": true } }
-- Simplified query hash
- * e.g. {"tcn": {">": "100" }, "circ_lib": "BR1"}
-- Simplified sort/limit/offset hash
- * e.g. { "sort":[{"circ_lib":"desc"},{"call_number":"asc"}],"limit":10 }
- * or {"sort":{"call_number":"desc"}}
- * or {"sort": "circ_lib"}
- * or {"sort": ["circ_lib", {"checkin_time": "desc"}]}
-
-Returns:
-
-- stream (or array, for .atomic) of hashes having the shape described in the path map
- * e.g. { "call_number":"PR3533.B61994", "circ_lib_name":"Example Branch 1", "barcode":"23624564258", "id":7, "circ_lib":"BR1" }
-
--- /dev/null
+Kid's OPAC Configuration
+========================
+
+Configuration
+-------------
+
+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>
+------------------------------------------------------------------------------
+
+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.
+
+[source, xml]
+------------------------------------------------------------------------------
+<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.
+
+[source, xml]
+------------------------------------------------------------------------------
+<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.
+
+[source, xml]
+------------------------------------------------------------------------------
+<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.
+
+[source, xml]
+------------------------------------------------------------------------------
+<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.
+
+[source, xml]
+------------------------------------------------------------------------------
+<cell name="Clarinet" img="category.png"
+ type="link">http://en.wikipedia.org/wiki/Clarinet</cell>
+------------------------------------------------------------------------------
+
+
+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 <<_how_to_override_templates,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.
+
+[source, bash]
+------------------------------------------------------------------------------
+% 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>
+-------------------------------------------------------------------------------
+
+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.
+
+Outstanding Development (Unsponsored)
+-------------------------------------
+
+ ** Port the XML configuration file to a DB structure, complete with UI for
+ managing the various components and upgrade path.
+
+++ /dev/null
-Kid's OPAC Configuration
-========================
-
-Configuration
--------------
-
-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>
-------------------------------------------------------------------------------
-
-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.
-
-[source, xml]
-------------------------------------------------------------------------------
-<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.
-
-[source, xml]
-------------------------------------------------------------------------------
-<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.
-
-[source, xml]
-------------------------------------------------------------------------------
-<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.
-
-[source, xml]
-------------------------------------------------------------------------------
-<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.
-
-[source, xml]
-------------------------------------------------------------------------------
-<cell name="Clarinet" img="category.png"
- type="link">http://en.wikipedia.org/wiki/Clarinet</cell>
-------------------------------------------------------------------------------
-
-
-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 <<_how_to_override_templates,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.
-
-[source, bash]
-------------------------------------------------------------------------------
-% 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>
--------------------------------------------------------------------------------
-
-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.
-
-Outstanding Development (Unsponsored)
--------------------------------------
-
- ** Port the XML configuration file to a DB structure, complete with UI for
- managing the various components and upgrade path.
-
--- /dev/null
+URL Verification
+================
+
+Evergreen now has ability to verify URLs, which it is hoped, will be of
+particular benefit to locations with large electronic resource collections.
+
+Overview
+--------
+
+In order to support verification of URLs, Evergreen now has several new
+capabilities, and extensions to some existing features.
+
+A wizard-style interface that walks a staff member through the process of collecting records and URLs to verify, verifying and reviewing the URLs.
+
+URL validation sessions are built as a whole to support immediate and
+future review of any URLs. Each session carries a name, an owner, a set
+of record search criteria, a set of tag and subfield combinations describing
+the location of URLs to validate, a record container for tracking individual
+records to verify, and a set of state and data tables for managing the
+processing of individual URLs.
+
+A set of middle-layer methods provide the business logic required to collect
+records, extract, parse and test the validity of the URLs.
+
+Workflow
+--------
+
+URL verification and update are be performed as a series of coordinated phases.
+
+ * Phase 1 - Select or Create a session
+ ** Collect the owner and name of the session, providing appropriate defaults
+ ** Collect a set of saved and immediately-entered searches for the purpose of targeting records, and store a single derived search
+ ** Collect a set of tag and subfield combinations describing the locations of interest that contain URLs within records found by the above search. Store these as xpath.
+ ** Offer a "Process immediately" option to skip Phase 4 (not skip to Phase 4, but skip Phase 4 itself) -- See below for details.
+ * Phase 2 - Search for and collect records of interest
+ ** Create a new bib record container of type "url-validate" and link this to the session record created in Phase 1
+ ** Run the search, and store the full set of record IDs in the "url-validate" container
+ * Phase 3 - Extract URLs from collected records
+ ** Inspect each record that we just placed into the container, and use the tag/subfield XPath expressions to extract any URLs
+ ** Extract any relevant data and store
+ *** Container entry pointing to the record from which it came
+ *** Tag and subfield from which it came
+ *** The full content
+ *** Scheme
+ *** Host
+ *** Domain
+ *** TLD
+ *** Path
+ *** Page (last component of Path)
+ *** Query
+ *** Fragment
+ * Phase 4 - Search/Filter/Sort URLs
+ ** Skip this step if "Process immediately" was selected during session setup in Phase 1
+ ** Else, display an interface for selecting which URLs and records to process based on any component extracted and stored during Phase 3.
+ * Phase 5 - Validate Selected/All URLs
+ ** Accept a list of extracted URL IDs from the previous step, or if no filtering done, all URLs
+ ** For each unique URL in the set, make a HTTP HEAD request to test validity
+ *** YAOUS for timeout value
+ *** YAOUS for sleep period between each URL test
+ *** For duplicated URLs, test only once and share the result across all instances
+ *** Avoid testing URLs having the same domain sequentially
+ ** Store HTTP response code
+ ** IFF 3XX (redirect) code is returned
+ *** Parse the new target URL, linking to the original
+ *** Repeat as necessary, up to a sanity limit on redirect depth (YAOUS)
+ *** Use a lookup table of hashes of URLs already redirected to (for the given original URL), to avoid loops
+ * Phase 6 - Validation Status Report
+ ** Display a summary breakdown of HTTP statuses and overall completion
+ ** Offer an interface to Search/Filter/Sort URLs for inspection based on any component extracted and stored during Phase 3 as well as HTTP status of the originally extracted URL. Included in this display should be the endpoint of any HTTP redirection the server requested.
+
+Development Breakdown
+---------------------
+
+ * Database -- The database has been augmented with new tables to store and process bibliographic records as they are collected for URL verification
+ ** Session state
+ ** Session configuration
+ ** Container type
+ ** URL data and state storage
+ * Middle Layer -- Several new API calls, culminating in a new OpenSRF service created to implement the required business logic.
+ ** Session and Configuration management
+ ** Session selection
+ ** Record discovery
+ ** Progress calculation
+ * User Interface -- Several new interface components have been created to drive the use of the new OpenSRF APIs
+ ** Session management
+ ** Configuration management
+ ** Extracted URL display (Search/Filter/Sort)
+ ** Summary status display
+
+User Interface
+--------------
+The user interface embodies the workflow section above. Displays of URLs for verification and then post-verification review make use of openils.widget.FlattenerGrid.
+
+First Change to FlattenerFilterDialog
+-------------------------------------
+
+FlattenerFilterDialog has gained the ability to save a set of filter conditions via a Save button (optionally displayed) which calls a callback at onClick.
+
+FlattenerFilterDialog now has a clean way to load a saved set of filter conditions (this part should be largely there already, see Trigger Event Log for similar).
+
+The mechanism to which this instance of FlattenerFilterDialog saves sets of conditions (and from which it will load them) uses a dialog that allows a user to choose sets of conditions to load and uses a DB table to store them in.
+
+Second Change to FlattenerFilterDialog
+--------------------------------------
+
+We also now support IN and NOT IN operators. The operand widget is be the same as if for a typical unary operator (any of them but 'between') plus an adder (label probably '[+]') and a multiselect, the valueset of which is augmented with every click of the adder.
+
+Here's why this is needed. Imagine needing to filter URLs in this way: say you want urls only from the "http" scheme and matching neither the domain example.com nor example.net. If you did this with FlattenerFilterDialog today, the result of setting up three conditions as described above would be (scheme = 'http' and (domain <> 'example.com' or domain <> 'example.net')) which is effectively the same as having no filter on domain at all.
+
+It worked that way before because until now it was only designed for equalities, not inequalities (compare to the situation where your three conditions are scheme is http, domain IS either example.com, example.net).
+
+The multiselect scheme described above allows clauses in the WHERE constraint that look like (domain not in ('example.com','example.net')).
+
+++ /dev/null
-URL Verification
-================
-
-Evergreen now has ability to verify URLs, which it is hoped, will be of
-particular benefit to locations with large electronic resource collections.
-
-Overview
---------
-
-In order to support verification of URLs, Evergreen now has several new
-capabilities, and extensions to some existing features.
-
-A wizard-style interface that walks a staff member through the process of collecting records and URLs to verify, verifying and reviewing the URLs.
-
-URL validation sessions are built as a whole to support immediate and
-future review of any URLs. Each session carries a name, an owner, a set
-of record search criteria, a set of tag and subfield combinations describing
-the location of URLs to validate, a record container for tracking individual
-records to verify, and a set of state and data tables for managing the
-processing of individual URLs.
-
-A set of middle-layer methods provide the business logic required to collect
-records, extract, parse and test the validity of the URLs.
-
-Workflow
---------
-
-URL verification and update are be performed as a series of coordinated phases.
-
- * Phase 1 - Select or Create a session
- ** Collect the owner and name of the session, providing appropriate defaults
- ** Collect a set of saved and immediately-entered searches for the purpose of targeting records, and store a single derived search
- ** Collect a set of tag and subfield combinations describing the locations of interest that contain URLs within records found by the above search. Store these as xpath.
- ** Offer a "Process immediately" option to skip Phase 4 (not skip to Phase 4, but skip Phase 4 itself) -- See below for details.
- * Phase 2 - Search for and collect records of interest
- ** Create a new bib record container of type "url-validate" and link this to the session record created in Phase 1
- ** Run the search, and store the full set of record IDs in the "url-validate" container
- * Phase 3 - Extract URLs from collected records
- ** Inspect each record that we just placed into the container, and use the tag/subfield XPath expressions to extract any URLs
- ** Extract any relevant data and store
- *** Container entry pointing to the record from which it came
- *** Tag and subfield from which it came
- *** The full content
- *** Scheme
- *** Host
- *** Domain
- *** TLD
- *** Path
- *** Page (last component of Path)
- *** Query
- *** Fragment
- * Phase 4 - Search/Filter/Sort URLs
- ** Skip this step if "Process immediately" was selected during session setup in Phase 1
- ** Else, display an interface for selecting which URLs and records to process based on any component extracted and stored during Phase 3.
- * Phase 5 - Validate Selected/All URLs
- ** Accept a list of extracted URL IDs from the previous step, or if no filtering done, all URLs
- ** For each unique URL in the set, make a HTTP HEAD request to test validity
- *** YAOUS for timeout value
- *** YAOUS for sleep period between each URL test
- *** For duplicated URLs, test only once and share the result across all instances
- *** Avoid testing URLs having the same domain sequentially
- ** Store HTTP response code
- ** IFF 3XX (redirect) code is returned
- *** Parse the new target URL, linking to the original
- *** Repeat as necessary, up to a sanity limit on redirect depth (YAOUS)
- *** Use a lookup table of hashes of URLs already redirected to (for the given original URL), to avoid loops
- * Phase 6 - Validation Status Report
- ** Display a summary breakdown of HTTP statuses and overall completion
- ** Offer an interface to Search/Filter/Sort URLs for inspection based on any component extracted and stored during Phase 3 as well as HTTP status of the originally extracted URL. Included in this display should be the endpoint of any HTTP redirection the server requested.
-
-Development Breakdown
----------------------
-
- * Database -- The database has been augmented with new tables to store and process bibliographic records as they are collected for URL verification
- ** Session state
- ** Session configuration
- ** Container type
- ** URL data and state storage
- * Middle Layer -- Several new API calls, culminating in a new OpenSRF service created to implement the required business logic.
- ** Session and Configuration management
- ** Session selection
- ** Record discovery
- ** Progress calculation
- * User Interface -- Several new interface components have been created to drive the use of the new OpenSRF APIs
- ** Session management
- ** Configuration management
- ** Extracted URL display (Search/Filter/Sort)
- ** Summary status display
-
-User Interface
---------------
-The user interface embodies the workflow section above. Displays of URLs for verification and then post-verification review make use of openils.widget.FlattenerGrid.
-
-First Change to FlattenerFilterDialog
--------------------------------------
-
-FlattenerFilterDialog has gained the ability to save a set of filter conditions via a Save button (optionally displayed) which calls a callback at onClick.
-
-FlattenerFilterDialog now has a clean way to load a saved set of filter conditions (this part should be largely there already, see Trigger Event Log for similar).
-
-The mechanism to which this instance of FlattenerFilterDialog saves sets of conditions (and from which it will load them) uses a dialog that allows a user to choose sets of conditions to load and uses a DB table to store them in.
-
-Second Change to FlattenerFilterDialog
---------------------------------------
-
-We also now support IN and NOT IN operators. The operand widget is be the same as if for a typical unary operator (any of them but 'between') plus an adder (label probably '[+]') and a multiselect, the valueset of which is augmented with every click of the adder.
-
-Here's why this is needed. Imagine needing to filter URLs in this way: say you want urls only from the "http" scheme and matching neither the domain example.com nor example.net. If you did this with FlattenerFilterDialog today, the result of setting up three conditions as described above would be (scheme = 'http' and (domain <> 'example.com' or domain <> 'example.net')) which is effectively the same as having no filter on domain at all.
-
-It worked that way before because until now it was only designed for equalities, not inequalities (compare to the situation where your three conditions are scheme is http, domain IS either example.com, example.net).
-
-The multiselect scheme described above allows clauses in the WHERE constraint that look like (domain not in ('example.com','example.net')).
-
--- /dev/null
+Setting up Telephone Notices with Evergreen
+===========================================
+
+[abstract]
+What is this document good for?
+-------------------------------
+This is telephony based on Asterisk and Action/Trigger for Evergreen 2.2 and up.
+
+If you've never done this before, you should *really* read this document all the way through before you begin, so that you have some idea of what to expect and how much time to schedule for it.
+
+This document should lead you through getting overdue telephone notices set up for Evergreen. This document is long, but it's not comprehensive. It does not cover everything you need to know about Asterisk, for example, or Action/Trigger or Cron or several other things. It assumes you're bringing some knowledge to the table and that you're willing and able to search for information you don't have at hand. You must be prepared to solve small problems along the way.
+
+Once you've set up overdue notices, you should get the general idea of how to set up additional notices, like notices for holds available. The last section of this document contains some parting information on what you can expect to differ between those notices and overdue notices.
+
+Hardware
+--------
+Get a dedicated computer running Linux and make sure it meets any system requirements for Asterisk. 1 modernish CPU, 1 GB memory is plenty for most
+applications. More is always better.
+
+Make sure that the system running Evergreen (specifically, the utility box if you're dealing with a multi-server environment that has a utility box specifically for Action/Trigger stuff) has network connectivity to the box running Asterisk. At minimum it needs to be able to reach that Asterisk machine via TCP port 10080. Do not let the whole Internet talk to your Asterisk box via TCP port 10080. iptables is your friend.
+
+If you're using analog telephony (you're connecting to the Public Switched Telephone Network), you'll need an actual physical computer.
+
+For digital telephony, a virtual machine may suffice.
+
+NOTE: Ask the Asterisk community whether they generally recommend using virtual machines to host Asterisk.
+
+There are three main ways you can make phone calls with Asterisk.
+
+. *plain old phone lines* - If you have to connect to plain old analog single-channel phone lines, you can use a card from Digium like the
+AEX400 series to connect to up to four of those lines at once. You need an FXO
+module for each line you want to connect to the system (so the card itself is not enough). Plain old phone lines are the worst choice on this list. Usually with these, Asterisk thinks the conversation in outgoing calls has begun as soon as the other end starts *ringing.* This is really suboptimal.
+. *PRI interface or similar* - If your institution has this kind of service from a telephone company, or if they already have a PBX or some other such device that can offer channels for outbound dialing over a T1 interface, look into a card like the Digium TE121. Make very sure you understand what kind of phone network you're going to connect it to, and that your selected card can talk to it. This will often require coordination with a telephone company or PBX vendor to get working, but it provides a better platform that plain old phone lines.
+. *VoIP service with SIP or IAX protocols* - Digital telephony. Easiest to
+deal with by far, and also provides the richest set of information to Asterisk about whether calls complete properly, whether busy signals occur, etc. Requires no special hardware, just an internet connection. Your institution will purchase this service from some other company. Specifically, the institution should look for VoIP SIP providers (not library SIP, telephony SIP). SIP is pretty easy to deal with.
+
+If your project is at the stage where you can still recommend how your institution will achieve telephony connectivity , go with option 3 (voip service). You'll be glad you did.
+
+Install Asterisk, Perform Test Calls
+------------------------------------
+
+First things first
+~~~~~~~~~~~~~~~~~~
+The first thing you need is a server dedicated to running Asterisk and
+Festival. Asterisk is an open source PBX. Festival is for speech synthesis.
+
+We'll talk about setting up Festival in a later step. Strictly speaking, you might not need Festival if your institution doesn't
+need its notice message to contain truly dynamic parts (such as reading a
+list of overdue titles). Asterisk can read numbers aloud by itself, and if
+you need notices to choose between a finite set of possibilities of things to
+say, you can just make or acquire recordings of each of those things and
+choose between them with logic either in the Action/Trigger template or in
+the Asterisk dialplan (for example, reading the name of a library branch
+where a circulation is overdue). More on this later.
+
+As of this writing, you want any version of Asterisk within the 1.4, 1.6 or 1.8 series.
+
+Basic outbound call testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install asterisk. If you're using a Debian-based distro, try installing
+Asterisk with apt. If not, you may wind up installing it from source. That's
+ok. Installing Asterisk from source is easy; it follows the typical +./configure && make && make install+ pattern, and that's about it. For more information on installing Asterisk, just google it.
+
+NOTE: If asterisk-1.6.2.18-accountcode.patch from the Evergreen source applies cleanly to whatever version of Asterisk you wind up installing, you may want to use it. For reporting/auditing purposes, the Account field is a good place to shove data when using Asterisk call files and Call Detail Records, and that patch makes it possible to store more than a few bytes there. Other fields (like userdata) don't necessary make it to the Call Detail Record in the event of outbound calls not reaching their destination (like when they result in busy signals).
+
+Configure asterisk for full logging. When running asterisk, you should get matter in +/var/log/asterisk/full+ on a typically configured system.
+
+Be sure you also installed DAHDI if you're using analog hardware to place phone calls (there are even cases when you want to install it for digital calling; grep Asterisk documentation for "timing source").
+When in doubt, just install it. Maybe your package manager already did for you.
+
+If using analog telephony, get your hardware configured and make sure you can see the things that you're supposed to see with +/usr/sbin/dahdi_tool+ (typical install location, but look around if needed) and the command "dahdi show channels" in the Asterisk interactive console. I'm handwaving over the specifics here. There's a wealth of information available online about how to do this.
+
+If using digital telephony, preferably with the SIP protocol, get that configured in asterisk and make sure your SIP channel(s) is/are up. Again, more specifics on this are available online.
+
+By the way, if you're not comfortable already, now is the time to get comfortable with Asterisk and making changes to its configuration. I have not successfully used FreePBX or AsteriskHome or any of the friendly metapackages. In my experience, these just get in your way and make Asterisk behave differently than otherwise documented.
+
+Make sure asterisk is running.
+
+In your dialplan (+/etc/asterisk/extensions.conf+), add a context that looks like the following. If you're not comfortable yet with the meanings of "context," "extension," "module," and "dialplan" in Asterisk, go back and learn more about Asterisk before proceeding.
+
+-------------------------------------------------------
+[just-a-test]
+exten => 10,1,Verbose(entering the just-a-test context)
+exten => 10,n,Answer
+exten => 10,n,SayNumber(10)
+exten => 10,n,SayDigits(987654321)
+exten => 10,n,Playback(vm-goodbye)
+exten => 10,n,Hangup
+-------------------------------------------------------
+
+Reload your dialplan. You should be able to do this with the "dialplan reload"
+command in the asterisk interactive console.
+
+Make sure the pbx_spool asterisk module is running.
+
+Edit a file in your home directory on the Asterisk machine. Give it any name you like. Make its contents match the following.
+
+-------------------------------------------------------
+Channel: X
+Context: just-a-test
+Extension: 10
+Callerid: 7701234567
+MaxRetries: 1
+RetryTime: 60
+WaitTime: 30
+Archive: 1
+-------------------------------------------------------
+
+Choose a phone number where you can be reached for this test call, such as your desk phone number. Let's pretend that's 770-555-1212. Now replace the "X" in the first line with something like "SIP/mytrunk/7705551212" if you've configured SIP and named your trunk "mytrunk," or with something like "DAHDI/1/17705551212" if using analog hardware (the 1 between the slashes here means channel 1.)
+
+Exactly what to replace that X with will vary a lot depending on circumstances. If you're in a situation where you're not directly connected to the outside telephone network, but are rather behind some other PBX equipment or something, you may have to prepend a 9 to the number you wish to dial, or something like that. Whether or not to add a 1 before dialing the main phone number is also a matter of circumstance. Sometimes you'll even be able to dial 7 digit phone numbers by themselves!
+
+NOTE: I'm sorry I've obviously written the above from a North America-centric perspective; somebody else feel free to correct this.
+
+When you think you've got something substituted for X that might work, do the following as root:
+
+-------------------------------------------------------
+cp yourfile /tmp
+chown asterisk /tmp/yourfile
+mv /tmp/yourfile /var/spool/asterisk/outgoing
+-------------------------------------------------------
+
+You might think that three step operation looks silly, but it's important that you not copy your "call file" (that's what we're calling the file you just composed) directly into +/var/spool/asterisk/outgoing+. The copy operation may not be finished when Asterisk reads in the file to make a call. By using a move operation instead (atomic) you make sure Asterisk doesn't see the file until it's completely there.
+
+If you've got the right stuff, and I've glossed over a lot of detail above, so you may very well not get it on the first try, you should get a phone call at your desk, and you should hear a woman's voice count down from ten to one and say goodbye.
+
+When you get the call, check whether your caller ID actually shows "7701234567" or whatever you entered for that line in your call file. Not all phone service providers actually let you set the caller ID here! Your institution probably wants the outgoing caller ID on these notices to be set to some phone number where patrons should call in. Don't promise your institution that you can actually make that happen until you test it!
+
+Testing a Call with Festival
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you don't need Festival (because perhaps you don't need to for the outbound notices to contain arbitrary strings like lists of item titles), move on to the next section in this document. But it's not that hard, and it does come in handy, so I recommend you keep going here.
+
+Install festival. Packages exist for any reasonable distro.
+
+Follow the instructions at http://www.voip-info.org/wiki/view/Asterisk+festival+installation . Within that document, just follow method 1 ("the easiest way") for installing Festival for Asterisk usage.
+
+Edit the "just-a-test" context in your dialplan so that it now reads like this:
+
+-------------------------------------------------------
+[just-a-test]
+exten => 10,1,Verbose(entering the just-a-test context)
+exten => 10,n,Answer
+exten => 10,n,SayDigits(123)
+exten => 10,n,Festival(Testing testing one two three)
+exten => 10,n,Playback(vm-goodbye)
+exten => 10,n,Festival(Goodbye)
+exten => 10,n,Hangup
+-------------------------------------------------------
+
+Reload your dialplan, and follow the steps as in the previous test to respool your call file for another outbound call.
+
+When you answer this call, you should hear a nice lady's voice say "one two three," a less nice male-ish voice say "testing testing one two three," the nice lady say "goodbye", and the less nice male say "goodbye."
+
+When you hear this test, you have festival configured correctly.
+
+Deploy Perl scripts connecting Evergreen to Asterisk
+----------------------------------------------------
+You've got to set up two Perl scripts now. These two scripts are involved in getting call files from Evergreen to Asterisk. Evergreen basically generates a
+call file via an Action/Trigger template and then ships it off to the Asterisk machine. More on that later.
+
+For now, the important thing is that Evergreen will send call files to your Asterisk machine on TCP port 10080 via XML-RPC. One of these two Perl scripts I'm talking about has the job of listening for those deliveries.
+
+Find the +Open-ILS/src/asterisk/pbx-daemon+ directory in the tarball for whatever version of Evergreen you installed, or from a checkout of the master branch. From there, copy the two .pl files to +/usr/local/bin+ and the one .conf file to +/usr/local/etc+.
+
+Try to run the command +eg-pbx-mediator.pl -c /usr/local/etc/eg-pbx-daemon.conf+. It probably won't work the first time. Read whatever error messages you get, and use your distribution's package manager or CPAN to install any missing perl dependencies (like Config::General and RPC::XML). Rinse and repeat until the script runs without errors. Use sudo or su to run it as the user "nobody." Once eg-pbx-mediator.pl is running, background it and get it out of your sight.
+
+From the utility box, make sure you can telnet to your Asterisk box on port 10080. If you can't get a connection, there's a either a firewall in your way or some other network layer problem. Resolve that before continuing.
+
+Now try to run +eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf+. Follow the same process as above to install any missing dependencies or fix any errors. This script is not a daemon, so it should exit immediately (and silently) when it's configured correctly. We're going to want to run it via cronjob eventually, but we'll set that up in a later step.
+
+What does each script do, you ask? Basically eg-pbx-mediator.pl listens for call files from Evergreen and drops them off in +/var/tmp+. eg-pbx-allocator.pl will move a given number of call files from +/var/tmp+ into +/var/spool/asterisk/outgoing+. The reason there are two separate scripts doing this is so that you can schedule eg-pbx-allocator.pl to run (via cron) only during times when you want to be calling patrons (like during the day, and not on Sundays).
+
+Getting your call script together
+---------------------------------
+Now you need to determine what your notifications should say. There are not useful defaults for this in Evergreen yet.
+
+We know we can do overdue notices and hold available notices. There are other "hooks" (see your Action/Trigger vocabulary) off which we could build other event definitions. Chart your own course here and please share your results with the community!
+
+For an overdue notice, for example, you need to decide (or get the
+institution to decide) literally word for word what you want the message to
+say.
+
+Generic example:
+
+-------------------------------------------------------
+This is the Example Consortium calling on behalf of Example Branch 1 to inform
+you that you have <number> overdue item(s). The following titles are overdue:
+<titles of overdue items>. For more information, please call Example Branch 1
+at <branch's phone number>. Thank you.
+-------------------------------------------------------
+
+And then you need to create or obtain a similar script for hold available notices.
+
+The following two subsections cover how to write a very basic dialplan and how to record sound files for a custom script.
+
+Expanding your dialplan
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Now it's time to create more complete dialplans that reflect your call scripts.
+
+In +/etc/asterisk/extensions.conf+, add a new context like the following. This follows our example call script above, and assumes you installed and set up Festival.
+
+-------------------------------------------------------
+[overdue-notice]
+exten => 11,1,Verbose(started in eg-overdue-notice)
+exten => 11,n,Answer
+exten => 11,n,Festival(This is the)
+exten => 11,n,Festival(${root_ou_name})
+exten => 11,n,Festival(calling on behalf of the)
+exten => 11,n,Festival(${ou_name})
+exten => 11,n,Festival(to inform you that you have)
+exten => 11,n,SayNumber(${items})
+exten => 11,n,GotoIf($[0${items} > 1]?20:25) ; spaces important
+exten => 11,20,Festival(overdue items.) ; this is plural
+exten => 11,n,Goto(30)
+exten => 11,25,Festival(overdue item.) ; this is singular
+exten => 11,n,Goto(30)
+exten => 11,30,Festival(The following titles are overdue)
+exten => 11,n,Festival(${titles})
+exten => 11,n,Festival(For more information please call)
+exten => 11,n,Festival(${ou_name})
+exten => 11,n,Festival(at)
+exten => 11,n,SayDigits(${ou_phone})
+exten => 11,n,Festival(Thank you.)
+exten => 11,n,Hangup
+-------------------------------------------------------
+
+There are several things to bear in mind about the above dialplan. It's extremely simple in that it doesn't attempt answering machine detection and it doesn't offer the called party any way to repeat part of the message. If you're using plain-old-phone-lines (as opposed to a PRI card or digital telephony) this message will actually play to the ringback tone instead of waiting for a human to answer! Furthermore, it's going to read everything in a hard-to-understand robot voice.
+
+It will, however, serve its purpose in testing whether our call script will work.
+
+Compose a new call file like this:
+
+-------------------------------------------------------
+Channel: X
+Context: overdue-notice
+Extension: 11
+Callerid: 7701234567
+MaxRetries: 1
+RetryTime: 60
+WaitTime: 30
+Archive: 1
+Set: rout_ou_name=Example Consortium
+Set: ou_name=Example Branch 1
+Set: ou_phone=4045551212
+Set: items=2
+Set: titles=Harry Potter. The Da Vinci Code.
+-------------------------------------------------------
+
+where you substitute "SIP/blah/somenumber" or "DAHDI/N/somenumber" for X as in the earlier example in this document.
+
+Spool the file as per previous instructions. Does the message being read to you over the phone match the script you have? If so, great. Otherwise, do not continue until you get it right.
+
+Repeat this process to create a hold-available notice, assuming your institution wants one. You'll create a similar chunk of dialplan, but you'll just change the messages and logic to reflect your script for hold-available notices rather than your script for overdue notices.
+
+Recording Sounds
+~~~~~~~~~~~~~~~~
+Now to get rid of the robot voice. For all the static parts of your call script (represented in the dialplan by lines that call Festival() without using any variables for arguments such as +${items}+), you can ask your institution to have somebody record wave files saying these phrases. Or maybe by the time you read this document Evergreen will have some standard dialplans and matching sound files. Or you may have to do the voice work yourself.
+
+'Audacity' is a great open source application for recording and editing sound files. Avoid clipping and introducing noisy artifacts. How to record good audio is obviously outside the scope of this document, but anybody can do it. Export Microsoft-style wav files, at 44100hz/16-bit.
+
+Once you have your wave files of all the parts of the dialplan recorded, you'll need to turn them into GSM files for Asterisk.
+
+Use sox to convert your WAV files to GSM. sox is available on every serious Linux distro. For a single file, do this:
+
+-------------------------------------------------------
+sox infile.wav -r 8000 -c 1 outfile.gsm resample -ql
+-------------------------------------------------------
+
+Put the above command inside a for loop to handle all your WAVs at once. I leave that as an exercise for the reader.
+
+Make sure your can play the product by running:
+-------------------------------------------------------
+play outfile.gsm
+-------------------------------------------------------
+
+It'll sound relatively lo-fi, but as long as you can hear yourself, that'll do. It'll probably sound more natural through a phone handset than it does through your workstation's speakers.
+
+Ideally you will have given your GSM files names that easily map to the strings of text that you have spoken in each file. Place these files in +/var/lib/asterisk/sounds+ on the Asterisk server. Then replace all of the static Festival calls in your dialplans with lines that look like this:
+
+-------------------------------------------------------
+exten => 11,n,Playback(For-more-information-please-call)
+-------------------------------------------------------
+
+The above assumes that there is a file at +/var/lib/asterisk/sounds/For-more-information-please-call.gsm+.
+
+Reload your dialplan. Re-run the test from end of the section "expanding your dialplan." You should hear your own voice replacing the hard-to-understand robot voice for all but the dynamic parts of the message.
+
+Action/Trigger Event Definitions
+--------------------------------
+
+It's time to create Action/Trigger Event Definitions (rows in the action_trigger.event_definition table) for the notifications you want.
+
+Setting up the event definition itself
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There should be a stock example event definition linked to the the "checkout.due" hook. For your overdue notices, you can just adjust this *if* you're going to be setting up overdue notices for the entire system or consortia using the Evergreen instance.
+
+If, on the other hand, you're setting up telephone notifications just for a certain branch or system, go ahead and create a new event definition, and make extra sure that its owner field contains the ID of the highest org unit that you want to be involved in your notifications, and no higher.
+
+Make your event definition look like the following. Columns I haven't mentioned can be left on their default values.
+
+-------------------------------------------------------
+active | t
+owner | N -- where N is the top org unit where you want notices
+name | Overdue Telephone Notification For Blah Library System
+hook | checkout.due
+validator | CircIsOverdue
+reactor | ProcessTemplate -- sic! just while we're testing
+delay | 5 seconds
+delay_field | due_date
+group_field | usr
+template | test -- sic! just while we're testing
+granularity | Telephony
+-------------------------------------------------------
+
+The above isn't really enough to get the job done, but we're going to do this in baby steps.
+
+Now make sure you have rows in action_trigger.environment that point to your event_definition (i.e., they have the correct event_definition ID in the "event_def" column) with the following three values for "path".
+
+-------------------------------------------------------
+target_copy.call_number.record.simple_record
+usr.settings
+circ_lib
+-------------------------------------------------------
+
+Once that's done, here's a simple template. The more you want to change it, the more comfortable you'll need to be with Template Toolkit Syntax. Try setting the "template" column of your action_trigger.event_definition row to this:
+
+-------------------------------------------------------
+[%-
+
+# Get a usable phone number.
+phone = target.0.usr.day_phone | replace('[^0-9]', '');
+
+IF phone.length == 7;
+ chan = 'DAHDI/r1/' _ phone;
+ELSIF phone.length == 10;
+ chan = 'DAHDI/r1/1' _ phone;
+ELSE;
+ ";noop bad phone number: '" _ phone _ "'"; STOP;
+END;
+
+branchname = target.0.circ_lib.shortname | lower;
+branchphone = target.0.circ_lib.phone | replace('[^0-9]','');
+-%]
+Channel: [% chan %]
+Context: overdue-notice
+Extension: 11
+MaxRetries: 2
+RetryTime: 300
+WaitTime: 30
+Archive: 1
+Set: eg_user_id=[% target.0.usr.id %]
+Set: items=[% target.size %]
+Set: branchname=[% branchname %]
+Set: branchphone=[% branchphone %]
+Set: titlestring=[%
+ titles = [];
+ FOR circ IN target;
+ t = circ.target_copy.call_number.record.simple_record.title;
+ t = t | replace('[^a-zA-Z0-9]',' '); # commas and things break Festival
+ titles.push(t);
+ END;
+ titles.join(". ");
+%]
+
+[%#
+ # Make sure this template ends with some line feeds! You don't want the
+ # "Set: titlestring=blah" line to be the last thing in the output without
+ # a linefeed (this, combined with things that happen later, will lead to
+ # callfiles that Asterisk cannot parse).
+%]
+
+-------------------------------------------------------
+
+Around the middle, notice the lines where the template defines a variable "chan". Make sure that "chan" is getting set to something that will actually work for placing a call with your system. It may start with DAHDI or it may start with SIP, and the middle part will vary as well. It all depends on what you had to put in your test call files earlier in order to be able to place test calls.
+
+Enough about the template for now. Let's run some test events and see if we can generate a correct callfile from this template.
+
+Testing some events for call file generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On your institution's utility server, change to the opensrf user and issue the following command.
+
+NOTE: For a busy institution that might have lots of overdue circulations (> 1000) you should take care to do this at some point in the day that won't disrupt other important processes on the utility box. This could take a while (hours, potentially).
+
+-------------------------------------------------------
+/openils/bin/action_trigger_runner.pl --run-pending --process-hooks --granularity Telephony
+-------------------------------------------------------
+
+When that command finishes, you should have some rows in your *action_trigger.event* table where the "event_def" column matches the ID of the telephony event definition you just set up and the "state" column is "complete".
+
+If you have rows where "event_def" is right but the state is not "complete," investigate that as you would any action trigger problem. Otherwise your event rows will have numbers in the "template_output" column. Pick some of those values from the "template_output" column, and for each of those values select the row from the *action_trigger.event_output* table with the matching ID.
+
+The value of the "data" column of your event output rows should look like a callfile that matches the format of the callfiles you successfully tested in earlier sections of this document. If you're not getting something that looks like a callfile that should work, make adjustments until you do. Once you think you have something that might work, try pasting it into a text editor, substituting your own phone number for the one generated from the patron record, and spooling that as a callfile on the Asterisk system. In theory you should hear a complete overdue notice.
+
+Finishing touches
+-----------------
+
+Revalidation
+~~~~~~~~~~~~
+
+TODO: Explain how to use revalidator_uri in +eg-pbx-daemon.conf+ to revalidate events that have been waiting for the allocator for a while right before we actually attempt to spool their callfiles with Asterisk, so patrons don't get stale overdue notices and such.
+
+Patch AstCall.pm
+~~~~~~~~~~~~~~~~
+
+If you're using a version of Evergreen earlier than 2.1.0, take the following commit from the Evergreen git repository and apply it on your utility server: e2d50e9f062c.
+
+/openils/conf/opensrf.xml
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the utility server edit +/openils/conf/opensrf.xml+ so that the <telephony> section looks like this:
+
+-------------------------------------------------------
+<telephony>
+ <enabled>1</enabled> <!-- I think this setting isn't actually used -->
+ <driver>SIP</driver> <!-- Always make this SIP, no matter what. -->
+ <channels> <!-- This isn't used but must be here anyway. -->
+ <channel>1</channel>
+ <channel>2</channel>
+ </channels>
+ <host>A.B.C.D</host> <!-- for A.B.C.D, enter the IP of Asterisk box -->
+ <port>10080</port> <!-- default, little reason to change this -->
+ <user>evergreen</user> <!-- not actually used -->
+ <pw>evergreen</pw> <!-- not actually used -->
+</telephony>
+-------------------------------------------------------
+
+Yes, I realize most of that config is ridiculous, especially how it expects you to have "SIP" as the driver even when you're using analog hardware. The config was shaped by earlier designs for A/T-based telephony that have been superseded. We should fix this, but don't worry: it's your event definition template that really spells out DAHDI or SIP, anyway.
+
+Of course, somebody should clean up the config and the code that uses it to reflect what we really need, and then ideally update this document. Thanks in advance.
+
+Services to restart
+~~~~~~~~~~~~~~~~~~~
+Restart the open-ils.trigger and the opensrf.settings services on the utility box. If you don't usually restart specific services like that, restarting all the services on the utility box is fine.
+
+Make your event definition use the AstCall reactor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Remember the event definition you made for telephone notices a few steps ago? Change the value of its "reactor" column from 'ProcessTemplate' to 'AstCall'.
+
+Init scripts for the Asterisk box
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you installed Asterisk from source instead of from a distro package, look in the source tarball for sample init scripts. Choose the one appropriate for your distro, put it in place, run 'chkconfig' or 'update-rc.d' or whatever's appropriate for your distro, and make sure you can start and stop Asterisk with that init script now.
+
+For festival, I think on Debianesque distros you will have installed this from a package, but if you're on something Redhat-ish and you need an init script, the following will probably work.
+
+Festival:
+-------------------------------------------------------
+#!/bin/sh
+#
+# festival: Festival Text-to-Speech server
+#
+# chkconfig: - 26 89
+# description: Festival Text-to-Speech server
+#
+
+# Source function library.
+. /etc/rc.d/init.d/functions
+
+start()
+{
+ mkdir -p /var/log/festival
+ mkdir -p /var/run/festival
+ cd /var/run/festival
+ echo -n $"Starting festival: "
+ nohup festival_server -l /var/log/festival &
+ echo
+}
+
+stop()
+{
+ echo -n $"Shutting down festival: "
+ festival_server_control -l /var/log/festival exit
+ echo
+}
+
+# See how we were called.
+case "$1" in
+ start)
+ start
+ ;;
+ stop)
+ stop
+ ;;
+ restart|reload)
+ stop
+ start
+ ;;
+ status)
+ status festival_server
+ ;;
+ *)
+ echo $"Usage: $0 {start|stop|restart|reload}"
+ exit 1
+esac
+
+exit 0
+-------------------------------------------------------
+
+For eg-pbx-mediator.pl, use this init script. Actually you should change it to run the mediator as the 'nobody' user instead of as the 'root' user, but I haven't got around to that yet.
+
+-------------------------------------------------------
+#!/bin/sh
+#
+# eg-pbx-mediator: Daemon to listen for call files from Evergreen
+#
+# chkconfig: - 62 38
+# description: Daemon to listen for call files from Evergreen
+#
+
+PIDFILE=/var/run/eg-pbx-mediator.pid
+
+start()
+{
+ echo -n "Starting eg-pbx-daemon: "
+ /usr/local/bin/eg-pbx-mediator.pl -c /usr/local/etc/eg-pbx-daemon.conf &
+ echo
+ echo $! > $PIDFILE
+}
+
+stop()
+{
+ echo -n "Shutting down eg-pbx-daemon: "
+ [ -r $PIDFILE ] && kill `cat $PIDFILE `
+ echo
+}
+
+# See how we were called.
+case "$1" in
+ start)
+ start
+ ;;
+ stop)
+ stop
+ ;;
+ restart|reload)
+ stop
+ start
+ ;;
+ *)
+ echo $"Usage: $0 {start|stop|restart|reload}"
+ exit 1
+esac
+
+exit 0
+
+-------------------------------------------------------
+
+Cron job for eg-pbx-allocator.pl
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the asterisk machine, create a cron job (or more than one) for root to run the eg-pbx-allocator.pl script. The idea is to run this script every minute during the "call window", or the period of time during which your institution is okay with calls going out. Make sure you communicate with your institution and find out when this window is!
+
+Here's an example from root's crontab on Anytown Public Library's Asterisk box:
+
+-------------------------------------------------------
+# Call window for Anytown Public Lib: 930am - 630pm Mon-Sat
+# The three lines below here do this.
+* 10-17 * * 1-6 /usr/local/bin/eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf
+0-29 18 * * 1-6 /usr/local/bin/eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf
+30-59 9 * * 1-6 /usr/local/bin/eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf
+-------------------------------------------------------
+
+So you see how those three cron lines together run the allocator every minute within Anytown's 930am - 630pm Mon-Sat call window.
+
+Cron job for action_trigger_runner.pl
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the utility server, create a cronjob as opensrf to run action_trigger_runner.pl with the particular arguments we need for telephony notices. If you're just doing overdue notices, most (but not all) Evergreen systems calculate overdues at midnight, so you 'could' have this cronjob run just once per day, some time in the wee hours.
+
+On the other hand, if you're eventually going to run telephony notices for holds available, too, then you want to run action_trigger_runner.pl with our arguments more often. Run it at the same frequency as you run the general --run-pending call, but slightly offset. For example, if you have a general "Run all pending A/T events every half hour" cronjob that does things every hour at :00 and :30, then perhaps use this for your telephony --run-pending job:
+
+-------------------------------------------------------
+# Runs all pending telephony A/T events every half hour (offset by 10 min)
+10,40 * * * * . ~/.bashrc && /openils/bin/action_trigger_runner.pl --osrf-config /openils/conf/opensrf_core.xml --run-pending --process-hooks --granularity Telephony
+-------------------------------------------------------
+
+Holidays
+~~~~~~~~
+TODO: Write this section
+
+Rollover failed notices
+~~~~~~~~~~~~~~~~~~~~~~~
+TODO: Write this section
+
+Congratulations!
+~~~~~~~~~~~~~~~~
+
+Congratulations! In a perfect world, telephone overdue notices for your institution are now live. If you're not quite there, but you followed this document carefully, you should at least be close, and maybe with some clever troubleshooting you'll get there soon.
+
+What to do differently for hooks like hold.available
+----------------------------------------------------
+
+For your event definition where the hook is "hold.available", be sure you make the "validator" column "HoldIsAvailable".
+
+Also, hold.available is an "active hook" as opposed to a passive one (like checkout.due) in Action/Trigger parlance. I suppose the only thing that you really need to know about it is that events for hold.available, once you set up an event definition, will appear all throughout the day, unlike the events for checkout.due, which will typically appear all at once sometime shortly after midnight.
+
+This may have implications for load scheduling. That might mean changes to the cron job on the Asterisk machine that runs eg-pbx-allocator.pl, or changes to the queue_limit value in +/usr/local/etc/eg-pbx-daemon.conf+, or other things. Telephony is an adventure.
+
+The target for a hold.available hook is a hold, unlike a checkout.due hook for which the target is a circ, so for your event_definition's environment, notice change 'circ_lib' to 'pickup_lib'. Then within your event_definition's template, make the same substitution and any other reasonable changes in light of the fact that now target is an array of holds, whereas before it was an array of circs.
+
+Troubleshooting and support
+---------------------------
+
+Troubleshooting post-go-live
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Want to see what's your telephony system is doing? The best things you can do are these.
+
+TODO: Explain how info from Account in a callfile winds up in CSV, and why it's good and helpful.
+
+- Activate one of the cdr modules that come with Asterisk. Call Detail Records wind up in either a CSV file or a database table depending on which module you activate. You can even have the cdr_pgsql.so module put that database table in the same postgres database as Evergreen itself uses. A cdr database table will have one row per call made, with lots of information about what the phone number was and what happened with the call. This information will be less reliable if you're using analog hardware, but is better if you're using digital telephony (VoIP).
+- Check +/var/log/asterisk/full+. grep around in this file to learn how to find all kinds of good information.
+- Run the interactive Asterisk console. On the asterisk server, as root, run */usr/sbin/asterisk -rvvvvvvvvvv* . Watch things happen in real time.
+- Consult the Evergreen database to see what kinds of notices have been generated. The following is an example query to see if any telephone notices went out regarding Harry Potter (assuming you kept the titlestring part in your event definition template):
+-------------------------------------------------------
+SELECT atev.id
+FROM action_trigger.event_definition atevdef
+JOIN action_trigger.event atev ON (atev.event_def = atevdef.id)
+JOIN action_trigger.event_output ateo ON (ateo.id = atev.template_output)
+WHERE ateo.data ILIKE '%harry potter%';
+-------------------------------------------------------
+- Want to know what hold available events have been generated for a given user? Try a query like this:
+-------------------------------------------------------
+SELECT atev.id,atev.state,ateo.data
+FROM action_trigger.event atev
+JOIN action_trigger.event_definition atevdev ON (atevdef.id = atev.event_def)
+LEFT JOIN action_trigger.event_output ateo ON (ateo.id = atev.template_output)
+JOIN action.hold_request ahr ON (ahr.id = atev.target)
+WHERE atevdef.hook = 'hold.available' and ahr.usr = <yourusridhere>;
+-------------------------------------------------------
+
+Stopping and restarting notices
+-------------------------------
+
+Is the system going haywire, and you need to stop outbound notices until you can figure out what's going on? The following two steps are enough to stop notices in their tracks:
+
+. Comment out the cron jobs for *eg-pbx-allocator.pl* in root's crontab on the Asterisk machine.
+. +/etc/init.d/asterisk+ stop
+
+Restarting notices is basically the obvious opposite of the above two steps, BUT you may wish to clear out previously queued notices first (or you may not, this just depends on what you're trying to accomplish and why you stopped notices in the first place). For Evergreen telephony, there's a two-stage queuing system in play. Files first go to +/var/tmp+ and then to +/var/spool/asterisk/outgoing+ so look for call files there and delete some if appropriate.
+
+Clearing out queued notices
+---------------------------
+
+Sometimes something will have happened (perhaps Evergreen has been used in offline mode for a while) and the system will have generated a lot of pending notices for overdues and holds that aren't actually correct. Remember that overdue notices are produced typically just after midnight, and hold available notices are produced all the time. Fixing wrong overdues or wrong hold shelving does NOT automatically recall any generated notices, so if there's some big disruptive event that's happened, it may be wise to clear out pending notices. It's even better if you can do this before the call window opens for the day.
+
+To remove queued notices (this is irrevocable!), just do
+
++rm /var/tmp/EG*.call+
+
++rm /var/spool/asterisk/outgoing/*+
+
+You could move these files somewhere instead of deleting them if you think there's some chance you might not actually want to delete them all.
+++ /dev/null
-Setting up Telephone Notices with Evergreen
-===========================================
-
-[abstract]
-What is this document good for?
--------------------------------
-This is telephony based on Asterisk and Action/Trigger for Evergreen 2.2 and up.
-
-If you've never done this before, you should *really* read this document all the way through before you begin, so that you have some idea of what to expect and how much time to schedule for it.
-
-This document should lead you through getting overdue telephone notices set up for Evergreen. This document is long, but it's not comprehensive. It does not cover everything you need to know about Asterisk, for example, or Action/Trigger or Cron or several other things. It assumes you're bringing some knowledge to the table and that you're willing and able to search for information you don't have at hand. You must be prepared to solve small problems along the way.
-
-Once you've set up overdue notices, you should get the general idea of how to set up additional notices, like notices for holds available. The last section of this document contains some parting information on what you can expect to differ between those notices and overdue notices.
-
-Hardware
---------
-Get a dedicated computer running Linux and make sure it meets any system requirements for Asterisk. 1 modernish CPU, 1 GB memory is plenty for most
-applications. More is always better.
-
-Make sure that the system running Evergreen (specifically, the utility box if you're dealing with a multi-server environment that has a utility box specifically for Action/Trigger stuff) has network connectivity to the box running Asterisk. At minimum it needs to be able to reach that Asterisk machine via TCP port 10080. Do not let the whole Internet talk to your Asterisk box via TCP port 10080. iptables is your friend.
-
-If you're using analog telephony (you're connecting to the Public Switched Telephone Network), you'll need an actual physical computer.
-
-For digital telephony, a virtual machine may suffice.
-
-NOTE: Ask the Asterisk community whether they generally recommend using virtual machines to host Asterisk.
-
-There are three main ways you can make phone calls with Asterisk.
-
-. *plain old phone lines* - If you have to connect to plain old analog single-channel phone lines, you can use a card from Digium like the
-AEX400 series to connect to up to four of those lines at once. You need an FXO
-module for each line you want to connect to the system (so the card itself is not enough). Plain old phone lines are the worst choice on this list. Usually with these, Asterisk thinks the conversation in outgoing calls has begun as soon as the other end starts *ringing.* This is really suboptimal.
-. *PRI interface or similar* - If your institution has this kind of service from a telephone company, or if they already have a PBX or some other such device that can offer channels for outbound dialing over a T1 interface, look into a card like the Digium TE121. Make very sure you understand what kind of phone network you're going to connect it to, and that your selected card can talk to it. This will often require coordination with a telephone company or PBX vendor to get working, but it provides a better platform that plain old phone lines.
-. *VoIP service with SIP or IAX protocols* - Digital telephony. Easiest to
-deal with by far, and also provides the richest set of information to Asterisk about whether calls complete properly, whether busy signals occur, etc. Requires no special hardware, just an internet connection. Your institution will purchase this service from some other company. Specifically, the institution should look for VoIP SIP providers (not library SIP, telephony SIP). SIP is pretty easy to deal with.
-
-If your project is at the stage where you can still recommend how your institution will achieve telephony connectivity , go with option 3 (voip service). You'll be glad you did.
-
-Install Asterisk, Perform Test Calls
-------------------------------------
-
-First things first
-~~~~~~~~~~~~~~~~~~
-The first thing you need is a server dedicated to running Asterisk and
-Festival. Asterisk is an open source PBX. Festival is for speech synthesis.
-
-We'll talk about setting up Festival in a later step. Strictly speaking, you might not need Festival if your institution doesn't
-need its notice message to contain truly dynamic parts (such as reading a
-list of overdue titles). Asterisk can read numbers aloud by itself, and if
-you need notices to choose between a finite set of possibilities of things to
-say, you can just make or acquire recordings of each of those things and
-choose between them with logic either in the Action/Trigger template or in
-the Asterisk dialplan (for example, reading the name of a library branch
-where a circulation is overdue). More on this later.
-
-As of this writing, you want any version of Asterisk within the 1.4, 1.6 or 1.8 series.
-
-Basic outbound call testing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Install asterisk. If you're using a Debian-based distro, try installing
-Asterisk with apt. If not, you may wind up installing it from source. That's
-ok. Installing Asterisk from source is easy; it follows the typical +./configure && make && make install+ pattern, and that's about it. For more information on installing Asterisk, just google it.
-
-NOTE: If asterisk-1.6.2.18-accountcode.patch from the Evergreen source applies cleanly to whatever version of Asterisk you wind up installing, you may want to use it. For reporting/auditing purposes, the Account field is a good place to shove data when using Asterisk call files and Call Detail Records, and that patch makes it possible to store more than a few bytes there. Other fields (like userdata) don't necessary make it to the Call Detail Record in the event of outbound calls not reaching their destination (like when they result in busy signals).
-
-Configure asterisk for full logging. When running asterisk, you should get matter in +/var/log/asterisk/full+ on a typically configured system.
-
-Be sure you also installed DAHDI if you're using analog hardware to place phone calls (there are even cases when you want to install it for digital calling; grep Asterisk documentation for "timing source").
-When in doubt, just install it. Maybe your package manager already did for you.
-
-If using analog telephony, get your hardware configured and make sure you can see the things that you're supposed to see with +/usr/sbin/dahdi_tool+ (typical install location, but look around if needed) and the command "dahdi show channels" in the Asterisk interactive console. I'm handwaving over the specifics here. There's a wealth of information available online about how to do this.
-
-If using digital telephony, preferably with the SIP protocol, get that configured in asterisk and make sure your SIP channel(s) is/are up. Again, more specifics on this are available online.
-
-By the way, if you're not comfortable already, now is the time to get comfortable with Asterisk and making changes to its configuration. I have not successfully used FreePBX or AsteriskHome or any of the friendly metapackages. In my experience, these just get in your way and make Asterisk behave differently than otherwise documented.
-
-Make sure asterisk is running.
-
-In your dialplan (+/etc/asterisk/extensions.conf+), add a context that looks like the following. If you're not comfortable yet with the meanings of "context," "extension," "module," and "dialplan" in Asterisk, go back and learn more about Asterisk before proceeding.
-
--------------------------------------------------------
-[just-a-test]
-exten => 10,1,Verbose(entering the just-a-test context)
-exten => 10,n,Answer
-exten => 10,n,SayNumber(10)
-exten => 10,n,SayDigits(987654321)
-exten => 10,n,Playback(vm-goodbye)
-exten => 10,n,Hangup
--------------------------------------------------------
-
-Reload your dialplan. You should be able to do this with the "dialplan reload"
-command in the asterisk interactive console.
-
-Make sure the pbx_spool asterisk module is running.
-
-Edit a file in your home directory on the Asterisk machine. Give it any name you like. Make its contents match the following.
-
--------------------------------------------------------
-Channel: X
-Context: just-a-test
-Extension: 10
-Callerid: 7701234567
-MaxRetries: 1
-RetryTime: 60
-WaitTime: 30
-Archive: 1
--------------------------------------------------------
-
-Choose a phone number where you can be reached for this test call, such as your desk phone number. Let's pretend that's 770-555-1212. Now replace the "X" in the first line with something like "SIP/mytrunk/7705551212" if you've configured SIP and named your trunk "mytrunk," or with something like "DAHDI/1/17705551212" if using analog hardware (the 1 between the slashes here means channel 1.)
-
-Exactly what to replace that X with will vary a lot depending on circumstances. If you're in a situation where you're not directly connected to the outside telephone network, but are rather behind some other PBX equipment or something, you may have to prepend a 9 to the number you wish to dial, or something like that. Whether or not to add a 1 before dialing the main phone number is also a matter of circumstance. Sometimes you'll even be able to dial 7 digit phone numbers by themselves!
-
-NOTE: I'm sorry I've obviously written the above from a North America-centric perspective; somebody else feel free to correct this.
-
-When you think you've got something substituted for X that might work, do the following as root:
-
--------------------------------------------------------
-cp yourfile /tmp
-chown asterisk /tmp/yourfile
-mv /tmp/yourfile /var/spool/asterisk/outgoing
--------------------------------------------------------
-
-You might think that three step operation looks silly, but it's important that you not copy your "call file" (that's what we're calling the file you just composed) directly into +/var/spool/asterisk/outgoing+. The copy operation may not be finished when Asterisk reads in the file to make a call. By using a move operation instead (atomic) you make sure Asterisk doesn't see the file until it's completely there.
-
-If you've got the right stuff, and I've glossed over a lot of detail above, so you may very well not get it on the first try, you should get a phone call at your desk, and you should hear a woman's voice count down from ten to one and say goodbye.
-
-When you get the call, check whether your caller ID actually shows "7701234567" or whatever you entered for that line in your call file. Not all phone service providers actually let you set the caller ID here! Your institution probably wants the outgoing caller ID on these notices to be set to some phone number where patrons should call in. Don't promise your institution that you can actually make that happen until you test it!
-
-Testing a Call with Festival
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you don't need Festival (because perhaps you don't need to for the outbound notices to contain arbitrary strings like lists of item titles), move on to the next section in this document. But it's not that hard, and it does come in handy, so I recommend you keep going here.
-
-Install festival. Packages exist for any reasonable distro.
-
-Follow the instructions at http://www.voip-info.org/wiki/view/Asterisk+festival+installation . Within that document, just follow method 1 ("the easiest way") for installing Festival for Asterisk usage.
-
-Edit the "just-a-test" context in your dialplan so that it now reads like this:
-
--------------------------------------------------------
-[just-a-test]
-exten => 10,1,Verbose(entering the just-a-test context)
-exten => 10,n,Answer
-exten => 10,n,SayDigits(123)
-exten => 10,n,Festival(Testing testing one two three)
-exten => 10,n,Playback(vm-goodbye)
-exten => 10,n,Festival(Goodbye)
-exten => 10,n,Hangup
--------------------------------------------------------
-
-Reload your dialplan, and follow the steps as in the previous test to respool your call file for another outbound call.
-
-When you answer this call, you should hear a nice lady's voice say "one two three," a less nice male-ish voice say "testing testing one two three," the nice lady say "goodbye", and the less nice male say "goodbye."
-
-When you hear this test, you have festival configured correctly.
-
-Deploy Perl scripts connecting Evergreen to Asterisk
-----------------------------------------------------
-You've got to set up two Perl scripts now. These two scripts are involved in getting call files from Evergreen to Asterisk. Evergreen basically generates a
-call file via an Action/Trigger template and then ships it off to the Asterisk machine. More on that later.
-
-For now, the important thing is that Evergreen will send call files to your Asterisk machine on TCP port 10080 via XML-RPC. One of these two Perl scripts I'm talking about has the job of listening for those deliveries.
-
-Find the +Open-ILS/src/asterisk/pbx-daemon+ directory in the tarball for whatever version of Evergreen you installed, or from a checkout of the master branch. From there, copy the two .pl files to +/usr/local/bin+ and the one .conf file to +/usr/local/etc+.
-
-Try to run the command +eg-pbx-mediator.pl -c /usr/local/etc/eg-pbx-daemon.conf+. It probably won't work the first time. Read whatever error messages you get, and use your distribution's package manager or CPAN to install any missing perl dependencies (like Config::General and RPC::XML). Rinse and repeat until the script runs without errors. Use sudo or su to run it as the user "nobody." Once eg-pbx-mediator.pl is running, background it and get it out of your sight.
-
-From the utility box, make sure you can telnet to your Asterisk box on port 10080. If you can't get a connection, there's a either a firewall in your way or some other network layer problem. Resolve that before continuing.
-
-Now try to run +eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf+. Follow the same process as above to install any missing dependencies or fix any errors. This script is not a daemon, so it should exit immediately (and silently) when it's configured correctly. We're going to want to run it via cronjob eventually, but we'll set that up in a later step.
-
-What does each script do, you ask? Basically eg-pbx-mediator.pl listens for call files from Evergreen and drops them off in +/var/tmp+. eg-pbx-allocator.pl will move a given number of call files from +/var/tmp+ into +/var/spool/asterisk/outgoing+. The reason there are two separate scripts doing this is so that you can schedule eg-pbx-allocator.pl to run (via cron) only during times when you want to be calling patrons (like during the day, and not on Sundays).
-
-Getting your call script together
----------------------------------
-Now you need to determine what your notifications should say. There are not useful defaults for this in Evergreen yet.
-
-We know we can do overdue notices and hold available notices. There are other "hooks" (see your Action/Trigger vocabulary) off which we could build other event definitions. Chart your own course here and please share your results with the community!
-
-For an overdue notice, for example, you need to decide (or get the
-institution to decide) literally word for word what you want the message to
-say.
-
-Generic example:
-
--------------------------------------------------------
-This is the Example Consortium calling on behalf of Example Branch 1 to inform
-you that you have <number> overdue item(s). The following titles are overdue:
-<titles of overdue items>. For more information, please call Example Branch 1
-at <branch's phone number>. Thank you.
--------------------------------------------------------
-
-And then you need to create or obtain a similar script for hold available notices.
-
-The following two subsections cover how to write a very basic dialplan and how to record sound files for a custom script.
-
-Expanding your dialplan
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Now it's time to create more complete dialplans that reflect your call scripts.
-
-In +/etc/asterisk/extensions.conf+, add a new context like the following. This follows our example call script above, and assumes you installed and set up Festival.
-
--------------------------------------------------------
-[overdue-notice]
-exten => 11,1,Verbose(started in eg-overdue-notice)
-exten => 11,n,Answer
-exten => 11,n,Festival(This is the)
-exten => 11,n,Festival(${root_ou_name})
-exten => 11,n,Festival(calling on behalf of the)
-exten => 11,n,Festival(${ou_name})
-exten => 11,n,Festival(to inform you that you have)
-exten => 11,n,SayNumber(${items})
-exten => 11,n,GotoIf($[0${items} > 1]?20:25) ; spaces important
-exten => 11,20,Festival(overdue items.) ; this is plural
-exten => 11,n,Goto(30)
-exten => 11,25,Festival(overdue item.) ; this is singular
-exten => 11,n,Goto(30)
-exten => 11,30,Festival(The following titles are overdue)
-exten => 11,n,Festival(${titles})
-exten => 11,n,Festival(For more information please call)
-exten => 11,n,Festival(${ou_name})
-exten => 11,n,Festival(at)
-exten => 11,n,SayDigits(${ou_phone})
-exten => 11,n,Festival(Thank you.)
-exten => 11,n,Hangup
--------------------------------------------------------
-
-There are several things to bear in mind about the above dialplan. It's extremely simple in that it doesn't attempt answering machine detection and it doesn't offer the called party any way to repeat part of the message. If you're using plain-old-phone-lines (as opposed to a PRI card or digital telephony) this message will actually play to the ringback tone instead of waiting for a human to answer! Furthermore, it's going to read everything in a hard-to-understand robot voice.
-
-It will, however, serve its purpose in testing whether our call script will work.
-
-Compose a new call file like this:
-
--------------------------------------------------------
-Channel: X
-Context: overdue-notice
-Extension: 11
-Callerid: 7701234567
-MaxRetries: 1
-RetryTime: 60
-WaitTime: 30
-Archive: 1
-Set: rout_ou_name=Example Consortium
-Set: ou_name=Example Branch 1
-Set: ou_phone=4045551212
-Set: items=2
-Set: titles=Harry Potter. The Da Vinci Code.
--------------------------------------------------------
-
-where you substitute "SIP/blah/somenumber" or "DAHDI/N/somenumber" for X as in the earlier example in this document.
-
-Spool the file as per previous instructions. Does the message being read to you over the phone match the script you have? If so, great. Otherwise, do not continue until you get it right.
-
-Repeat this process to create a hold-available notice, assuming your institution wants one. You'll create a similar chunk of dialplan, but you'll just change the messages and logic to reflect your script for hold-available notices rather than your script for overdue notices.
-
-Recording Sounds
-~~~~~~~~~~~~~~~~
-Now to get rid of the robot voice. For all the static parts of your call script (represented in the dialplan by lines that call Festival() without using any variables for arguments such as +${items}+), you can ask your institution to have somebody record wave files saying these phrases. Or maybe by the time you read this document Evergreen will have some standard dialplans and matching sound files. Or you may have to do the voice work yourself.
-
-'Audacity' is a great open source application for recording and editing sound files. Avoid clipping and introducing noisy artifacts. How to record good audio is obviously outside the scope of this document, but anybody can do it. Export Microsoft-style wav files, at 44100hz/16-bit.
-
-Once you have your wave files of all the parts of the dialplan recorded, you'll need to turn them into GSM files for Asterisk.
-
-Use sox to convert your WAV files to GSM. sox is available on every serious Linux distro. For a single file, do this:
-
--------------------------------------------------------
-sox infile.wav -r 8000 -c 1 outfile.gsm resample -ql
--------------------------------------------------------
-
-Put the above command inside a for loop to handle all your WAVs at once. I leave that as an exercise for the reader.
-
-Make sure your can play the product by running:
--------------------------------------------------------
-play outfile.gsm
--------------------------------------------------------
-
-It'll sound relatively lo-fi, but as long as you can hear yourself, that'll do. It'll probably sound more natural through a phone handset than it does through your workstation's speakers.
-
-Ideally you will have given your GSM files names that easily map to the strings of text that you have spoken in each file. Place these files in +/var/lib/asterisk/sounds+ on the Asterisk server. Then replace all of the static Festival calls in your dialplans with lines that look like this:
-
--------------------------------------------------------
-exten => 11,n,Playback(For-more-information-please-call)
--------------------------------------------------------
-
-The above assumes that there is a file at +/var/lib/asterisk/sounds/For-more-information-please-call.gsm+.
-
-Reload your dialplan. Re-run the test from end of the section "expanding your dialplan." You should hear your own voice replacing the hard-to-understand robot voice for all but the dynamic parts of the message.
-
-Action/Trigger Event Definitions
---------------------------------
-
-It's time to create Action/Trigger Event Definitions (rows in the action_trigger.event_definition table) for the notifications you want.
-
-Setting up the event definition itself
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There should be a stock example event definition linked to the the "checkout.due" hook. For your overdue notices, you can just adjust this *if* you're going to be setting up overdue notices for the entire system or consortia using the Evergreen instance.
-
-If, on the other hand, you're setting up telephone notifications just for a certain branch or system, go ahead and create a new event definition, and make extra sure that its owner field contains the ID of the highest org unit that you want to be involved in your notifications, and no higher.
-
-Make your event definition look like the following. Columns I haven't mentioned can be left on their default values.
-
--------------------------------------------------------
-active | t
-owner | N -- where N is the top org unit where you want notices
-name | Overdue Telephone Notification For Blah Library System
-hook | checkout.due
-validator | CircIsOverdue
-reactor | ProcessTemplate -- sic! just while we're testing
-delay | 5 seconds
-delay_field | due_date
-group_field | usr
-template | test -- sic! just while we're testing
-granularity | Telephony
--------------------------------------------------------
-
-The above isn't really enough to get the job done, but we're going to do this in baby steps.
-
-Now make sure you have rows in action_trigger.environment that point to your event_definition (i.e., they have the correct event_definition ID in the "event_def" column) with the following three values for "path".
-
--------------------------------------------------------
-target_copy.call_number.record.simple_record
-usr.settings
-circ_lib
--------------------------------------------------------
-
-Once that's done, here's a simple template. The more you want to change it, the more comfortable you'll need to be with Template Toolkit Syntax. Try setting the "template" column of your action_trigger.event_definition row to this:
-
--------------------------------------------------------
-[%-
-
-# Get a usable phone number.
-phone = target.0.usr.day_phone | replace('[^0-9]', '');
-
-IF phone.length == 7;
- chan = 'DAHDI/r1/' _ phone;
-ELSIF phone.length == 10;
- chan = 'DAHDI/r1/1' _ phone;
-ELSE;
- ";noop bad phone number: '" _ phone _ "'"; STOP;
-END;
-
-branchname = target.0.circ_lib.shortname | lower;
-branchphone = target.0.circ_lib.phone | replace('[^0-9]','');
--%]
-Channel: [% chan %]
-Context: overdue-notice
-Extension: 11
-MaxRetries: 2
-RetryTime: 300
-WaitTime: 30
-Archive: 1
-Set: eg_user_id=[% target.0.usr.id %]
-Set: items=[% target.size %]
-Set: branchname=[% branchname %]
-Set: branchphone=[% branchphone %]
-Set: titlestring=[%
- titles = [];
- FOR circ IN target;
- t = circ.target_copy.call_number.record.simple_record.title;
- t = t | replace('[^a-zA-Z0-9]',' '); # commas and things break Festival
- titles.push(t);
- END;
- titles.join(". ");
-%]
-
-[%#
- # Make sure this template ends with some line feeds! You don't want the
- # "Set: titlestring=blah" line to be the last thing in the output without
- # a linefeed (this, combined with things that happen later, will lead to
- # callfiles that Asterisk cannot parse).
-%]
-
--------------------------------------------------------
-
-Around the middle, notice the lines where the template defines a variable "chan". Make sure that "chan" is getting set to something that will actually work for placing a call with your system. It may start with DAHDI or it may start with SIP, and the middle part will vary as well. It all depends on what you had to put in your test call files earlier in order to be able to place test calls.
-
-Enough about the template for now. Let's run some test events and see if we can generate a correct callfile from this template.
-
-Testing some events for call file generation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On your institution's utility server, change to the opensrf user and issue the following command.
-
-NOTE: For a busy institution that might have lots of overdue circulations (> 1000) you should take care to do this at some point in the day that won't disrupt other important processes on the utility box. This could take a while (hours, potentially).
-
--------------------------------------------------------
-/openils/bin/action_trigger_runner.pl --run-pending --process-hooks --granularity Telephony
--------------------------------------------------------
-
-When that command finishes, you should have some rows in your *action_trigger.event* table where the "event_def" column matches the ID of the telephony event definition you just set up and the "state" column is "complete".
-
-If you have rows where "event_def" is right but the state is not "complete," investigate that as you would any action trigger problem. Otherwise your event rows will have numbers in the "template_output" column. Pick some of those values from the "template_output" column, and for each of those values select the row from the *action_trigger.event_output* table with the matching ID.
-
-The value of the "data" column of your event output rows should look like a callfile that matches the format of the callfiles you successfully tested in earlier sections of this document. If you're not getting something that looks like a callfile that should work, make adjustments until you do. Once you think you have something that might work, try pasting it into a text editor, substituting your own phone number for the one generated from the patron record, and spooling that as a callfile on the Asterisk system. In theory you should hear a complete overdue notice.
-
-Finishing touches
------------------
-
-Revalidation
-~~~~~~~~~~~~
-
-TODO: Explain how to use revalidator_uri in +eg-pbx-daemon.conf+ to revalidate events that have been waiting for the allocator for a while right before we actually attempt to spool their callfiles with Asterisk, so patrons don't get stale overdue notices and such.
-
-Patch AstCall.pm
-~~~~~~~~~~~~~~~~
-
-If you're using a version of Evergreen earlier than 2.1.0, take the following commit from the Evergreen git repository and apply it on your utility server: e2d50e9f062c.
-
-/openils/conf/opensrf.xml
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On the utility server edit +/openils/conf/opensrf.xml+ so that the <telephony> section looks like this:
-
--------------------------------------------------------
-<telephony>
- <enabled>1</enabled> <!-- I think this setting isn't actually used -->
- <driver>SIP</driver> <!-- Always make this SIP, no matter what. -->
- <channels> <!-- This isn't used but must be here anyway. -->
- <channel>1</channel>
- <channel>2</channel>
- </channels>
- <host>A.B.C.D</host> <!-- for A.B.C.D, enter the IP of Asterisk box -->
- <port>10080</port> <!-- default, little reason to change this -->
- <user>evergreen</user> <!-- not actually used -->
- <pw>evergreen</pw> <!-- not actually used -->
-</telephony>
--------------------------------------------------------
-
-Yes, I realize most of that config is ridiculous, especially how it expects you to have "SIP" as the driver even when you're using analog hardware. The config was shaped by earlier designs for A/T-based telephony that have been superseded. We should fix this, but don't worry: it's your event definition template that really spells out DAHDI or SIP, anyway.
-
-Of course, somebody should clean up the config and the code that uses it to reflect what we really need, and then ideally update this document. Thanks in advance.
-
-Services to restart
-~~~~~~~~~~~~~~~~~~~
-Restart the open-ils.trigger and the opensrf.settings services on the utility box. If you don't usually restart specific services like that, restarting all the services on the utility box is fine.
-
-Make your event definition use the AstCall reactor
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Remember the event definition you made for telephone notices a few steps ago? Change the value of its "reactor" column from 'ProcessTemplate' to 'AstCall'.
-
-Init scripts for the Asterisk box
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you installed Asterisk from source instead of from a distro package, look in the source tarball for sample init scripts. Choose the one appropriate for your distro, put it in place, run 'chkconfig' or 'update-rc.d' or whatever's appropriate for your distro, and make sure you can start and stop Asterisk with that init script now.
-
-For festival, I think on Debianesque distros you will have installed this from a package, but if you're on something Redhat-ish and you need an init script, the following will probably work.
-
-Festival:
--------------------------------------------------------
-#!/bin/sh
-#
-# festival: Festival Text-to-Speech server
-#
-# chkconfig: - 26 89
-# description: Festival Text-to-Speech server
-#
-
-# Source function library.
-. /etc/rc.d/init.d/functions
-
-start()
-{
- mkdir -p /var/log/festival
- mkdir -p /var/run/festival
- cd /var/run/festival
- echo -n $"Starting festival: "
- nohup festival_server -l /var/log/festival &
- echo
-}
-
-stop()
-{
- echo -n $"Shutting down festival: "
- festival_server_control -l /var/log/festival exit
- echo
-}
-
-# See how we were called.
-case "$1" in
- start)
- start
- ;;
- stop)
- stop
- ;;
- restart|reload)
- stop
- start
- ;;
- status)
- status festival_server
- ;;
- *)
- echo $"Usage: $0 {start|stop|restart|reload}"
- exit 1
-esac
-
-exit 0
--------------------------------------------------------
-
-For eg-pbx-mediator.pl, use this init script. Actually you should change it to run the mediator as the 'nobody' user instead of as the 'root' user, but I haven't got around to that yet.
-
--------------------------------------------------------
-#!/bin/sh
-#
-# eg-pbx-mediator: Daemon to listen for call files from Evergreen
-#
-# chkconfig: - 62 38
-# description: Daemon to listen for call files from Evergreen
-#
-
-PIDFILE=/var/run/eg-pbx-mediator.pid
-
-start()
-{
- echo -n "Starting eg-pbx-daemon: "
- /usr/local/bin/eg-pbx-mediator.pl -c /usr/local/etc/eg-pbx-daemon.conf &
- echo
- echo $! > $PIDFILE
-}
-
-stop()
-{
- echo -n "Shutting down eg-pbx-daemon: "
- [ -r $PIDFILE ] && kill `cat $PIDFILE `
- echo
-}
-
-# See how we were called.
-case "$1" in
- start)
- start
- ;;
- stop)
- stop
- ;;
- restart|reload)
- stop
- start
- ;;
- *)
- echo $"Usage: $0 {start|stop|restart|reload}"
- exit 1
-esac
-
-exit 0
-
--------------------------------------------------------
-
-Cron job for eg-pbx-allocator.pl
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On the asterisk machine, create a cron job (or more than one) for root to run the eg-pbx-allocator.pl script. The idea is to run this script every minute during the "call window", or the period of time during which your institution is okay with calls going out. Make sure you communicate with your institution and find out when this window is!
-
-Here's an example from root's crontab on Anytown Public Library's Asterisk box:
-
--------------------------------------------------------
-# Call window for Anytown Public Lib: 930am - 630pm Mon-Sat
-# The three lines below here do this.
-* 10-17 * * 1-6 /usr/local/bin/eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf
-0-29 18 * * 1-6 /usr/local/bin/eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf
-30-59 9 * * 1-6 /usr/local/bin/eg-pbx-allocator.pl -c /usr/local/etc/eg-pbx-daemon.conf
--------------------------------------------------------
-
-So you see how those three cron lines together run the allocator every minute within Anytown's 930am - 630pm Mon-Sat call window.
-
-Cron job for action_trigger_runner.pl
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On the utility server, create a cronjob as opensrf to run action_trigger_runner.pl with the particular arguments we need for telephony notices. If you're just doing overdue notices, most (but not all) Evergreen systems calculate overdues at midnight, so you 'could' have this cronjob run just once per day, some time in the wee hours.
-
-On the other hand, if you're eventually going to run telephony notices for holds available, too, then you want to run action_trigger_runner.pl with our arguments more often. Run it at the same frequency as you run the general --run-pending call, but slightly offset. For example, if you have a general "Run all pending A/T events every half hour" cronjob that does things every hour at :00 and :30, then perhaps use this for your telephony --run-pending job:
-
--------------------------------------------------------
-# Runs all pending telephony A/T events every half hour (offset by 10 min)
-10,40 * * * * . ~/.bashrc && /openils/bin/action_trigger_runner.pl --osrf-config /openils/conf/opensrf_core.xml --run-pending --process-hooks --granularity Telephony
--------------------------------------------------------
-
-Holidays
-~~~~~~~~
-TODO: Write this section
-
-Rollover failed notices
-~~~~~~~~~~~~~~~~~~~~~~~
-TODO: Write this section
-
-Congratulations!
-~~~~~~~~~~~~~~~~
-
-Congratulations! In a perfect world, telephone overdue notices for your institution are now live. If you're not quite there, but you followed this document carefully, you should at least be close, and maybe with some clever troubleshooting you'll get there soon.
-
-What to do differently for hooks like hold.available
-----------------------------------------------------
-
-For your event definition where the hook is "hold.available", be sure you make the "validator" column "HoldIsAvailable".
-
-Also, hold.available is an "active hook" as opposed to a passive one (like checkout.due) in Action/Trigger parlance. I suppose the only thing that you really need to know about it is that events for hold.available, once you set up an event definition, will appear all throughout the day, unlike the events for checkout.due, which will typically appear all at once sometime shortly after midnight.
-
-This may have implications for load scheduling. That might mean changes to the cron job on the Asterisk machine that runs eg-pbx-allocator.pl, or changes to the queue_limit value in +/usr/local/etc/eg-pbx-daemon.conf+, or other things. Telephony is an adventure.
-
-The target for a hold.available hook is a hold, unlike a checkout.due hook for which the target is a circ, so for your event_definition's environment, notice change 'circ_lib' to 'pickup_lib'. Then within your event_definition's template, make the same substitution and any other reasonable changes in light of the fact that now target is an array of holds, whereas before it was an array of circs.
-
-Troubleshooting and support
----------------------------
-
-Troubleshooting post-go-live
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Want to see what's your telephony system is doing? The best things you can do are these.
-
-TODO: Explain how info from Account in a callfile winds up in CSV, and why it's good and helpful.
-
-- Activate one of the cdr modules that come with Asterisk. Call Detail Records wind up in either a CSV file or a database table depending on which module you activate. You can even have the cdr_pgsql.so module put that database table in the same postgres database as Evergreen itself uses. A cdr database table will have one row per call made, with lots of information about what the phone number was and what happened with the call. This information will be less reliable if you're using analog hardware, but is better if you're using digital telephony (VoIP).
-- Check +/var/log/asterisk/full+. grep around in this file to learn how to find all kinds of good information.
-- Run the interactive Asterisk console. On the asterisk server, as root, run */usr/sbin/asterisk -rvvvvvvvvvv* . Watch things happen in real time.
-- Consult the Evergreen database to see what kinds of notices have been generated. The following is an example query to see if any telephone notices went out regarding Harry Potter (assuming you kept the titlestring part in your event definition template):
--------------------------------------------------------
-SELECT atev.id
-FROM action_trigger.event_definition atevdef
-JOIN action_trigger.event atev ON (atev.event_def = atevdef.id)
-JOIN action_trigger.event_output ateo ON (ateo.id = atev.template_output)
-WHERE ateo.data ILIKE '%harry potter%';
--------------------------------------------------------
-- Want to know what hold available events have been generated for a given user? Try a query like this:
--------------------------------------------------------
-SELECT atev.id,atev.state,ateo.data
-FROM action_trigger.event atev
-JOIN action_trigger.event_definition atevdev ON (atevdef.id = atev.event_def)
-LEFT JOIN action_trigger.event_output ateo ON (ateo.id = atev.template_output)
-JOIN action.hold_request ahr ON (ahr.id = atev.target)
-WHERE atevdef.hook = 'hold.available' and ahr.usr = <yourusridhere>;
--------------------------------------------------------
-
-Stopping and restarting notices
--------------------------------
-
-Is the system going haywire, and you need to stop outbound notices until you can figure out what's going on? The following two steps are enough to stop notices in their tracks:
-
-. Comment out the cron jobs for *eg-pbx-allocator.pl* in root's crontab on the Asterisk machine.
-. +/etc/init.d/asterisk+ stop
-
-Restarting notices is basically the obvious opposite of the above two steps, BUT you may wish to clear out previously queued notices first (or you may not, this just depends on what you're trying to accomplish and why you stopped notices in the first place). For Evergreen telephony, there's a two-stage queuing system in play. Files first go to +/var/tmp+ and then to +/var/spool/asterisk/outgoing+ so look for call files there and delete some if appropriate.
-
-Clearing out queued notices
----------------------------
-
-Sometimes something will have happened (perhaps Evergreen has been used in offline mode for a while) and the system will have generated a lot of pending notices for overdues and holds that aren't actually correct. Remember that overdue notices are produced typically just after midnight, and hold available notices are produced all the time. Fixing wrong overdues or wrong hold shelving does NOT automatically recall any generated notices, so if there's some big disruptive event that's happened, it may be wise to clear out pending notices. It's even better if you can do this before the call window opens for the day.
-
-To remove queued notices (this is irrevocable!), just do
-
-+rm /var/tmp/EG*.call+
-
-+rm /var/spool/asterisk/outgoing/*+
-
-You could move these files somewhere instead of deleting them if you think there's some chance you might not actually want to delete them all.
--- /dev/null
+Display alternate graphic (880) fields
+======================================
+
+By default, Evergreen displays alternate graphic fields, if any, for
+contributors (1xx / 7xx), titles (245), edition statements (250), imprints
+(260), notes (5xx), subjects (6xx), and series (4xx / 8xx) in search results and record details
+per the Library of Congress MARC21 specifications:
+
+* http://www.loc.gov/marc/bibliographic/bd880.html
+* http://www.loc.gov/marc/bibliographic/ecbdcntf.html
+* http://www.loc.gov/marc/bibliographic/ecbdmulti.html (Model A)
+
+Default display
+---------------
+In general, alternate graphic fields display below the corresponding
+primary field. One exception is the attribution summary on the record details
+page, in which the alternate graphic field contents display between the
+primary field content and the attribution statement. To support CSS
+customizations, HTML elements for the graphic fields have the class attribute
+value `graphic880`.
+
+Implementation details
+----------------------
+The template file `parts/misc_util.tt2` defines two macros for retrieving
+linked 880 fields:
+
+* `get_graphic_880s`: given a _target_field_ scalar value representing a MARC
+ field tag, populate the _graphic_880s_ list with hashes containing the
+ target field tag and any graphic fields linked to that particular tag, with
+ the values for each being a simple concatenation of all subfields that are
+ not control subfields (per
+ http://www.loc.gov/marc/bibliographic/ecbdcntf.html). The structure of the
+ `graphic_880s` list is as follows:
++
+------------------------------------------------------------------------
+[
+ {
+ "primary": {"occur": 01, "value": "foo foo"},
+ "graphic": [
+ {
+ "occur": 01,
+ "value": "bar bar",
+ "orient": "rtl",
+ "script": "CJK"
+ }
+ ]
+ }
+]
+------------------------------------------------------------------------
+* `get_linked_880s` macro iterates over the content of the `linked_fields`
+ list, in which each element of the list to be a scalar representing the $6
+ control subfield link info. The macro populates the `graphics` list with a
+ set of graphic field hashes with the following structure:
++
+------------------------------------------------------------------------
+[
+ {
+ "occur": 01,
+ "value": "bar bar",
+ "orient": "rtl",
+ "script": "CJK"
+ }
+]
+------------------------------------------------------------------------
+
+`misc_util.tt2` preserves legacy attribute lists to enable previous TPAC
+customizations to continue to function normally.
+++ /dev/null
-Display alternate graphic (880) fields
-======================================
-
-By default, Evergreen displays alternate graphic fields, if any, for
-contributors (1xx / 7xx), titles (245), edition statements (250), imprints
-(260), notes (5xx), subjects (6xx), and series (4xx / 8xx) in search results and record details
-per the Library of Congress MARC21 specifications:
-
-* http://www.loc.gov/marc/bibliographic/bd880.html
-* http://www.loc.gov/marc/bibliographic/ecbdcntf.html
-* http://www.loc.gov/marc/bibliographic/ecbdmulti.html (Model A)
-
-Default display
----------------
-In general, alternate graphic fields display below the corresponding
-primary field. One exception is the attribution summary on the record details
-page, in which the alternate graphic field contents display between the
-primary field content and the attribution statement. To support CSS
-customizations, HTML elements for the graphic fields have the class attribute
-value `graphic880`.
-
-Implementation details
-----------------------
-The template file `parts/misc_util.tt2` defines two macros for retrieving
-linked 880 fields:
-
-* `get_graphic_880s`: given a _target_field_ scalar value representing a MARC
- field tag, populate the _graphic_880s_ list with hashes containing the
- target field tag and any graphic fields linked to that particular tag, with
- the values for each being a simple concatenation of all subfields that are
- not control subfields (per
- http://www.loc.gov/marc/bibliographic/ecbdcntf.html). The structure of the
- `graphic_880s` list is as follows:
-+
-------------------------------------------------------------------------
-[
- {
- "primary": {"occur": 01, "value": "foo foo"},
- "graphic": [
- {
- "occur": 01,
- "value": "bar bar",
- "orient": "rtl",
- "script": "CJK"
- }
- ]
- }
-]
-------------------------------------------------------------------------
-* `get_linked_880s` macro iterates over the content of the `linked_fields`
- list, in which each element of the list to be a scalar representing the $6
- control subfield link info. The macro populates the `graphics` list with a
- set of graphic field hashes with the following structure:
-+
-------------------------------------------------------------------------
-[
- {
- "occur": 01,
- "value": "bar bar",
- "orient": "rtl",
- "script": "CJK"
- }
-]
-------------------------------------------------------------------------
-
-`misc_util.tt2` preserves legacy attribute lists to enable previous TPAC
-customizations to continue to function normally.
--- /dev/null
+New Feature: Generic CSV Notification Generator/Receiver
+========================================================
+
+New Action/Trigger template and sample event definitions for creating a CSV
+export file for various patron actions, primarily for the purpose of creating
+patron notices via external notification mechanisms.
+
+The reference implementation for this development is the TalkingTech iTiva
+product, which consumes CSV files for generating phone/text notifications and
+produces CSV results files for informing the ILS of notification statuses.
+The template and send/receive scripts, however, should be generic enough to
+create CSV for any type of 3rd-party notification product.
+
+Action/Trigger Event Definition Configuration
+---------------------------------------------
+
+ * Supported hook core types include *circ*, *ahr*, *ausp*, and *au*
+ * Reactor is *ProcessTemplate*
+
+Event Environment Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ * Patron object with card
+ * copy object
+ ** circ.target_copy
+ ** hold.current_copy
+ * Org unit
+ ** circ.circ_lib
+ ** ahr.pickup_lib
+ ** ausp.org_unit
+ ** patron.home_ou
+
+Not all fields are relevant to all notice types.
+
+Required Event Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ * notify_media (e.g. phone)
+ * notify_type (e.g. overdue)
+ * notify_level (e.g. "1" -- first overdue)
+
+The set of options for each event parameter is dependent on the 3rd-party
+processing the CSV file.
+
+iTiva Event Parameter Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ * notify_media
+ ** V (voice)
+ ** T (text)
+ * notify_level
+ ** 1 (1st notice)
+ ** 2 (2nd notice)
+ ** 3 (3rd notice)
+ * notify_type
+ ** FINES
+ ** OVERDUE
+ ** PREOVERDUE
+ ** PRERESERVE
+ ** RECALL
+ ** RESERVE
+ ** RESERVECANCEL
+ ** RESERVEEXPIRE
+ ** SUSPEND
+
+Push/Fetch Scripts
+------------------
+
+ * action_trigger_aggregator.pl collects event output from requested event
+ definitions and stitches them together into a single file, which is sent
+ via (s)FTP to the 3rd party.
+ * Why don't we use the SendFile reactor directly?
+ ** The final file is meant to be a collection of event-def outputs, not
+ the output from a single event def
+ ** The final file may be too large to reasonably store directly in a
+ single action/trigger event_output row.
+ * csv_notify_fetcher.pl retrieves responses from the 3rd party and applies
+ the statuses to the async_output of each notified event.
+++ /dev/null
-New Feature: Generic CSV Notification Generator/Receiver
-========================================================
-
-New Action/Trigger template and sample event definitions for creating a CSV
-export file for various patron actions, primarily for the purpose of creating
-patron notices via external notification mechanisms.
-
-The reference implementation for this development is the TalkingTech iTiva
-product, which consumes CSV files for generating phone/text notifications and
-produces CSV results files for informing the ILS of notification statuses.
-The template and send/receive scripts, however, should be generic enough to
-create CSV for any type of 3rd-party notification product.
-
-Action/Trigger Event Definition Configuration
----------------------------------------------
-
- * Supported hook core types include *circ*, *ahr*, *ausp*, and *au*
- * Reactor is *ProcessTemplate*
-
-Event Environment Requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- * Patron object with card
- * copy object
- ** circ.target_copy
- ** hold.current_copy
- * Org unit
- ** circ.circ_lib
- ** ahr.pickup_lib
- ** ausp.org_unit
- ** patron.home_ou
-
-Not all fields are relevant to all notice types.
-
-Required Event Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
- * notify_media (e.g. phone)
- * notify_type (e.g. overdue)
- * notify_level (e.g. "1" -- first overdue)
-
-The set of options for each event parameter is dependent on the 3rd-party
-processing the CSV file.
-
-iTiva Event Parameter Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- * notify_media
- ** V (voice)
- ** T (text)
- * notify_level
- ** 1 (1st notice)
- ** 2 (2nd notice)
- ** 3 (3rd notice)
- * notify_type
- ** FINES
- ** OVERDUE
- ** PREOVERDUE
- ** PRERESERVE
- ** RECALL
- ** RESERVE
- ** RESERVECANCEL
- ** RESERVEEXPIRE
- ** SUSPEND
-
-Push/Fetch Scripts
-------------------
-
- * action_trigger_aggregator.pl collects event output from requested event
- definitions and stitches them together into a single file, which is sent
- via (s)FTP to the 3rd party.
- * Why don't we use the SendFile reactor directly?
- ** The final file is meant to be a collection of event-def outputs, not
- the output from a single event def
- ** The final file may be too large to reasonably store directly in a
- single action/trigger event_output row.
- * csv_notify_fetcher.pl retrieves responses from the 3rd party and applies
- the statuses to the async_output of each notified event.
--- /dev/null
+Statistically generated Record Ratings (Popularity)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Summary
++++++++
+
+For the purpose of supplying non-bibliographic popularity adjustment to the ranking of search results, this feature implements a set of statistical modelling algorithms which will identify bibliographic records of particular note based on derivable parameters.
+
+Generally, factors such as to circulation and hold activity, record and item age, and item ownership counts will available for statistical consideration. Each factor will embody a "popularity badge" that the bibliographic record can earn, and each badge will have a 5-point scale, where more points indicates a more popular record. The average of the badge points earned by each record will constitute a "popularity rating". The number and types of badges will break ties for average popularity, and relevance will sort items with like popularity.
+
+A new sort axis of *Popularity* is created to sort first on the weighted average popularity of each record, followed by the query-specific relevance available today. A new option is created in the dropdown that sorts on the combination of "activity metric" (aka badge ranking, aka popularity) first and the existing, stock relevance ranking when those are equal. For instance, given two records that both have a badge ranking of "4.5", they will be sorted in the order of the query relevance ranking that is calculated today as a tie breaker. Those two records will sort above other records with lower badge rankings regardless of what today's relevance ranking says about them.
+
+In addition, a new sort axis of *Popularity and Relevance* is created that augments the normal Relevance sort with a normalized popularity value by multiplying the base relevance by a value controlled by a new global flag, generally set to a decimal number between 1 and 2.
+
+Finally, there will continue to be a pure *Relevance* sort option, which is the version that exists today.
+
+A global flag will allow the selection of the default sort axis.
+
+
+The basics
+++++++++++
+
+There will exist two classes of non-bibliographic popularity badge: point-in-time popularity, such as the number of items held or the number of open hold requests; and temporal popularity, such as circulations over the past two years or hold requests placed over the last six months.
+
+Each popularity badge will have a definition. The badge's value are calculated for each bibliographic record within the definition's bibliographic population. The population circumscribes the bibliographic records that are eligible to receive the badge. Each record within the population of a badge definition will receive a ranking adjustment, based on its "popularity rating" if the appropriate thresholds are met.
+
+The set of existing popularity badges is displayed as a grid. A library selector defaulting to the workstation location will allow scoping the grid contents to specific organizational units. Creating or editing a badge is performed within a dedicated modal popup interface that will float above the grid, disabling access to the underlying interface until the action is completed or canceled.
+
+All popularity badge definitions will describe a set of configuration, population criteria, and statistical constraints:
+
+* *Badge Name:* The administrator-assigned name of the popularity badge definition. This is presented as a text input box, and the value is used in the OPAC.
+* *Scope:* The owning org unit of the badge. Badges are cumulative, and are included in ranking when the Scope is equal to, or an ancestor of, the search location. Therefore branch-specific searches will include branch, system and consortium badges, but consortium-wide searches will only make use of consortium-scoped badges. For item-specific metrics, this also limits the population of the statistical group to those records having items whose owning library is at or below the Scope in the org tree. This is presented as a standard Library selector.
+* *Weight:* A multiplier defining the importance of this particular badge in relation to any other badges that might be earned by a record. This is presented as a number spinner with a default and minimum value of 1.
+* *Recalculation Interval:* How often to recalculate the badge's popularity value for each record. For temporal popularity badges that may change quickly, such as in-house use or short-duration circulation-over-time, this may be nightly. For slowly changing metrics such as count of items held, this may be monthly or quarterly. This is presented as a text input that will accept an interval string such as "2 years", "30 days", or "6 weeks, 2 days". Numeric values without a timespan qualifier are considered to be a number of seconds. For newer items that may have rapidly changing metrics, a mechanism is created to adjust the "last calculated date" so that library staff can clear the date and force a recalculation overnight. However, because the badge value each record receives is relative to all the other records in the population, the badge as a whole will need to be recalculated. This feature stores individual record raw stats, where possible and reasonable, to speed up recalculation.
+* *Population Filters:* Optional, and any combination may be used.
+** *Attribute Filter:* Filter bibliographic record population based on record attributes. This will use an interface similar to the Composite Attribute editor.
+** *Bibliographic Source:* Filter bibliographic records to those with a specific source. This is presented as a dropdown of sources.
+** *Circulation Modifier Filter:* Include only those items that make use of certain Circulation Modifiers in statistical calculations. This is only applicable to item-related badges. This is presented as a dropdown of modifiers.
+** *Copy Location Group:* Include only those items that are assigned to shelving locations within specific location groups. This is only applicable to item-related badges. This is presented as a dropdown of location groups available within the Scope for the badge.
+* *Popularity Parameter:* One of a set of predefined types of popularity measure. This is presented as a dropdown. These will include, but may not be limited to:
+** Holds Filled Over Time
+** Holds Requested Over Time
+** Current Hold Count
+** Circulations Over Time
+** Current Circulation Count
+** Out/Total Ratio
+** Holds/Total Ratio
+** Holds/Holdable Ratio
+** Percent of Time Circulating -- Of the time between the active date of the copies on the record and the badge calculation time, the percentage of that time during which the items have been checked out. This is meant to be an indicator of high-demand over the lifetime of the title, and not just a temporary spike in circ count for, say, a book club or school report. Recent temporary spikes can be represented by circs over time with a time horizon. It's the difference between an "always popular" title and a "just recently popular" title.
+** Bibliographic Record Age (days)
+** Publication Age (days)
+** Available On-Line (for e-books, etc)
+** Copy Count
+* *Fixed Rating:* An optional override supplying a fixed popularity value for all records earning this badge. For some popularity types, such as "Available On-Line", it is preferable to specify, rather than calculate, the popularity value for a badge. This is presented as a number spinner with a value ranging from 1 to 5.
+* *Inclusion Threshold Percentile:* Cumulative distribution percentile. This is presented as a number spinner of "percentile" values ranging from 50 to 100, indicating the number of how much of the population a record's score must be better than in order to earn the badge. Leaving this value unset will allow the entire population to earn the badge.
+* *Discard most common:* A value that, if greater than 0, will ignore records with extremely common values so that outliers are more readily identified, and the distribution of values can be assumed to be more normal. Many popularity parameters, such as those for circulation counts, benefit from this input filter. This is presented as a number spinner initially set to 0 that indicates the number of distinct, low values -- but not the values themselves -- to exclude from the population.
+
+This new feature comes with a starter badge based on the top 97th percentile of holds requested over the past five years.
+
+A word about Inclusion Threshold Percentile
++++++++++++++++++++++++++++++++++++++++++++
+
+In order to limit the amount of data that must be retained and queried during normal search operations, to allow limiting the popular population to truly exceptional records when appropriate, and to limit the speed cost of popularity ranking, many popularity types will provide thresholds that must be passed in order to store a record's badge-specific popularity value.
+
+The administrator will be presented with a choice of "percentile" that defines the threshold which must be crossed before the value of the variable for any given record is considered statistically significant, and therefore scaled and included in ranking. For instance, a record may need to be in the 95th percentile for Holds/Total Items before it is considered "popular" and the badge is earned.
+
+Additionally, in order to normalize populations that exhibit a "long tail" effect, such as for circulation counts were most records will have a very low number of events, the administrator will be able to instruct the algorithm to ignore the most common low values.
+
+Type-specific input modifications
++++++++++++++++++++++++++++++++++
+
+For temporal popularity badges, two time-horizons are required. The first is the inclusion horizon, or the age at which events are no longer considered. This will allow, for instance, limiting circulation calculations to only the past two years. The second is the importance aging horizon, which will allow recent events to be considered more important than those further in the past. A value of zero for this horizon will mean that all events are seen to be of equal importance. These are presented as text inputs that will accept interval strings such as "2 years", "30 days", or "6 weeks, 2 days". Numeric values without a timespan qualifier are considered to be a number of seconds.
+
+For those badges that have the Fixed Rating flag set, no statistical input is gathered for records in the population of the badge definition. Instead, all records in the population are assigned this fixed value for the badge.
+
+Rating process
+++++++++++++++
+
+For badges other than those with the Fixed Rating set, the collected statistical input parameters are used to derive the mean, median, mode, min, max, and standard deviation values for the bibliographic record population. Each record passing the requisite thresholds are assigned a badge-specific value based on the quintile into which the value falls. This value, interpreted as a one-to-five rating, is stored for static application, instead of being calculated on the fly, when the badge is in scope and the record is part of a search result set. Thus records with values in the bottom quintile will have a rating of one, and records with values in the top quintile will have a rating of five.
+
+All badge values for all records are calculated by a secondary process that runs in the background on the server on a regular basis.
+
+Display in the OPAC
++++++++++++++++++++
+
+Ratings are displayed in two places within the OPAC. Like the rest of the TPAC, this is templated and display can be modified or disabled through customization.
+
+First, on the record result page, the overall average popularity rating is displayed with a label of "Popularity" below the record-specific data such as call number and publisher, and above the holdings counts.
+
+Second, on the record detail page, the list of badge names earned by the record that are in scope for the search location, and the 1-5 rating value of each badge, is displayed in a horizontal list above the copy detail table.
+
+Future possibilities
+++++++++++++++++++++
+
+This infrastructure will directly support future work such as Patron and Staff ratings, and even allow search and browse filtering based on specific badges and ratings. Additionally, bibliographic information could be leveraged to create metadata badges that would affect the ranking of record, in addition to the non-bibliographic badges described here.
+
+Performance
++++++++++++
+
+It is expected that there may be some very small speed impact, but all attempts have been made to mitigate this by precalculating the adjustment values and by keeping the search-required data as compact as possible. By doing this, the aggregate cost per search should be extremely small. In addition, the development will include a setting to define the amount of database resources to dedicate to the job of badge value calculation and reduce its run time.
+
+++ /dev/null
-Statistically generated Record Ratings (Popularity)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Summary
-+++++++
-
-For the purpose of supplying non-bibliographic popularity adjustment to the ranking of search results, this feature implements a set of statistical modelling algorithms which will identify bibliographic records of particular note based on derivable parameters.
-
-Generally, factors such as to circulation and hold activity, record and item age, and item ownership counts will available for statistical consideration. Each factor will embody a "popularity badge" that the bibliographic record can earn, and each badge will have a 5-point scale, where more points indicates a more popular record. The average of the badge points earned by each record will constitute a "popularity rating". The number and types of badges will break ties for average popularity, and relevance will sort items with like popularity.
-
-A new sort axis of *Popularity* is created to sort first on the weighted average popularity of each record, followed by the query-specific relevance available today. A new option is created in the dropdown that sorts on the combination of "activity metric" (aka badge ranking, aka popularity) first and the existing, stock relevance ranking when those are equal. For instance, given two records that both have a badge ranking of "4.5", they will be sorted in the order of the query relevance ranking that is calculated today as a tie breaker. Those two records will sort above other records with lower badge rankings regardless of what today's relevance ranking says about them.
-
-In addition, a new sort axis of *Popularity and Relevance* is created that augments the normal Relevance sort with a normalized popularity value by multiplying the base relevance by a value controlled by a new global flag, generally set to a decimal number between 1 and 2.
-
-Finally, there will continue to be a pure *Relevance* sort option, which is the version that exists today.
-
-A global flag will allow the selection of the default sort axis.
-
-
-The basics
-++++++++++
-
-There will exist two classes of non-bibliographic popularity badge: point-in-time popularity, such as the number of items held or the number of open hold requests; and temporal popularity, such as circulations over the past two years or hold requests placed over the last six months.
-
-Each popularity badge will have a definition. The badge's value are calculated for each bibliographic record within the definition's bibliographic population. The population circumscribes the bibliographic records that are eligible to receive the badge. Each record within the population of a badge definition will receive a ranking adjustment, based on its "popularity rating" if the appropriate thresholds are met.
-
-The set of existing popularity badges is displayed as a grid. A library selector defaulting to the workstation location will allow scoping the grid contents to specific organizational units. Creating or editing a badge is performed within a dedicated modal popup interface that will float above the grid, disabling access to the underlying interface until the action is completed or canceled.
-
-All popularity badge definitions will describe a set of configuration, population criteria, and statistical constraints:
-
-* *Badge Name:* The administrator-assigned name of the popularity badge definition. This is presented as a text input box, and the value is used in the OPAC.
-* *Scope:* The owning org unit of the badge. Badges are cumulative, and are included in ranking when the Scope is equal to, or an ancestor of, the search location. Therefore branch-specific searches will include branch, system and consortium badges, but consortium-wide searches will only make use of consortium-scoped badges. For item-specific metrics, this also limits the population of the statistical group to those records having items whose owning library is at or below the Scope in the org tree. This is presented as a standard Library selector.
-* *Weight:* A multiplier defining the importance of this particular badge in relation to any other badges that might be earned by a record. This is presented as a number spinner with a default and minimum value of 1.
-* *Recalculation Interval:* How often to recalculate the badge's popularity value for each record. For temporal popularity badges that may change quickly, such as in-house use or short-duration circulation-over-time, this may be nightly. For slowly changing metrics such as count of items held, this may be monthly or quarterly. This is presented as a text input that will accept an interval string such as "2 years", "30 days", or "6 weeks, 2 days". Numeric values without a timespan qualifier are considered to be a number of seconds. For newer items that may have rapidly changing metrics, a mechanism is created to adjust the "last calculated date" so that library staff can clear the date and force a recalculation overnight. However, because the badge value each record receives is relative to all the other records in the population, the badge as a whole will need to be recalculated. This feature stores individual record raw stats, where possible and reasonable, to speed up recalculation.
-* *Population Filters:* Optional, and any combination may be used.
-** *Attribute Filter:* Filter bibliographic record population based on record attributes. This will use an interface similar to the Composite Attribute editor.
-** *Bibliographic Source:* Filter bibliographic records to those with a specific source. This is presented as a dropdown of sources.
-** *Circulation Modifier Filter:* Include only those items that make use of certain Circulation Modifiers in statistical calculations. This is only applicable to item-related badges. This is presented as a dropdown of modifiers.
-** *Copy Location Group:* Include only those items that are assigned to shelving locations within specific location groups. This is only applicable to item-related badges. This is presented as a dropdown of location groups available within the Scope for the badge.
-* *Popularity Parameter:* One of a set of predefined types of popularity measure. This is presented as a dropdown. These will include, but may not be limited to:
-** Holds Filled Over Time
-** Holds Requested Over Time
-** Current Hold Count
-** Circulations Over Time
-** Current Circulation Count
-** Out/Total Ratio
-** Holds/Total Ratio
-** Holds/Holdable Ratio
-** Percent of Time Circulating -- Of the time between the active date of the copies on the record and the badge calculation time, the percentage of that time during which the items have been checked out. This is meant to be an indicator of high-demand over the lifetime of the title, and not just a temporary spike in circ count for, say, a book club or school report. Recent temporary spikes can be represented by circs over time with a time horizon. It's the difference between an "always popular" title and a "just recently popular" title.
-** Bibliographic Record Age (days)
-** Publication Age (days)
-** Available On-Line (for e-books, etc)
-** Copy Count
-* *Fixed Rating:* An optional override supplying a fixed popularity value for all records earning this badge. For some popularity types, such as "Available On-Line", it is preferable to specify, rather than calculate, the popularity value for a badge. This is presented as a number spinner with a value ranging from 1 to 5.
-* *Inclusion Threshold Percentile:* Cumulative distribution percentile. This is presented as a number spinner of "percentile" values ranging from 50 to 100, indicating the number of how much of the population a record's score must be better than in order to earn the badge. Leaving this value unset will allow the entire population to earn the badge.
-* *Discard most common:* A value that, if greater than 0, will ignore records with extremely common values so that outliers are more readily identified, and the distribution of values can be assumed to be more normal. Many popularity parameters, such as those for circulation counts, benefit from this input filter. This is presented as a number spinner initially set to 0 that indicates the number of distinct, low values -- but not the values themselves -- to exclude from the population.
-
-This new feature comes with a starter badge based on the top 97th percentile of holds requested over the past five years.
-
-A word about Inclusion Threshold Percentile
-+++++++++++++++++++++++++++++++++++++++++++
-
-In order to limit the amount of data that must be retained and queried during normal search operations, to allow limiting the popular population to truly exceptional records when appropriate, and to limit the speed cost of popularity ranking, many popularity types will provide thresholds that must be passed in order to store a record's badge-specific popularity value.
-
-The administrator will be presented with a choice of "percentile" that defines the threshold which must be crossed before the value of the variable for any given record is considered statistically significant, and therefore scaled and included in ranking. For instance, a record may need to be in the 95th percentile for Holds/Total Items before it is considered "popular" and the badge is earned.
-
-Additionally, in order to normalize populations that exhibit a "long tail" effect, such as for circulation counts were most records will have a very low number of events, the administrator will be able to instruct the algorithm to ignore the most common low values.
-
-Type-specific input modifications
-+++++++++++++++++++++++++++++++++
-
-For temporal popularity badges, two time-horizons are required. The first is the inclusion horizon, or the age at which events are no longer considered. This will allow, for instance, limiting circulation calculations to only the past two years. The second is the importance aging horizon, which will allow recent events to be considered more important than those further in the past. A value of zero for this horizon will mean that all events are seen to be of equal importance. These are presented as text inputs that will accept interval strings such as "2 years", "30 days", or "6 weeks, 2 days". Numeric values without a timespan qualifier are considered to be a number of seconds.
-
-For those badges that have the Fixed Rating flag set, no statistical input is gathered for records in the population of the badge definition. Instead, all records in the population are assigned this fixed value for the badge.
-
-Rating process
-++++++++++++++
-
-For badges other than those with the Fixed Rating set, the collected statistical input parameters are used to derive the mean, median, mode, min, max, and standard deviation values for the bibliographic record population. Each record passing the requisite thresholds are assigned a badge-specific value based on the quintile into which the value falls. This value, interpreted as a one-to-five rating, is stored for static application, instead of being calculated on the fly, when the badge is in scope and the record is part of a search result set. Thus records with values in the bottom quintile will have a rating of one, and records with values in the top quintile will have a rating of five.
-
-All badge values for all records are calculated by a secondary process that runs in the background on the server on a regular basis.
-
-Display in the OPAC
-+++++++++++++++++++
-
-Ratings are displayed in two places within the OPAC. Like the rest of the TPAC, this is templated and display can be modified or disabled through customization.
-
-First, on the record result page, the overall average popularity rating is displayed with a label of "Popularity" below the record-specific data such as call number and publisher, and above the holdings counts.
-
-Second, on the record detail page, the list of badge names earned by the record that are in scope for the search location, and the 1-5 rating value of each badge, is displayed in a horizontal list above the copy detail table.
-
-Future possibilities
-++++++++++++++++++++
-
-This infrastructure will directly support future work such as Patron and Staff ratings, and even allow search and browse filtering based on specific badges and ratings. Additionally, bibliographic information could be leveraged to create metadata badges that would affect the ranking of record, in addition to the non-bibliographic badges described here.
-
-Performance
-+++++++++++
-
-It is expected that there may be some very small speed impact, but all attempts have been made to mitigate this by precalculating the adjustment values and by keeping the search-required data as compact as possible. By doing this, the aggregate cost per search should be extremely small. In addition, the development will include a setting to define the amount of database resources to dedicate to the job of badge value calculation and reduce its run time.
-
--- /dev/null
+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,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,Batch Importing MARC Records>> in Cataloging)
+* Providers
+
+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.
+
+image::media/acq_workflow.jpg[workflow diagram]
+++ /dev/null
-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,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,Batch Importing MARC Records>> in Cataloging)
-* Providers
-
-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.
-
-image::media/acq_workflow.jpg[workflow diagram]
--- /dev/null
+Invoices
+--------
+
+
+indexterm:[acquisitions,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.
+
+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.
+
+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.
++
+[NOTE]
+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.
+
+image::media/acq_invoice_blanket.png[Blanket invoice]
+
+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.
+
++
+[NOTE]
+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.
+
+Search for line items from an invoice
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[acquisitions,lineitems,searching for]
+indexterm:[acquisitions,invoices,searching for lineitems]
+
+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:
+
+indexterm:[acquisitions,lineitems,adding]
+
+. 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.
++
+NOTE: If you do not want to display the details, click _Hide Details_.
++
+image::media/Search_for_line_items_from_an_invoice1.jpg[Search_for_line_items_from_an_invoice1]
++
+. 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_.
++
+image::media/Search_for_line_items_from_an_invoice2.jpg[Search_for_line_items_from_an_invoice2]
++
+. 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.
++
+image::media/Search_for_line_items_from_an_invoice3.jpg[Search_for_line_items_from_an_invoice3]
++
+. 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.
+
+image::media/Search_for_line_items_from_an_invoice5.jpg[Search_for_line_items_from_an_invoice5]
+
+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.
++
+[NOTE]
+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.
+
++
+[NOTE]
+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.
+
+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_.
+
+image::media/acq_invoice_link.png[Link Invoice]
+
+Electronic Invoicing
+~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,invoices,electronic]
+
+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.
+
+image::media/Electronic_invoicing1.jpg[Electronic_invoicing1]
+
+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_.
++
+image::media/acq_invoice_view.png[Open Invoice 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.
++
+image::media/acq_invoice_view-2.png[View Invoices from PO]
++
+. 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.
+++ /dev/null
-Invoices
---------
-
-
-indexterm:[acquisitions,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.
-
-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.
-
-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.
-+
-[NOTE]
-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.
-
-image::media/acq_invoice_blanket.png[Blanket invoice]
-
-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.
-
-+
-[NOTE]
-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.
-
-Search for line items from an invoice
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[acquisitions,lineitems,searching for]
-indexterm:[acquisitions,invoices,searching for lineitems]
-
-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:
-
-indexterm:[acquisitions,lineitems,adding]
-
-. 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.
-+
-NOTE: If you do not want to display the details, click _Hide Details_.
-+
-image::media/Search_for_line_items_from_an_invoice1.jpg[Search_for_line_items_from_an_invoice1]
-+
-. 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_.
-+
-image::media/Search_for_line_items_from_an_invoice2.jpg[Search_for_line_items_from_an_invoice2]
-+
-. 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.
-+
-image::media/Search_for_line_items_from_an_invoice3.jpg[Search_for_line_items_from_an_invoice3]
-+
-. 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.
-
-image::media/Search_for_line_items_from_an_invoice5.jpg[Search_for_line_items_from_an_invoice5]
-
-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.
-+
-[NOTE]
-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.
-
-+
-[NOTE]
-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.
-
-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_.
-
-image::media/acq_invoice_link.png[Link Invoice]
-
-Electronic Invoicing
-~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,invoices,electronic]
-
-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.
-
-image::media/Electronic_invoicing1.jpg[Electronic_invoicing1]
-
-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_.
-+
-image::media/acq_invoice_view.png[Open Invoice 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.
-+
-image::media/acq_invoice_view-2.png[View Invoices from PO]
-+
-. 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.
--- /dev/null
+Managing patron purchase requests
+---------------------------------
+
+indexterm:[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.
+
+Adding a request
+~~~~~~~~~~~~~~~~
+
+You may add a patron purchase request using this screen.
+
+. To add the request, click the _Create Request_ button.
++
+NOTE: 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.
+
+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.
+
+++ /dev/null
-Managing patron purchase requests
----------------------------------
-
-indexterm:[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.
-
-Adding a request
-~~~~~~~~~~~~~~~~
-
-You may add a patron purchase request using this screen.
-
-. To add the request, click the _Create Request_ button.
-+
-NOTE: 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.
-
-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.
-
--- /dev/null
+Placing purchase requests from a patron record
+----------------------------------------------
+
+indexterm:[patrons, 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 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.
++
+NOTE: 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.
+
+++ /dev/null
-Placing purchase requests from a patron record
-----------------------------------------------
-
-indexterm:[patrons, 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 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.
-+
-NOTE: 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.
-
--- /dev/null
+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.
+
+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*.
+
+image::media/Receive_Items_From_an_Invoice1.jpg[Receive_Items_From_an_Invoice1]
+
+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.
+
+
+image::media/Receive_Items_From_an_Invoice2.jpg[Receive_Items_From_an_Invoice2]
+
+
+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.
+
+
+NOTE: You cannot receive fewer items than 0 (zero) or more items than the number that you ordered.
+
+
+8) Click *Receive Selected Copies*.
+
+
+image::media/Receive_Items_From_an_Invoice4.jpg[Receive_Items_From_an_Invoice4]
+
+
+9) When you are finished receiving items, close the screen. You can repeat this process as you receive more copies.
+
+
+
+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*.
+
+image::media/Receive_Items_From_an_Invoice5.jpg[Receive_Items_From_an_Invoice5]
+
+
+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.
+
+image::media/Receive_Items_From_an_Invoice7.jpg[Receive_Items_From_an_Invoice7]
+
+++ /dev/null
-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.
-
-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*.
-
-image::media/Receive_Items_From_an_Invoice1.jpg[Receive_Items_From_an_Invoice1]
-
-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.
-
-
-image::media/Receive_Items_From_an_Invoice2.jpg[Receive_Items_From_an_Invoice2]
-
-
-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.
-
-
-NOTE: You cannot receive fewer items than 0 (zero) or more items than the number that you ordered.
-
-
-8) Click *Receive Selected Copies*.
-
-
-image::media/Receive_Items_From_an_Invoice4.jpg[Receive_Items_From_an_Invoice4]
-
-
-9) When you are finished receiving items, close the screen. You can repeat this process as you receive more copies.
-
-
-
-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*.
-
-image::media/Receive_Items_From_an_Invoice5.jpg[Receive_Items_From_an_Invoice5]
-
-
-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.
-
-image::media/Receive_Items_From_an_Invoice7.jpg[Receive_Items_From_an_Invoice7]
-
--- /dev/null
+Selection Lists and Purchase Orders
+-----------------------------------
+
+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.
+
+Create a selection list
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Selection lists can be created in four areas within the module. Selection lists can be created when you <<_brief_records,Add Brief Records>>, Upload MARC Order Records, or find records through the <<_marc_federated_search_2,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.
+
+image::media/acq_selection_create.png[create selection list]
+
+Add items to a selection list
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can add items to a selection list in one of three ways: <<_brief_records,add a brief record>>; upload MARC order records; add records through a <<_marc_federated_search_2,federated search>>; or use the View/Place Orders menu item in the catalog.
+
+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.
+
+image::media/acq_selection_clone.png[clone selection list]
+
+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.
+
+image::media/acq_selection_merge.png[merge selection list]
+
+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.
+
+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.
+
+image::media/acq_selection_mark_ready.png[mark ready]
+
+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.
+
+
+Purchase Orders
+~~~~~~~~~~~~~~~
+
+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*
+
+image::media/po_name_detection_1.JPG[PO Name Detection 1]
+
+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*.
+
+image::media/po_name_detection_2.JPG[PO Name Detection 2]
+
+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.
+
+image::media/po_name_detection_3.JPG[PO Name Detection 3]
+
+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.
+
+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
+
+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*.
+
+image::media/Zero_Copies1.jpg[Zero_Copies1]
+
+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.
+
+image::media/2_7_Enhancements_to_Canceled2.jpg[Canceled2]
+
+
+image::media/2_7_Enhancements_to_Canceled4.jpg[Canceled4]
+
+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.
+
+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.
+
+image::media/2_10_Lineitem_Paid.png[Paid Lineitem]
+
+
+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.
+
+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.
+
+image::media/acq_brief_record.png[]
+
+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,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.
+
+image::media/acq_brief_record-2.png[]
+
+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.
++
+image::media/acq_marc_search.png[search form]
++
+. A list of results will appear. Click the "Copies" link to add copy information to the line item. See the <<_line_items,section on Line Items>> for more information.
+. Click the Notes link to add notes or line item alerts to the line item. See the <<_line_items,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.
+
+image::media/acq_marc_search-2.png[line item]
+
+Line Items
+~~~~~~~~~~
+
+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.
+
+image::media/Return_to_line_item1.jpg[Return_to_line_item1]
+
+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
+
+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.
+
+image::media/display_copy_count_1.JPG[Display Copy Count 1]
+
+The user may also hover over the existing copy count to view the accompanying tooltip.
+
+image::media/display_copy_count_2.JPG[Display Copy Count 2]
+
+
+++ /dev/null
-Selection Lists and Purchase Orders
------------------------------------
-
-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.
-
-Create a selection list
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Selection lists can be created in four areas within the module. Selection lists can be created when you <<_brief_records,Add Brief Records>>, Upload MARC Order Records, or find records through the <<_marc_federated_search_2,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.
-
-image::media/acq_selection_create.png[create selection list]
-
-Add items to a selection list
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can add items to a selection list in one of three ways: <<_brief_records,add a brief record>>; upload MARC order records; add records through a <<_marc_federated_search_2,federated search>>; or use the View/Place Orders menu item in the catalog.
-
-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.
-
-image::media/acq_selection_clone.png[clone selection list]
-
-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.
-
-image::media/acq_selection_merge.png[merge selection list]
-
-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.
-
-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.
-
-image::media/acq_selection_mark_ready.png[mark ready]
-
-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.
-
-
-Purchase Orders
-~~~~~~~~~~~~~~~
-
-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*
-
-image::media/po_name_detection_1.JPG[PO Name Detection 1]
-
-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*.
-
-image::media/po_name_detection_2.JPG[PO Name Detection 2]
-
-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.
-
-image::media/po_name_detection_3.JPG[PO Name Detection 3]
-
-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.
-
-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
-
-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*.
-
-image::media/Zero_Copies1.jpg[Zero_Copies1]
-
-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.
-
-image::media/2_7_Enhancements_to_Canceled2.jpg[Canceled2]
-
-
-image::media/2_7_Enhancements_to_Canceled4.jpg[Canceled4]
-
-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.
-
-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.
-
-image::media/2_10_Lineitem_Paid.png[Paid Lineitem]
-
-
-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.
-
-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.
-
-image::media/acq_brief_record.png[]
-
-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,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.
-
-image::media/acq_brief_record-2.png[]
-
-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.
-+
-image::media/acq_marc_search.png[search form]
-+
-. A list of results will appear. Click the "Copies" link to add copy information to the line item. See the <<_line_items,section on Line Items>> for more information.
-. Click the Notes link to add notes or line item alerts to the line item. See the <<_line_items,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.
-
-image::media/acq_marc_search-2.png[line item]
-
-Line Items
-~~~~~~~~~~
-
-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.
-
-image::media/Return_to_line_item1.jpg[Return_to_line_item1]
-
-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
-
-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.
-
-image::media/display_copy_count_1.JPG[Display Copy Count 1]
-
-The user may also hover over the existing copy count to view the accompanying tooltip.
-
-image::media/display_copy_count_2.JPG[Display Copy Count 2]
-
-
--- /dev/null
+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
+<<batchimport, Batch Importing MARC Records>>.
+
+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.
+
+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.
+
+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
+
+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
+
+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*.
++
+image::media/Vandelay_Integration_into_Acquisitions1.jpg[Vandelay_Integration_into_Acquisitions1]
++
+. The processed items appear at the bottom of the screen.
++
+image::media/Vandelay_Integration_into_Acquisitions2.jpg[Vandelay_Integration_into_Acquisitions2]
+. 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.
++
+image::media/Vandelay_Integration_into_Acquisitions3.jpg[Vandelay_Integration_into_Acquisitions3]
+. 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.
+
+image::media/Vandelay_Integration_into_Acquisitions4.jpg[Vandelay_Integration_into_Acquisitions4]
+
+*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*.
++
+image::media/Vandelay_Integration_into_Acquisitions5.jpg[Vandelay_Integration_into_Acquisitions5]
++
+. 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*.
++
+image::media/Vandelay_Integration_into_Acquisitions6.jpg[Vandelay_Integration_into_Acquisitions6]
++
+. 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.
+++ /dev/null
-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
-<<batchimport, Batch Importing MARC Records>>.
-
-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.
-
-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.
-
-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
-
-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
-
-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*.
-+
-image::media/Vandelay_Integration_into_Acquisitions1.jpg[Vandelay_Integration_into_Acquisitions1]
-+
-. The processed items appear at the bottom of the screen.
-+
-image::media/Vandelay_Integration_into_Acquisitions2.jpg[Vandelay_Integration_into_Acquisitions2]
-. 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.
-+
-image::media/Vandelay_Integration_into_Acquisitions3.jpg[Vandelay_Integration_into_Acquisitions3]
-. 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.
-
-image::media/Vandelay_Integration_into_Acquisitions4.jpg[Vandelay_Integration_into_Acquisitions4]
-
-*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*.
-+
-image::media/Vandelay_Integration_into_Acquisitions5.jpg[Vandelay_Integration_into_Acquisitions5]
-+
-. 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*.
-+
-image::media/Vandelay_Integration_into_Acquisitions6.jpg[Vandelay_Integration_into_Acquisitions6]
-+
-. 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.
--- /dev/null
+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.
+
+
+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*.
+
+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.
+
+image::media/best_hold_sort_order1.jpg[Best-Hold Selection Sort Order]
+
+
+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.
+
+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*.
+
+image::media/best_hold_sort_order2.jpg[Library Settings Editor]
+
+
+Permissions to use this Feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To administer the custom Best-Hold Selection Sort Order interface, you need the following permission:
+
+* ADMIN_HOLD_CAPTURE_SORT
\ No newline at end of file
+++ /dev/null
-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.
-
-
-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*.
-
-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.
-
-image::media/best_hold_sort_order1.jpg[Best-Hold Selection Sort Order]
-
-
-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.
-
-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*.
-
-image::media/best_hold_sort_order2.jpg[Library Settings Editor]
-
-
-Permissions to use this Feature
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To administer the custom Best-Hold Selection Sort Order interface, you need the following permission:
-
-* ADMIN_HOLD_CAPTURE_SORT
\ No newline at end of file
--- /dev/null
+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
+
+
+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.
+
+
+image::media/marc_import_remove_fields3.jpg[MARC Remove Fields Profile]
+
+
+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*
+
+image::media/marc_import_remove_fields1.jpg[Import Record from Z39.50]
+{nbsp}
+
+*Cataloging -> MARC Batch Import/Export*
+
+image::media/marc_import_remove_fields2.jpg[MARC Batch Import/Export]
+{nbsp}
+
+*Acquisitions -> Load MARC Order Records*
+
+image::media/marc_import_remove_fields5.jpg[Load MARC Order Records]
+
+
+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
+++ /dev/null
-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
-
-
-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.
-
-
-image::media/marc_import_remove_fields3.jpg[MARC Remove Fields Profile]
-
-
-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*
-
-image::media/marc_import_remove_fields1.jpg[Import Record from Z39.50]
-{nbsp}
-
-*Cataloging -> MARC Batch Import/Export*
-
-image::media/marc_import_remove_fields2.jpg[MARC Batch Import/Export]
-{nbsp}
-
-*Acquisitions -> Load MARC Order Records*
-
-image::media/marc_import_remove_fields5.jpg[Load MARC Order Records]
-
-
-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
--- /dev/null
+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*
+
+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.
+
+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).
+
+image::media/radmvcolumn_1.jpg[]
+
+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*
+
+image::media/editrad_2.jpg[]
+
+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.
+
+image::media/radcvmcacolumns_3.jpg[]
+
+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.
+
+image::media/cvmpage_4.jpg[]
+
+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*
+
+image::media/radcatrue_5.jpg[]
+
+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.
+
+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.
+
+image::media/caed_6.jpg[]
+
+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
+
+image::media/modifycde_7.jpg[]
+
+Search and Icon Formats
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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 <<anchor-1,fixed field types>> at the end of this document.
+
+[width="60%", cols="<,<,<"]
+|====
+|*Icon* |*Search Label/Icon Label* |*Definition*
+|image:media/blu-ray.png[] | Blu-ray | VR Format:s
+|image:media/book.png[] | 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]_
+|image:media/braille.png[] | Braille | Item Type: a
+
+Item Form: f
+|image:media/casaudiobook.png[] | Cassette audiobook | Item Type: i
+
+SR Format: l
+|image:media/casmusic.png[] | Audiocassette music recording | Item Type: j
+
+SR Format: l
+|image:media/cdaudiobook.png[] | CD audiobook | Item Type: i
+
+SR Format: f
+|image:media/cdmusic.png[] | CD music recording | Item Type: j
+
+SR Format: f
+|image:media/dvd.png[] | DVD | VR Format: v
+|image:media/eaudio.png[] | E-audio | Item Type: i
+
+Item Form: o,q,s
+|image:media/ebook.png[]| E-book | Item Type: a,t
+
+Bib Level: a,c,d,m
+
+Item Form: o,q,s
+|image:media/equip.png[] | Equipment, games, toys | Item Type: r
+|image:media/evideo.png[] | E-video | Item Type: g
+
+Item Form: o,q,s
+|image:media/kit.png[] | Kit | Item Type: o,p
+|image:media/lpbook.png[] | Large print book | Item Type: a,t
+
+Bib Level: a,c,d,m
+
+Item Form: d
+|image:media/map.png[] | Map | Item Type: e,f
+|image:media/microform.png[] | Microform | Item Form: a,b,c
+|image:media/music.png[] | All music/Music sound recording (unknown format) | Item Type: j
+
+_[NOT: SR Format: a,b,c,d,e,f,l]_
+|image:media/phonomusic.png[] | Phonograph music recording | Item Type: j
+
+SR Format: a,b,c,d,e
+|image:media/phonospoken.png[] | Phonograph spoken recording | Item Type: i
+
+SR Format: a,b,c,d,e
+|image:media/picture.png[] | Picture | Item type: k
+|image:media/score.png[] | Music score | Item type: c,d
+|image:media/serial.png[] | Serials and magazines | Bib Level: b,s
+|image:media/software.png[] | Software and video games | Item Type: m
+|image:media/vhs.png[] | VHS | VR Format: b
+|====
+
+[[anchor-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.
+
+[width="30%", cols="<,<,<"]
+|====
+| *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
+|====
+
+[[anchor-1]]
+Fixed Field Types
++++++++++++++++++
+This table details the fixed field types currently used for determining search and icon formats. See the <<anchor-2,record types>> section above for how the system determines them.
+
+[width="40%", cols="<,<,<,<"]
+|====
+| *Label* | *Record Type* | *Tag* | *Position*
+|Item Type | ANY | LDR | 06
+|Bib Level | ANY | LDR | 07
+.14+^.^| Item Format .2+^.^| BKS | 006 | 06
+| 008 | 23
+.2+^.^| MAP | 006 | 12
+|008 | 29
+.2+^.^| MIX | 006 | 06
+| 008 | 23
+.2+^.^| REC | 006 | 06
+| 008 | 23
+.2+^.^| SCO | 006 |06
+| 008 | 23
+.2+^.^| SER | 006 | 06
+| 008 | 23
+.2+^.^| VIS | 006 | 12
+| 008 | 29
+| SR Format | ANY | 007s | 03
+| VR Format | ANY | 007v | 04
+|====
+
+++ /dev/null
-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*
-
-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.
-
-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).
-
-image::media/radmvcolumn_1.jpg[]
-
-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*
-
-image::media/editrad_2.jpg[]
-
-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.
-
-image::media/radcvmcacolumns_3.jpg[]
-
-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.
-
-image::media/cvmpage_4.jpg[]
-
-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*
-
-image::media/radcatrue_5.jpg[]
-
-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.
-
-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.
-
-image::media/caed_6.jpg[]
-
-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
-
-image::media/modifycde_7.jpg[]
-
-Search and Icon Formats
-^^^^^^^^^^^^^^^^^^^^^^^
-
-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 <<anchor-1,fixed field types>> at the end of this document.
-
-[width="60%", cols="<,<,<"]
-|====
-|*Icon* |*Search Label/Icon Label* |*Definition*
-|image:media/blu-ray.png[] | Blu-ray | VR Format:s
-|image:media/book.png[] | 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]_
-|image:media/braille.png[] | Braille | Item Type: a
-
-Item Form: f
-|image:media/casaudiobook.png[] | Cassette audiobook | Item Type: i
-
-SR Format: l
-|image:media/casmusic.png[] | Audiocassette music recording | Item Type: j
-
-SR Format: l
-|image:media/cdaudiobook.png[] | CD audiobook | Item Type: i
-
-SR Format: f
-|image:media/cdmusic.png[] | CD music recording | Item Type: j
-
-SR Format: f
-|image:media/dvd.png[] | DVD | VR Format: v
-|image:media/eaudio.png[] | E-audio | Item Type: i
-
-Item Form: o,q,s
-|image:media/ebook.png[]| E-book | Item Type: a,t
-
-Bib Level: a,c,d,m
-
-Item Form: o,q,s
-|image:media/equip.png[] | Equipment, games, toys | Item Type: r
-|image:media/evideo.png[] | E-video | Item Type: g
-
-Item Form: o,q,s
-|image:media/kit.png[] | Kit | Item Type: o,p
-|image:media/lpbook.png[] | Large print book | Item Type: a,t
-
-Bib Level: a,c,d,m
-
-Item Form: d
-|image:media/map.png[] | Map | Item Type: e,f
-|image:media/microform.png[] | Microform | Item Form: a,b,c
-|image:media/music.png[] | All music/Music sound recording (unknown format) | Item Type: j
-
-_[NOT: SR Format: a,b,c,d,e,f,l]_
-|image:media/phonomusic.png[] | Phonograph music recording | Item Type: j
-
-SR Format: a,b,c,d,e
-|image:media/phonospoken.png[] | Phonograph spoken recording | Item Type: i
-
-SR Format: a,b,c,d,e
-|image:media/picture.png[] | Picture | Item type: k
-|image:media/score.png[] | Music score | Item type: c,d
-|image:media/serial.png[] | Serials and magazines | Bib Level: b,s
-|image:media/software.png[] | Software and video games | Item Type: m
-|image:media/vhs.png[] | VHS | VR Format: b
-|====
-
-[[anchor-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.
-
-[width="30%", cols="<,<,<"]
-|====
-| *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
-|====
-
-[[anchor-1]]
-Fixed Field Types
-+++++++++++++++++
-This table details the fixed field types currently used for determining search and icon formats. See the <<anchor-2,record types>> section above for how the system determines them.
-
-[width="40%", cols="<,<,<,<"]
-|====
-| *Label* | *Record Type* | *Tag* | *Position*
-|Item Type | ANY | LDR | 06
-|Bib Level | ANY | LDR | 07
-.14+^.^| Item Format .2+^.^| BKS | 006 | 06
-| 008 | 23
-.2+^.^| MAP | 006 | 12
-|008 | 29
-.2+^.^| MIX | 006 | 06
-| 008 | 23
-.2+^.^| REC | 006 | 06
-| 008 | 23
-.2+^.^| SCO | 006 |06
-| 008 | 23
-.2+^.^| SER | 006 | 06
-| 008 | 23
-.2+^.^| VIS | 006 | 12
-| 008 | 29
-| SR Format | ANY | 007s | 03
-| VR Format | ANY | 007v | 04
-|====
-
--- /dev/null
+Org Unit Proximity Adjustments
+-----------------------------
+
+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.
+
+image::media/Org_Unit_Prox_Adj1.png[Org Unit Proximity]
+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.
+
+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.
+
+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*.
+
+image::media/Org_Unit_Prox_Adj2.png[Org Unit Proximity Adjustment]
+
+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.
+
+Permissions to use this Feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To create Org Unit Proximity Adjustments, you will need the following permission:
+
+* ADMIN_PROXIMITY_ADJUSTMENT
+++ /dev/null
-Org Unit Proximity Adjustments
------------------------------
-
-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.
-
-image::media/Org_Unit_Prox_Adj1.png[Org Unit Proximity]
-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.
-
-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.
-
-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*.
-
-image::media/Org_Unit_Prox_Adj2.png[Org Unit Proximity Adjustment]
-
-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.
-
-Permissions to use this Feature
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To create Org Unit Proximity Adjustments, you will need the following permission:
-
-* ADMIN_PROXIMITY_ADJUSTMENT
--- /dev/null
+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.
+
+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.
+
+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.*
+
+image::media/SMS_Text_Messaging1.jpg[SMS_Text_Messaging1]
+
+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.*
+
+image::media/SMS_Text_Messaging2.jpg[SMS_Text_Messaging2]
+
+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.
++
+image::media/SMS_Text_Messaging3.jpg[SMS_Text_Messaging3]
++
+. 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.
+
+image::media/SMS_Text_Messaging4.jpg[SMS_Text_Messaging4]
+
+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.
++
+image::media/SMS_Text_Messaging5.jpg[SMS_Text_Messaging5]
++
+. 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.
+
+image::media/SMS_Text_Messaging6.jpg[SMS_Text_Messaging6]
+
+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.
++
+image::media/SMS_Text_Messaging12.jpg[SMS_Text_Messaging12]
++
+. 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.*
+
+image::media/SMS_Text_Messaging13.jpg[SMS_Text_Messaging13]
+
+[[Sending_Copy_Details_via_Text_Message]]
+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,Administrative Setup>> for more information.
++
+image::media/SMS_Text_Messaging7.jpg[SMS_Text_Messaging7]
++
+. Search the catalog, and retrieve a title with copies.
+. Click the *Text* link next to the call number.
++
+image::media/SMS_Text_Messaging8.png[Screenshot: Link to text copy details via SMS]
++
+. The text of the SMS Text Message appears.
++
+image::media/SMS_Text_Messaging9.png[Screenshot: Text message preview with submit form]
++
+. 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.
++
+image::media/SMS_Text_Messaging11.png[Screenshot: Confirmation page that SMS message was sent]
+
+*Permissions to use this Feature*
+
+ADMIN_SMS_CARRIER - Enables users to add/create/delete SMS Carrier entries.
+
+
+++ /dev/null
-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.
-
-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.
-
-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.*
-
-image::media/SMS_Text_Messaging1.jpg[SMS_Text_Messaging1]
-
-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.*
-
-image::media/SMS_Text_Messaging2.jpg[SMS_Text_Messaging2]
-
-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.
-+
-image::media/SMS_Text_Messaging3.jpg[SMS_Text_Messaging3]
-+
-. 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.
-
-image::media/SMS_Text_Messaging4.jpg[SMS_Text_Messaging4]
-
-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.
-+
-image::media/SMS_Text_Messaging5.jpg[SMS_Text_Messaging5]
-+
-. 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.
-
-image::media/SMS_Text_Messaging6.jpg[SMS_Text_Messaging6]
-
-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.
-+
-image::media/SMS_Text_Messaging12.jpg[SMS_Text_Messaging12]
-+
-. 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.*
-
-image::media/SMS_Text_Messaging13.jpg[SMS_Text_Messaging13]
-
-[[Sending_Copy_Details_via_Text_Message]]
-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,Administrative Setup>> for more information.
-+
-image::media/SMS_Text_Messaging7.jpg[SMS_Text_Messaging7]
-+
-. Search the catalog, and retrieve a title with copies.
-. Click the *Text* link next to the call number.
-+
-image::media/SMS_Text_Messaging8.png[Screenshot: Link to text copy details via SMS]
-+
-. The text of the SMS Text Message appears.
-+
-image::media/SMS_Text_Messaging9.png[Screenshot: Text message preview with submit form]
-+
-. 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.
-+
-image::media/SMS_Text_Messaging11.png[Screenshot: Confirmation page that SMS message was sent]
-
-*Permissions to use this Feature*
-
-ADMIN_SMS_CARRIER - Enables users to add/create/delete SMS Carrier entries.
-
-
--- /dev/null
+Acquisitions Administration
+---------------------------
+
+Acquisitions Settings
+~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,permissions]
+
+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
+
+Cancel/Delay reasons
+~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,purchase order,cancellation]
+indexterm:[acquisitions,line item,cancellation]
+
+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.
+
+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_.
+
+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.
+
+[TIP]
+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.
+
+
+Claiming
+~~~~~~~~
+
+indexterm:[acquisitions,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.
+
+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).
++
+[NOTE]
+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_.
+
+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).
++
+[NOTE]
+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_.
+
+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).
++
+[NOTE]
+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.
++
+[NOTE]
+Currently, all claims are initiated by a user. The ILS cannot automatically
+claim an issue.
++
+. Click _Save_.
+
+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_.
+
+[NOTE]
+You can create claim cycles by adding multiple claim policy actions to a claim
+ policy.
+
+Currency Types
+~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,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.
+
+
+
+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.
+
+
+
+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.
+
+[NOTE]
+From the currency types interface, you can delete currencies that have never
+been applied to funds or used to make purchases.
+
+Distribution Formulas
+~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,distribution formulas, templates]
+
+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.
+
+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).
++
+[NOTE]
+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.
+
+[NOTE]
+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.
+
+Edit a distribution formula
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To edit a distribution formula, click the hyperlinked title of the formula.
+
+Electronic Data Interchange
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+indexterm:[acquisitions,EDI,accounts]
+indexterm:[EDI,accounts]
+
+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 <<_setting_up_edi_acquisitions,EDI Installation Instructions>>
+because this is required for use of EDI.
+
+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.
+
+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.
++
+[NOTE]
+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_.
+
+image::media/enter-library-san-2.png[Enter Library SAN]
+
+
+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.
+
+image::media/enter-provider-san-1.png[Enter Provider SAN]
+
+. Enter your provider's SAN in the field labeled _SAN_.
+. Click _Save_.
+
+image::media/enter-provider-san-2.png[Enter Provider SAN]
+
+Create an EDI Account
+^^^^^^^^^^^^^^^^^^^^^
+
+CAUTION: 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.
+
+image::media/create-edi-accounts-2.png[Create EDI Account]
+
+. 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.
++
+[TIP]
+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.
++
+[NOTE]
+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.
++
+image::media/create-edi-accounts-3.png[Create EDI Account]
+
+. Click _Save_.
+. Click on the link in the _Provider_ field.
+
+image::media/create-edi-accounts-4.png[Create EDI Account]
+
+. Select the EDI account that has just been created from the _EDI Default_ drop down menu.
+
+image::media/create-edi-accounts-5.png[Create EDI Account]
+
+. Click _Save_.
+
+EDI Messages
+^^^^^^^^^^^^
+
+indexterm:[EDI,messages]
+indexterm:[acquisitions,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_).
+
+Exchange Rates
+~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,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.
+
+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_.
+
+Edit an exchange rate
+^^^^^^^^^^^^^^^^^^^^^
+
+Edit an exchange rate just as you would edit a currency type.
+
+MARC Federated Search
+~~~~~~~~~~~~~~~~~~~~~
+
+
+indexterm:[acquisitions,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.
++
+image::media/acq_marc_search.png[search form]
++
+. A list of results will appear. Click the _Copies_ link to add copy information
+to the line item. See <<line_item_features, 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, 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_.
+
+image::media/acq_marc_search-2.png[line item]
+
+Fund Tags
+~~~~~~~~~
+
+indexterm:[acquisitions,funds,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).
++
+[NOTE]
+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_.
+
+Funding Sources
+~~~~~~~~~~~~~~~
+
+indexterm:[acquisitions,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.
+
+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).
++
+[NOTE]
+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_.
+
+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_.
+
+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_.
+
+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.
+
+Funds
+~~~~~
+
+indexterm:[acquisitions,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.
+
+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).
++
+[NOTE]
+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_.
+
+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_.
+
+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_.
+
+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.
+
+
+Fund reporting
+^^^^^^^^^^^^^^
+
+indexterm:[acquisitions,funds,reports]
+indexterm:[reports,funds]
+
+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.
+
+
+image::media/Core_Source_1.jpg[Core_Source1]
+
+
+
+Edit a fund
+^^^^^^^^^^^
+
+Edit a fund just as you would edit a currency type.
+
+Perform fiscal year close-out operation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[acquisitions,funds,fiscal rollover]
+
+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_.
++
+[NOTE]
+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_.
++
+image::media/Fiscal_Rollover1.jpg[Fiscal_Rollover1]
+
+. 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.
+
+Invoice menus
+~~~~~~~~~~~~~
+
+indexterm:[acquisitions,invoices]
+
+Invoice menus allow you to create drop-down menus that appear on invoices. You
+can create an invoice item type or invoice payment method.
+
+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_.
+
+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.
+
+Line Item Features
+~~~~~~~~~~~~~~~~~~
+[[line_item_features]]
+
+indexterm:[acquisitions,line items]
+
+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.
+
+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_.
+
+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.
+
+Providers
+~~~~~~~~~
+
+Providers are vendors. You can create a provider profile that includes contact
+information for the provider, holdings information, invoices, and other
+information.
+
+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).
++
+[NOTE]
+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.
+
+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.
++
+[NOTE]
+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.
+
+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.
+
+++ /dev/null
-Acquisitions Administration
----------------------------
-
-Acquisitions Settings
-~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,permissions]
-
-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
-
-Cancel/Delay reasons
-~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,purchase order,cancellation]
-indexterm:[acquisitions,line item,cancellation]
-
-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.
-
-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_.
-
-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.
-
-[TIP]
-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.
-
-
-Claiming
-~~~~~~~~
-
-indexterm:[acquisitions,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.
-
-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).
-+
-[NOTE]
-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_.
-
-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).
-+
-[NOTE]
-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_.
-
-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).
-+
-[NOTE]
-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.
-+
-[NOTE]
-Currently, all claims are initiated by a user. The ILS cannot automatically
-claim an issue.
-+
-. Click _Save_.
-
-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_.
-
-[NOTE]
-You can create claim cycles by adding multiple claim policy actions to a claim
- policy.
-
-Currency Types
-~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,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.
-
-
-
-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.
-
-
-
-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.
-
-[NOTE]
-From the currency types interface, you can delete currencies that have never
-been applied to funds or used to make purchases.
-
-Distribution Formulas
-~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,distribution formulas, templates]
-
-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.
-
-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).
-+
-[NOTE]
-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.
-
-[NOTE]
-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.
-
-Edit a distribution formula
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To edit a distribution formula, click the hyperlinked title of the formula.
-
-Electronic Data Interchange
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-indexterm:[acquisitions,EDI,accounts]
-indexterm:[EDI,accounts]
-
-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 <<_setting_up_edi_acquisitions,EDI Installation Instructions>>
-because this is required for use of EDI.
-
-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.
-
-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.
-+
-[NOTE]
-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_.
-
-image::media/enter-library-san-2.png[Enter Library SAN]
-
-
-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.
-
-image::media/enter-provider-san-1.png[Enter Provider SAN]
-
-. Enter your provider's SAN in the field labeled _SAN_.
-. Click _Save_.
-
-image::media/enter-provider-san-2.png[Enter Provider SAN]
-
-Create an EDI Account
-^^^^^^^^^^^^^^^^^^^^^
-
-CAUTION: 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.
-
-image::media/create-edi-accounts-2.png[Create EDI Account]
-
-. 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.
-+
-[TIP]
-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.
-+
-[NOTE]
-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.
-+
-image::media/create-edi-accounts-3.png[Create EDI Account]
-
-. Click _Save_.
-. Click on the link in the _Provider_ field.
-
-image::media/create-edi-accounts-4.png[Create EDI Account]
-
-. Select the EDI account that has just been created from the _EDI Default_ drop down menu.
-
-image::media/create-edi-accounts-5.png[Create EDI Account]
-
-. Click _Save_.
-
-EDI Messages
-^^^^^^^^^^^^
-
-indexterm:[EDI,messages]
-indexterm:[acquisitions,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_).
-
-Exchange Rates
-~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,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.
-
-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_.
-
-Edit an exchange rate
-^^^^^^^^^^^^^^^^^^^^^
-
-Edit an exchange rate just as you would edit a currency type.
-
-MARC Federated Search
-~~~~~~~~~~~~~~~~~~~~~
-
-
-indexterm:[acquisitions,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.
-+
-image::media/acq_marc_search.png[search form]
-+
-. A list of results will appear. Click the _Copies_ link to add copy information
-to the line item. See <<line_item_features, 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, 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_.
-
-image::media/acq_marc_search-2.png[line item]
-
-Fund Tags
-~~~~~~~~~
-
-indexterm:[acquisitions,funds,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).
-+
-[NOTE]
-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_.
-
-Funding Sources
-~~~~~~~~~~~~~~~
-
-indexterm:[acquisitions,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.
-
-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).
-+
-[NOTE]
-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_.
-
-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_.
-
-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_.
-
-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.
-
-Funds
-~~~~~
-
-indexterm:[acquisitions,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.
-
-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).
-+
-[NOTE]
-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_.
-
-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_.
-
-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_.
-
-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.
-
-
-Fund reporting
-^^^^^^^^^^^^^^
-
-indexterm:[acquisitions,funds,reports]
-indexterm:[reports,funds]
-
-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.
-
-
-image::media/Core_Source_1.jpg[Core_Source1]
-
-
-
-Edit a fund
-^^^^^^^^^^^
-
-Edit a fund just as you would edit a currency type.
-
-Perform fiscal year close-out operation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[acquisitions,funds,fiscal rollover]
-
-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_.
-+
-[NOTE]
-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_.
-+
-image::media/Fiscal_Rollover1.jpg[Fiscal_Rollover1]
-
-. 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.
-
-Invoice menus
-~~~~~~~~~~~~~
-
-indexterm:[acquisitions,invoices]
-
-Invoice menus allow you to create drop-down menus that appear on invoices. You
-can create an invoice item type or invoice payment method.
-
-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_.
-
-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.
-
-Line Item Features
-~~~~~~~~~~~~~~~~~~
-[[line_item_features]]
-
-indexterm:[acquisitions,line items]
-
-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.
-
-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_.
-
-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.
-
-Providers
-~~~~~~~~~
-
-Providers are vendors. You can create a provider profile that includes contact
-information for the provider, holdings information, invoices, and other
-information.
-
-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).
-+
-[NOTE]
-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.
-
-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.
-+
-[NOTE]
-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.
-
-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.
-
--- /dev/null
+Notifications / Action Triggers
+-------------------------------
+
+indexterm:[action triggers, event definitions, notifications]
+
+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*.
+
+[NOTE]
+==========
+You must have Local Administrator permissions to access the Action Triggers module.
+==========
+
+You will notice four tabs on this page: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.
+
+
+anchor:event_definitions[]
+
+Event Definitions
+~~~~~~~~~~~~~~~~~
+
+Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:
+
+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, Validators>> and/or <<reactors, Reactors>> for processing.
+| <<hooks, 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.
+| <<reactors, Reactor>> |Links the action trigger to the Reactor.
+| <<validators, 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.
+|===============================================
+
+
+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.
+
+[TIP]
+=========
+A quick and easy way to create new action triggers is to clone an existing action trigger.
+=========
+
+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_.
+
+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.
+
+[NOTE]
+============
+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.
+============
+
+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.
+
+
+anchor:hooks[]
+
+Hooks
+^^^^^
+Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions ``hang''.
+
+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.
+
+
+anchor:reactors[]
+
+Reactors
+^^^^^^^^
+
+Reactors link the trigger definition to the action to be carried out.
+
+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.
+
+
+anchor:validators[]
+
+Validators
+^^^^^^^^^^
+
+Validators set the validation test to be preformed to determine whether the action trigger is executed.
+
+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.
+
+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
+----
+++ /dev/null
-Notifications / Action Triggers
--------------------------------
-
-indexterm:[action triggers, event definitions, notifications]
-
-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*.
-
-[NOTE]
-==========
-You must have Local Administrator permissions to access the Action Triggers module.
-==========
-
-You will notice four tabs on this page: <<event_definitions, Event Definitions>>, <<hooks, Hooks>>, <<reactors, Reactors>> and <<validators, Validators>>.
-
-
-anchor:event_definitions[]
-
-Event Definitions
-~~~~~~~~~~~~~~~~~
-
-Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:
-
-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, Validators>> and/or <<reactors, Reactors>> for processing.
-| <<hooks, 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.
-| <<reactors, Reactor>> |Links the action trigger to the Reactor.
-| <<validators, 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.
-|===============================================
-
-
-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.
-
-[TIP]
-=========
-A quick and easy way to create new action triggers is to clone an existing action trigger.
-=========
-
-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_.
-
-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.
-
-[NOTE]
-============
-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.
-============
-
-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.
-
-
-anchor:hooks[]
-
-Hooks
-^^^^^
-Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions ``hang''.
-
-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.
-
-
-anchor:reactors[]
-
-Reactors
-^^^^^^^^
-
-Reactors link the trigger definition to the action to be carried out.
-
-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.
-
-
-anchor:validators[]
-
-Validators
-^^^^^^^^^^
-
-Validators set the validation test to be preformed to determine whether the action trigger is executed.
-
-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.
-
-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
-----
--- /dev/null
+Age hold protection
+-------------------
+indexterm:[Holds]
+indexterm:[Holds, Age 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.
+
+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.
\ No newline at end of file
+++ /dev/null
-Age hold protection
--------------------
-indexterm:[Holds]
-indexterm:[Holds, Age 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.
-
-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.
\ No newline at end of file
--- /dev/null
+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:
+
+[source,conf]
+----
+<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.
+
+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
+
+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:
+
+[source,conf]
+----
+<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.
+++ /dev/null
-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:
-
-[source,conf]
-----
-<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.
-
-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
-
-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:
-
-[source,conf]
-----
-<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.
--- /dev/null
+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.
+
+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.
+
+[source,conf]
+----
+# 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]
+----
+
+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.
+
+[source,conf]
+----
+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
+[source,html]
+----
+[% 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
+[source,conf]
+----
+# 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
+[source,txt]
+----
+# 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
+[source,conf]
+----
+# 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
+[source,txt]
+----
+# Note that we cannot have spaces in the "value", so instead   is used. is also an option.
+BRANCH1 Branch One
+BRANCH2 Branch Two
+BRANCH3 Branch Three
+CONS Example Consortium Name
+----
+
+.Contents of liburl.txt File
+[source,txt]
+----
+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
+[source,conf]
+----
+# 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
+[source,txt]
+----
+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
+[source,conf]
+----
+# 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.
+
+++ /dev/null
-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.
-
-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.
-
-[source,conf]
-----
-# 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]
-----
-
-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.
-
-[source,conf]
-----
-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
-[source,html]
-----
-[% 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
-[source,conf]
-----
-# 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
-[source,txt]
-----
-# 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
-[source,conf]
-----
-# 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
-[source,txt]
-----
-# Note that we cannot have spaces in the "value", so instead   is used. is also an option.
-BRANCH1 Branch One
-BRANCH2 Branch Two
-BRANCH3 Branch Three
-CONS Example Consortium Name
-----
-
-.Contents of liburl.txt File
-[source,txt]
-----
-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
-[source,conf]
-----
-# 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
-[source,txt]
-----
-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
-[source,conf]
-----
-# 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.
-
--- /dev/null
+Authentication Proxy
+--------------------
+
+indexterm:[authentication, proxy]
+
+indexterm:[authentication, LDAP]
+
+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:
++
+[source,xml]
+----
+
+<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.
+
+[TIP]
+====================================================================
+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_*.
+====================================================================
+++ /dev/null
-Authentication Proxy
---------------------
-
-indexterm:[authentication, proxy]
-
-indexterm:[authentication, LDAP]
-
-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:
-+
-[source,xml]
-----
-
-<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.
-
-[TIP]
-====================================================================
-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_*.
-====================================================================
--- /dev/null
+Authorities
+-----------
+
+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*.
+
+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*.
+
+image::media/Authority_Control_Sets1.jpg[Authority_Control_Sets1]
+
+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*.
+
+
+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.
+
+image::media/Authority_Control_Sets2.jpg[Authority_Control_Sets2]
+
+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.
+
+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*.
++
+image::media/Authority_Control_Sets3.jpg[Authority_Control_Sets3]
++
+. 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*.
+
+image::media/Authority_Control_Sets4.jpg[Authority_Control_Sets4]
+
+
+
+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.
+
+
+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.
++
+image::media/Authority_Control_Sets5.jpg[Authority_Control_Sets5]
+. 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*.
+
+image::media/Authority_Control_Sets6.jpg[Authority_Control_Sets6]
+
+
+*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
+
+++ /dev/null
-Authorities
------------
-
-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*.
-
-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*.
-
-image::media/Authority_Control_Sets1.jpg[Authority_Control_Sets1]
-
-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*.
-
-
-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.
-
-image::media/Authority_Control_Sets2.jpg[Authority_Control_Sets2]
-
-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.
-
-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*.
-+
-image::media/Authority_Control_Sets3.jpg[Authority_Control_Sets3]
-+
-. 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*.
-
-image::media/Authority_Control_Sets4.jpg[Authority_Control_Sets4]
-
-
-
-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.
-
-
-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.
-+
-image::media/Authority_Control_Sets5.jpg[Authority_Control_Sets5]
-. 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*.
-
-image::media/Authority_Control_Sets6.jpg[Authority_Control_Sets6]
-
-
-*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
-
--- /dev/null
+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.
+
+
+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.
++
+note: 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.*
+
+image::media/Auto_Suggest_in_Catalog_Search2.jpg[Auto_Suggest_in_Catalog_Search2]
+
+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.
+
+image::media/Auto_Suggest_in_Catalog_Search1.jpg[Auto_Suggest_in_Catalog_Search1]
+
+++ /dev/null
-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.
-
-
-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.
-+
-note: 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.*
-
-image::media/Auto_Suggest_in_Catalog_Search2.jpg[Auto_Suggest_in_Catalog_Search2]
-
-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.
-
-image::media/Auto_Suggest_in_Catalog_Search1.jpg[Auto_Suggest_in_Catalog_Search1]
-
--- /dev/null
+Booking Module Administration
+-----------------------------
+
+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.
+
+Create New Resource Type
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+1) Select Admin --> Server Administration --> Booking --> Resource Types.
+
+image::media/booking-create-resourcetype-1.png[]
+
+2) A list of current resource types will appear. Use Back and Next buttons to browse the whole list.
+
+image::media/booking-create-resourcetype-2.png[]
+
+[NOTE]
+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, .
+
+image::media/booking-create-resourcetype-3.png[]
+
+4) A box will appear in which you create your new type of resource.
+
+image::media/booking-create-bookable-1.png[]
+
+* Resource Type Name - Give your resource a name.
+* Fine Interval - How often will fines be charged? This period can be input in several ways:
+
+[NOTE]
+====================================================================
+** 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.
+
+image::media/booking-create-resourcetype-4.png[]
+
+6) The new resource type will appear in the list.
+
+image::media/booking-create-resourcetype-5.png[]
+
+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.
+
+image::media/booking-create-bookable-2.png[]
+
+* 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.
+
+[NOTE]
+One resource type may have multiple attributes. You may repeat the above procedure to add more.
+
+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.
+
+image::media/booking-create-bookable-3.png[]
+
+* 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.
+
+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.
+
+image::media/booking-create-bookable-4.png[]
+
+* 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.
+
+[NOTE]
+One resource type may have multiple resources attached.
+
+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.
+
+image::media/booking-create-bookable-5.png[]
+
+* 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.
+
+[NOTE]
+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.
+
+image::media/booking-create-bookable-6.png[]
+
+
+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.
+
+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.
+
+
+
+
+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.
+
+
+
+
+++ /dev/null
-Booking Module Administration
------------------------------
-
-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.
-
-Create New Resource Type
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-1) Select Admin --> Server Administration --> Booking --> Resource Types.
-
-image::media/booking-create-resourcetype-1.png[]
-
-2) A list of current resource types will appear. Use Back and Next buttons to browse the whole list.
-
-image::media/booking-create-resourcetype-2.png[]
-
-[NOTE]
-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, .
-
-image::media/booking-create-resourcetype-3.png[]
-
-4) A box will appear in which you create your new type of resource.
-
-image::media/booking-create-bookable-1.png[]
-
-* Resource Type Name - Give your resource a name.
-* Fine Interval - How often will fines be charged? This period can be input in several ways:
-
-[NOTE]
-====================================================================
-** 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.
-
-image::media/booking-create-resourcetype-4.png[]
-
-6) The new resource type will appear in the list.
-
-image::media/booking-create-resourcetype-5.png[]
-
-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.
-
-image::media/booking-create-bookable-2.png[]
-
-* 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.
-
-[NOTE]
-One resource type may have multiple attributes. You may repeat the above procedure to add more.
-
-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.
-
-image::media/booking-create-bookable-3.png[]
-
-* 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.
-
-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.
-
-image::media/booking-create-bookable-4.png[]
-
-* 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.
-
-[NOTE]
-One resource type may have multiple resources attached.
-
-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.
-
-image::media/booking-create-bookable-5.png[]
-
-* 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.
-
-[NOTE]
-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.
-
-image::media/booking-create-bookable-6.png[]
-
-
-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.
-
-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.
-
-
-
-
-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.
-
-
-
-
--- /dev/null
+Circulation Limit Sets
+----------------------
+
+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*.
+
+image::media/Maximum_Checkout_by_Copy_Location1.jpg[Maximum_Checkout_by_Copy_Location1]
+
+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*.
+
+image::media/Maximum_Checkout_by_Copy_Location2.jpg[Maximum_Checkout_by_Copy_Location2]
+++ /dev/null
-Circulation Limit Sets
-----------------------
-
-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*.
-
-image::media/Maximum_Checkout_by_Copy_Location1.jpg[Maximum_Checkout_by_Copy_Location1]
-
-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*.
-
-image::media/Maximum_Checkout_by_Copy_Location2.jpg[Maximum_Checkout_by_Copy_Location2]
--- /dev/null
+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.
+
+
+Configure call number prefixes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Call number prefixes are codes that precede a call number.
+
+To configure call number prefixes:
+
+1. Select *Admin -> Server Administration -> Call Number Prefixes*.
+2. Click *New Prefix*.
+3. Enter the *call number label* that will appear on the item.
+4. 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.
+5. Click *Save*.
+
+
+
+image::media/Call_Number_Prefixes_and_Suffixes_2_21.jpg[Call_Number_Prefixes_and_Suffixes_2_21]
+
+
+
+Configure call number suffixes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Call number suffixes are codes that succeed a call number.
+
+To configure call number suffixes:
+
+1. Select *Admin -> Server Administration -> Call Number Suffixes*.
+2. Click *New Suffix*.
+3. Enter the *call number label* that will appear on the item.
+4. 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.
+5. Click *Save*.
+
+
+image::media/Call_Number_Prefixes_and_Suffixes_2_22.jpg[Call_Number_Prefixes_and_Suffixes_2_22]
+
+
+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.
+++ /dev/null
-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.
-
-
-Configure call number prefixes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Call number prefixes are codes that precede a call number.
-
-To configure call number prefixes:
-
-1. Select *Admin -> Server Administration -> Call Number Prefixes*.
-2. Click *New Prefix*.
-3. Enter the *call number label* that will appear on the item.
-4. 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.
-5. Click *Save*.
-
-
-
-image::media/Call_Number_Prefixes_and_Suffixes_2_21.jpg[Call_Number_Prefixes_and_Suffixes_2_21]
-
-
-
-Configure call number suffixes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Call number suffixes are codes that succeed a call number.
-
-To configure call number suffixes:
-
-1. Select *Admin -> Server Administration -> Call Number Suffixes*.
-2. Click *New Suffix*.
-3. Enter the *call number label* that will appear on the item.
-4. 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.
-5. Click *Save*.
-
-
-image::media/Call_Number_Prefixes_and_Suffixes_2_22.jpg[Call_Number_Prefixes_and_Suffixes_2_22]
-
-
-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.
--- /dev/null
+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.
+
+.Stock copy statuses and default settings
+[options="header"]
+|==============================================
+|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
+|==============================================
+
+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.
+
+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.
+
+[NOTE]
+You will not be able to delete statuses if copies currently exist with that
+status.
+
+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.
+++ /dev/null
-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.
-
-.Stock copy statuses and default settings
-[options="header"]
-|==============================================
-|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
-|==============================================
-
-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.
-
-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.
-
-[NOTE]
-You will not be able to delete statuses if copies currently exist with that
-status.
-
-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.
--- /dev/null
+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).
+
+Configure Toolbar
+~~~~~~~~~~~~~~~~~
+
+. Click *Admin* -> *Workstation Administration* -> *Toolbars* -> *Configure
+Toolbars*.
+
+. Click *New Toolbar*.
+
+. Enter label for toolbar.
++
+image::media/Customizable_Toolbar1.jpg[Customizable_Toolbar1]
++
+. 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.
++
+image::media/Customizable_Toolbar2.jpg[Customizable_Toolbar2]
++
+. 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)`.
++
+image::media/Customizable_Toolbar3.jpg[Customizable_Toolbar3]
++
+. To add a dividing line between buttons that appear on the same side of the
+screen, select *toolbarseparator*, and click `--> (A)`.
++
+image::media/Customizable_Toolbar4.jpg[Customizable_Toolbar4]
++
+. 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
+++ /dev/null
-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).
-
-Configure Toolbar
-~~~~~~~~~~~~~~~~~
-
-. Click *Admin* -> *Workstation Administration* -> *Toolbars* -> *Configure
-Toolbars*.
-
-. Click *New Toolbar*.
-
-. Enter label for toolbar.
-+
-image::media/Customizable_Toolbar1.jpg[Customizable_Toolbar1]
-+
-. 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.
-+
-image::media/Customizable_Toolbar2.jpg[Customizable_Toolbar2]
-+
-. 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)`.
-+
-image::media/Customizable_Toolbar3.jpg[Customizable_Toolbar3]
-+
-. To add a dividing line between buttons that appear on the same side of the
-screen, select *toolbarseparator*, and click `--> (A)`.
-+
-image::media/Customizable_Toolbar4.jpg[Customizable_Toolbar4]
-+
-. 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
--- /dev/null
+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.
+
+== 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.
+
+== 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.
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+== Examples
+
+=== 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
+
+=== 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
+
+=== 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
+
+=== 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
+
+=== 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
+
+=== 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.
+
+=== 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
+++ /dev/null
-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.
-
-== 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.
-
-== 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.
-
-=== 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.
-
-=== 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.
-
-=== 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.
-
-=== 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.
-
-== Examples
-
-=== 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
-
-=== 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
-
-=== 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
-
-=== 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
-
-=== 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
-
-=== 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.
-
-=== 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
--- /dev/null
+Hold-driven recalls
+===================
+
+indexterm:[hold-driven recalls]
+indexterm:[circulation, recalls, hold-driven]
+
+_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
+
+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.
+
+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*.
+++ /dev/null
-Hold-driven recalls
-===================
-
-indexterm:[hold-driven recalls]
-indexterm:[circulation, recalls, hold-driven]
-
-_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
-
-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.
-
-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*.
--- /dev/null
+Address Alert
+-------------
+
+indexterm:[address alerts]
+
+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*.
+
+[NOTE]
+==========
+You must have Local Administrator permissions or ADMIN_ADDRESS_ALERT permission to access the Address Alert module.
+==========
+
+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.
+
+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.
+
+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:
++
+.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.
+
+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.
+
+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.
+
+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.
+
+image::media/lsa-address_alert_staff_view.png[Address Alert Staff View]
+
+Regular Expressions / Wildcards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All of the patterns entered to match the various address fields are evaluated as case-insensitive regular expressions by default.
+
+[NOTE]
+==========
+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.
+
+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)"
+
+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
+++ /dev/null
-Address Alert
--------------
-
-indexterm:[address alerts]
-
-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*.
-
-[NOTE]
-==========
-You must have Local Administrator permissions or ADMIN_ADDRESS_ALERT permission to access the Address Alert module.
-==========
-
-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.
-
-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.
-
-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:
-+
-.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.
-
-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.
-
-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.
-
-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.
-
-image::media/lsa-address_alert_staff_view.png[Address Alert Staff View]
-
-Regular Expressions / Wildcards
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-All of the patterns entered to match the various address fields are evaluated as case-insensitive regular expressions by default.
-
-[NOTE]
-==========
-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.
-
-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)"
-
-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
--- /dev/null
+Barcode Completion
+------------------
+
+indexterm:[Barcode Completion,Lazy Circ]
+
+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
+
+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.
+
+
+Access Points
+~~~~~~~~~~~~~
+
+The admin interface for Barcode Completion is located under *Admin*
+-> *Local Administration* -> *Barcode Completion*.
+
+image::media/lsa-barcode_completion_admin.png[Barcode Completion Admin]
+
+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.
+
+NOTE: Barcode Completion does not work in the
+ *Search for Patron [by Name]* interface.
+
+image::media/lsa-barcode_completion_accesspoints.png[Barcode Completion Access Points]
+
+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.
+
+image::media/lsa-barcode_completion_multiple.png[Barcode Completion Multiple Matches]
+
+Barcode Completion Data Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following data fields can be set for each Barcode Completion rule.
+
+.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.
+
+image::media/lsa-barcode_completion_fields.png[Barcode Completion Data Fields]
+
+Create, Update, Filter, Delete/Disable Rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+image::media/lsa-barcode_completion_admin.png[Barcode Completion Admin]
+
+In the Barcode Completion admin interface at *Admin* -> *Local Administration*
+-> *Barcode Completion* you can create, update and disable rules.
+
+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.
+
+Update Rules
+^^^^^^^^^^^^
+To edit a rule double click on the rule in the main list.
+
+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*.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+
+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.
+++ /dev/null
-Barcode Completion
-------------------
-
-indexterm:[Barcode Completion,Lazy Circ]
-
-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
-
-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.
-
-
-Access Points
-~~~~~~~~~~~~~
-
-The admin interface for Barcode Completion is located under *Admin*
--> *Local Administration* -> *Barcode Completion*.
-
-image::media/lsa-barcode_completion_admin.png[Barcode Completion Admin]
-
-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.
-
-NOTE: Barcode Completion does not work in the
- *Search for Patron [by Name]* interface.
-
-image::media/lsa-barcode_completion_accesspoints.png[Barcode Completion Access Points]
-
-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.
-
-image::media/lsa-barcode_completion_multiple.png[Barcode Completion Multiple Matches]
-
-Barcode Completion Data Fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following data fields can be set for each Barcode Completion rule.
-
-.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.
-
-image::media/lsa-barcode_completion_fields.png[Barcode Completion Data Fields]
-
-Create, Update, Filter, Delete/Disable Rules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-image::media/lsa-barcode_completion_admin.png[Barcode Completion Admin]
-
-In the Barcode Completion admin interface at *Admin* -> *Local Administration*
--> *Barcode Completion* you can create, update and disable rules.
-
-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.
-
-Update Rules
-^^^^^^^^^^^^
-To edit a rule double click on the rule in the main list.
-
-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*.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-
-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.
--- /dev/null
+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.
+
+++ /dev/null
-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.
-
--- /dev/null
+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.
+
+1. Click *Admin -> Local Administration -> Statistical Categories Editor.*
+
+2. 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:
+
+image::media/lsa-statcat-1.png[Create copy stat cat]
+
+* _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:
+
+image::media/lsa-statcat-2.png[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_:
+
+image::media/lsa-statcat-3.png[Stat cats in 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:
+
+image::media/lsa-statcat-4.png[Create patron stat cat]
+
+* _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:
+
+image::media/lsa-statcat-5.png[Sample patron stat cats]
+
+To add an entry, click on _Add_ in the category row under the _Add Entry_ column:
+
+image::media/lsa-statcat-6.png[Add patron category entry]
+
+To edit an entry, select the entry you wish to edit from the drop-down list for the category:
+
+image::media/lsa-statcat-7.png[Edit patron category entry]
+
+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:
+
+image::media/lsa-statcat-8.png[Patron stat cats in registration screen]
+
+++ /dev/null
-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.
-
-1. Click *Admin -> Local Administration -> Statistical Categories Editor.*
-
-2. 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:
-
-image::media/lsa-statcat-1.png[Create copy stat cat]
-
-* _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:
-
-image::media/lsa-statcat-2.png[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_:
-
-image::media/lsa-statcat-3.png[Stat cats in 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:
-
-image::media/lsa-statcat-4.png[Create patron stat cat]
-
-* _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:
-
-image::media/lsa-statcat-5.png[Sample patron stat cats]
-
-To add an entry, click on _Add_ in the category row under the _Add Entry_ column:
-
-image::media/lsa-statcat-6.png[Add patron category entry]
-
-To edit an entry, select the entry you wish to edit from the drop-down list for the category:
-
-image::media/lsa-statcat-7.png[Edit patron category entry]
-
-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:
-
-image::media/lsa-statcat-8.png[Patron stat cats in registration screen]
-
--- /dev/null
+Work Log
+--------
+
+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.
+
+image::media/Expanding_the_Work_Log1.jpg[Expanding_the_Work_Log1]
+
+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.
+
+image::media/Expanding_the_Work_Log2.jpg[Expanding_the_Work_Log2]
+++ /dev/null
-Work Log
---------
-
-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.
-
-image::media/Expanding_the_Work_Log1.jpg[Expanding_the_Work_Log1]
-
-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.
-
-image::media/Expanding_the_Work_Log2.jpg[Expanding_the_Work_Log2]
--- /dev/null
+Patron Address City/State/County Pre-Populate by ZIP Code
+---------------------------------------------------------
+
+indexterm:[zips.txt, Populate Address by ZIP Code, 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.
+
+
+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.
+
+Setup Steps
+~~~~~~~~~~~
+
+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.
+
+TIP: The <<_address_alert,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||
+----
+
+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.
+
+NOTE: The specific opensrf services you need to restart are "opensrf.setting" and "open-ils.search".
+
+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.
+
+ZIP Code Data
+~~~~~~~~~~~~~
+
+There are several methods you can use to populate your zips.txt with data.
+
+Manual Entry
+^^^^^^^^^^^^
+
+If you only have a few communities that you serve, entering data manually may be the simplest approach.
+
+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.
+
+[source,bash]
+----
+## 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
+----
+
+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.
+
+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.
+
+[source,bash]
+----
+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
+
+
+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
+++ /dev/null
-Patron Address City/State/County Pre-Populate by ZIP Code
----------------------------------------------------------
-
-indexterm:[zips.txt, Populate Address by ZIP Code, 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.
-
-
-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.
-
-Setup Steps
-~~~~~~~~~~~
-
-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.
-
-TIP: The <<_address_alert,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||
-----
-
-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.
-
-NOTE: The specific opensrf services you need to restart are "opensrf.setting" and "open-ils.search".
-
-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.
-
-ZIP Code Data
-~~~~~~~~~~~~~
-
-There are several methods you can use to populate your zips.txt with data.
-
-Manual Entry
-^^^^^^^^^^^^
-
-If you only have a few communities that you serve, entering data manually may be the simplest approach.
-
-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.
-
-[source,bash]
-----
-## 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
-----
-
-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.
-
-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.
-
-[source,bash]
-----
-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
-
-
-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
--- /dev/null
+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.
+
+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_.
++
+NOTE: In multi-branch libraries it is possible to assign more than one working
+location
+
+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.
+
+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.
++
+image::media/profile-5.png[profile-5]
++
+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_.
++
+image::media/profile-6.png[profile-6]
++
+. Scroll down and click Save to apply the changes.
++
+image::media/profile-7.png[profile-7]
+
+
+
+++ /dev/null
-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.
-
-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_.
-+
-NOTE: In multi-branch libraries it is possible to assign more than one working
-location
-
-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.
-
-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.
-+
-image::media/profile-5.png[profile-5]
-+
-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_.
-+
-image::media/profile-6.png[profile-6]
-+
-. Scroll down and click Save to apply the changes.
-+
-image::media/profile-7.png[profile-7]
-
-
-
--- /dev/null
+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.
+
+.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.
+
+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.
+
+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.
+
+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, Skipping
+patrons with email notification of holds>> as described below.
+
+
+.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.
+|=====================================
+
+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, Skipping patrons with
+email notification of holds>> as described below.
+
+.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.
+|=================================
+
+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.
+
+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.
+
+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.
+++ /dev/null
-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.
-
-.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.
-
-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.
-
-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.
-
-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, Skipping
-patrons with email notification of holds>> as described below.
-
-
-.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.
-|=====================================
-
-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, Skipping patrons with
-email notification of holds>> as described below.
-
-.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.
-|=================================
-
-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.
-
-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.
-
-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.
--- /dev/null
+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:
+
+1. Click *Admin -> Local Administration -> Library Settings Editor.*
+
+2. Scroll to *OPAC: Number of staff client saved searches to display on left side of results and record details pages*
+
+3. Click *Edit*.
+
+4. Select a *Context* from the drop down menu.
+
+5. Enter the number of searches that you wish to save in the *Value* field.
+
+6. Click *Update Setting*
+
+image::media/Saved_Catalog_Searches_2_21.jpg[Saved_Catalog_Searches_2_21]
+
+
+NOTE: 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:
+
+1. Follow steps 1-4 (one through four) as listed in the previous section.
+
+2. In the *value* field, enter 0 (zero).
+
+3. 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:
+
+1. Enter a search term in either the basic or advanced search fields.
+
+2. 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.
+
+image::media/Saved_Catalog_Searches_2_22.jpg[Saved_Catalog_Searches_2_22]
+++ /dev/null
-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:
-
-1. Click *Admin -> Local Administration -> Library Settings Editor.*
-
-2. Scroll to *OPAC: Number of staff client saved searches to display on left side of results and record details pages*
-
-3. Click *Edit*.
-
-4. Select a *Context* from the drop down menu.
-
-5. Enter the number of searches that you wish to save in the *Value* field.
-
-6. Click *Update Setting*
-
-image::media/Saved_Catalog_Searches_2_21.jpg[Saved_Catalog_Searches_2_21]
-
-
-NOTE: 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:
-
-1. Follow steps 1-4 (one through four) as listed in the previous section.
-
-2. In the *value* field, enter 0 (zero).
-
-3. 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:
-
-1. Enter a search term in either the basic or advanced search fields.
-
-2. 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.
-
-image::media/Saved_Catalog_Searches_2_22.jpg[Saved_Catalog_Searches_2_22]
--- /dev/null
+Z39.50 Servers
+--------------
+
+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.
+
+Administrative Settings
+^^^^^^^^^^^^^^^^^^^^^^^
+
+You can add a permission to limit use of Z39.50 servers, or you can use an existing permission.
+
+NOTE: 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.
+
+image::media/Restrict_Z39_50_Sources_by_Permission_Group1.jpg[]
+
+4) Click *Add*.
+
+5) The new permission appears in the list of permissions.
+
+
+
+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.
+
+image::media/Restrict_Z39_50_Sources_by_Permission_Group2.jpg[]
+
+4) Click *Save*.
+
+5) Add the permission that you created to a user or user group so that they can access the restricted server.
+
+
+image::media/Restrict_Z39_50_Sources_by_Permission_Group3.jpg[]
+
+6) Users that log in to the staff client and have that permission will be able to see the restricted Z39.50 server.
+
+NOTE: 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.
+
+
+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*.
+
+image::media/storing_z3950_credentials.jpg[Storing Z39.50 Credentials]
+++ /dev/null
-Z39.50 Servers
---------------
-
-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.
-
-Administrative Settings
-^^^^^^^^^^^^^^^^^^^^^^^
-
-You can add a permission to limit use of Z39.50 servers, or you can use an existing permission.
-
-NOTE: 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.
-
-image::media/Restrict_Z39_50_Sources_by_Permission_Group1.jpg[]
-
-4) Click *Add*.
-
-5) The new permission appears in the list of permissions.
-
-
-
-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.
-
-image::media/Restrict_Z39_50_Sources_by_Permission_Group2.jpg[]
-
-4) Click *Save*.
-
-5) Add the permission that you created to a user or user group so that they can access the restricted server.
-
-
-image::media/Restrict_Z39_50_Sources_by_Permission_Group3.jpg[]
-
-6) Users that log in to the staff client and have that permission will be able to see the restricted Z39.50 server.
-
-NOTE: 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.
-
-
-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*.
-
-image::media/storing_z3950_credentials.jpg[Storing Z39.50 Credentials]
--- /dev/null
+SIP Server
+----------
+
+indexterm:[Automated Circulation System]
+indexterm:[SelfCheck]
+indexterm:[Automated Material Handling]
+
++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
+
+Installing the SIP Server
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+This is a rough intro to installing the +SIP+ server for Evergreen.
+
+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
+
+
+Configuring the Server
+^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[configuration files, oils_sip.xml]
+
+. 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.
+
+Adding SIP Users
+^^^^^^^^^^^^^^^^
+
+indexterm:[configuration files, oils_sip.xml]
+
+. 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.
+
+[NOTE]
+===================
+The expiration date will affect the +SIP+ users' connection so you might want to make a note of this
+somewhere.
+===================
+
+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
+
+indexterm:[SIP]
+
+
+Logging-SIP
+^^^^^^^^^^^
+
+Syslog
+++++++
+
+indexterm:[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
+
+
+Syslog-NG
++++++++++
+
+indexterm:[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
+
+
+indexterm:[SIP]
+
+
+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.
+
+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.
+
+///////////////
+Comments because we don't want to indent these numbered bullets!
+///////////////
+
+. Start by testing your ability to log into the SIP server:
++
+[NOTE]
+======================
+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.
+
+indexterm:[SIP]
+
+SIP Communication
+~~~~~~~~~~~~~~~~~
+
+indexterm:[SIP Server, 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 |<<sip_01_block_patron, 01/Block_Patron>> - ACS responds with 24 Patron Status Response
+| 09-10 | Checkin | Yes (with extensions) |<<sip_09-10_checkin, 09/10_Checkin>>
+| 11-12 | Checkout | Yes (no renewals) |<<sip_11-12_checkout, 11/12_Checkout>>
+| 15-16 | Hold | Partially supported |<<sip_15-16_hold, 15/16_Hold>>
+| 17-18 | Item Information | Yes (no extensions) |<<sip_17-18_item_information, 17/18_Item_Information>>
+| 19-20 | Item Status Update | No |<<sip_19-20_item_status_update, 19/20_Item_Status_Update>> - Returns Patron Enable response, but doesn't make any changes in EG
+| 23-24 | Patron Status | Yes |<<sip_23-24_patron_status, 23/24_Patron_Status>> - 63/64 ``Patron Information'' preferred
+| 25-26 | Patron Enable | No |<<sip_25-26_patron_enable, 25/26_Patron_Enable>> - Used during system testing and validation
+| 29-30 | Renew | Yes |<<sip_29-30_renew, 29/30_Renew>>
+| 35-36 | End Session | Yes |<<sip_35-36_end_session, 35/36_End_Session>>
+| 37-38 | Fee Paid | Yes |<<sip_37-38_fee_paid, 37/38_Fee_Paid>>
+| 63-64 | Patron Information | Yes (no extensions) |<<sip_63-64_patron_information, 63/64_Patron_Information>>
+| 65-66 | Renew All | Yes |<<sip_65-66_renew_all, 65/66_Renew_All>>
+| 93-94 | Login | Yes |<<sip_93-94_login, 93/94_Login>> - Must be first command to Evergreen ACS (via socket) or +SIP+ will terminate
+| 97-96 | Resend last message | Yes |<<sip_97-96_resend, 97/96_Resend>>
+| 99-98 | SC-ACS Status | Yes |<<sip_99-98_sc_and_acs_status, 99/98_SC_and_ACS_Status>>
+|===========================================================================
+
+anchor:sip_01_block_patron[]
+
+01 Block Patron
+^^^^^^^^^^^^^^^
+
+indexterm:[SelfCheck]
+
+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, 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
+
+anchor:sip_09-10_checkin[]
+
+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, 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
+
+indexterm:[magnetic media]
+
+[NOTE]
+===============
+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).
+================
+
+anchor:sip_11-12_checkout[]
+
+11/12 Checkout
+^^^^^^^^^^^^^^
+
+
+anchor:sip_15-16_hold[]
+
+15/16 Hold
+^^^^^^^^^^
+
+Evergreen supports the Hold message for the purpose of canceling
+holds. It does not currently support creating hold requests via SIP2.
+
+
+anchor:sip_17-18_item_information[]
+
+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.
+
+indexterm:[Automated Material Handling (AMH)]
+
+EXTENSIONS: The CT field for _destination location_ and CS _call number_ are used by Automated Material Handling
+systems.
+
+
+anchor:sip_19-20_item_status_update[]
+
+19/20 Item Status Update
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+anchor:sip_23-24_patron_status[]
+
+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.
+
+
+anchor:sip_25-26_patron_enable[]
+
+25/26 Patron Enable
+^^^^^^^^^^^^^^^^^^^
+
+Not yet supported.
+
+
+anchor:sip_29-30_renew[]
+
+29/30 Renew
+^^^^^^^^^^^
+
+Evergreen supports the Renew message.
+
+
+anchor:sip_35-36_end_session[]
+
+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_.
+
+
+
+anchor:sip_37-38_fee_paid[]
+
+37/38 Fee Paid
+^^^^^^^^^^^^^^
+
+Evergreen supports the Fee Paid message.
+
+
+anchor:sip_63-64_patron_information[]
+
+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 <<sip_23-24_patron_status, 23/24 Patron Status>> for info on +BL+ and +CQ+ fields.
+
+
+
+anchor:sip_65-66_renew_all[]
+
+65/66 Renew All
+^^^^^^^^^^^^^^^
+
+Evergreen supports the Renew All message.
+
+
+anchor:sip_93-94_login[]
+
+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.
+
+
+anchor:sip_97-96_resend[]
+
+97/96 Resend
+^^^^^^^^^^^^
+
+
+anchor:sip_99-98_sc_and_acs_status[]
+
+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.
+
+
+anchor:fields[]
+
+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.
+++ /dev/null
-SIP Server
-----------
-
-indexterm:[Automated Circulation System]
-indexterm:[SelfCheck]
-indexterm:[Automated Material Handling]
-
-+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
-
-Installing the SIP Server
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-
-This is a rough intro to installing the +SIP+ server for Evergreen.
-
-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
-
-
-Configuring the Server
-^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[configuration files, oils_sip.xml]
-
-. 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.
-
-Adding SIP Users
-^^^^^^^^^^^^^^^^
-
-indexterm:[configuration files, oils_sip.xml]
-
-. 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.
-
-[NOTE]
-===================
-The expiration date will affect the +SIP+ users' connection so you might want to make a note of this
-somewhere.
-===================
-
-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
-
-indexterm:[SIP]
-
-
-Logging-SIP
-^^^^^^^^^^^
-
-Syslog
-++++++
-
-indexterm:[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
-
-
-Syslog-NG
-+++++++++
-
-indexterm:[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
-
-
-indexterm:[SIP]
-
-
-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.
-
-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.
-
-///////////////
-Comments because we don't want to indent these numbered bullets!
-///////////////
-
-. Start by testing your ability to log into the SIP server:
-+
-[NOTE]
-======================
-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.
-
-indexterm:[SIP]
-
-SIP Communication
-~~~~~~~~~~~~~~~~~
-
-indexterm:[SIP Server, 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 |<<sip_01_block_patron, 01/Block_Patron>> - ACS responds with 24 Patron Status Response
-| 09-10 | Checkin | Yes (with extensions) |<<sip_09-10_checkin, 09/10_Checkin>>
-| 11-12 | Checkout | Yes (no renewals) |<<sip_11-12_checkout, 11/12_Checkout>>
-| 15-16 | Hold | Partially supported |<<sip_15-16_hold, 15/16_Hold>>
-| 17-18 | Item Information | Yes (no extensions) |<<sip_17-18_item_information, 17/18_Item_Information>>
-| 19-20 | Item Status Update | No |<<sip_19-20_item_status_update, 19/20_Item_Status_Update>> - Returns Patron Enable response, but doesn't make any changes in EG
-| 23-24 | Patron Status | Yes |<<sip_23-24_patron_status, 23/24_Patron_Status>> - 63/64 ``Patron Information'' preferred
-| 25-26 | Patron Enable | No |<<sip_25-26_patron_enable, 25/26_Patron_Enable>> - Used during system testing and validation
-| 29-30 | Renew | Yes |<<sip_29-30_renew, 29/30_Renew>>
-| 35-36 | End Session | Yes |<<sip_35-36_end_session, 35/36_End_Session>>
-| 37-38 | Fee Paid | Yes |<<sip_37-38_fee_paid, 37/38_Fee_Paid>>
-| 63-64 | Patron Information | Yes (no extensions) |<<sip_63-64_patron_information, 63/64_Patron_Information>>
-| 65-66 | Renew All | Yes |<<sip_65-66_renew_all, 65/66_Renew_All>>
-| 93-94 | Login | Yes |<<sip_93-94_login, 93/94_Login>> - Must be first command to Evergreen ACS (via socket) or +SIP+ will terminate
-| 97-96 | Resend last message | Yes |<<sip_97-96_resend, 97/96_Resend>>
-| 99-98 | SC-ACS Status | Yes |<<sip_99-98_sc_and_acs_status, 99/98_SC_and_ACS_Status>>
-|===========================================================================
-
-anchor:sip_01_block_patron[]
-
-01 Block Patron
-^^^^^^^^^^^^^^^
-
-indexterm:[SelfCheck]
-
-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, 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
-
-anchor:sip_09-10_checkin[]
-
-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, 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
-
-indexterm:[magnetic media]
-
-[NOTE]
-===============
-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).
-================
-
-anchor:sip_11-12_checkout[]
-
-11/12 Checkout
-^^^^^^^^^^^^^^
-
-
-anchor:sip_15-16_hold[]
-
-15/16 Hold
-^^^^^^^^^^
-
-Evergreen supports the Hold message for the purpose of canceling
-holds. It does not currently support creating hold requests via SIP2.
-
-
-anchor:sip_17-18_item_information[]
-
-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.
-
-indexterm:[Automated Material Handling (AMH)]
-
-EXTENSIONS: The CT field for _destination location_ and CS _call number_ are used by Automated Material Handling
-systems.
-
-
-anchor:sip_19-20_item_status_update[]
-
-19/20 Item Status Update
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-anchor:sip_23-24_patron_status[]
-
-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.
-
-
-anchor:sip_25-26_patron_enable[]
-
-25/26 Patron Enable
-^^^^^^^^^^^^^^^^^^^
-
-Not yet supported.
-
-
-anchor:sip_29-30_renew[]
-
-29/30 Renew
-^^^^^^^^^^^
-
-Evergreen supports the Renew message.
-
-
-anchor:sip_35-36_end_session[]
-
-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_.
-
-
-
-anchor:sip_37-38_fee_paid[]
-
-37/38 Fee Paid
-^^^^^^^^^^^^^^
-
-Evergreen supports the Fee Paid message.
-
-
-anchor:sip_63-64_patron_information[]
-
-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 <<sip_23-24_patron_status, 23/24 Patron Status>> for info on +BL+ and +CQ+ fields.
-
-
-
-anchor:sip_65-66_renew_all[]
-
-65/66 Renew All
-^^^^^^^^^^^^^^^
-
-Evergreen supports the Renew All message.
-
-
-anchor:sip_93-94_login[]
-
-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.
-
-
-anchor:sip_97-96_resend[]
-
-97/96 Resend
-^^^^^^^^^^^^
-
-
-anchor:sip_99-98_sc_and_acs_status[]
-
-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.
-
-
-anchor:fields[]
-
-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.
--- /dev/null
+Button Bar/Toolbar
+------------------
+
+indexterm:[staff client, button bar]
+indexterm:[staff client, toolbar]
+
+There is an optional toolbar with buttons providing quick access to commonly
+used staff client functions. When activated the toolbar appears below the
+menu bar.
+
+image::media/workstation-button_bar-1.png[button bar]
+
+The look of the buttons can be customized. Use _Mode_, _Label Position_ and
+_Icon Size_ on the _Toolbar_ menu shown on the screen below to select your
+preference.
+
+A group of buttons can be selected or activated by default for all
+workstations at a particular library (see
+<<_library_settings_editor,Library Settings>> for details). A different
+default group can be set up on individual workstations by the following
+steps.
+
+. Go to *Admin -> Workstation Administration -> Toolbars -> Current*.
++
+image::media/workstation-button_bar-2.png[button bar 2]
++
+. Choose a group from the list.
+. Go back to the above menu. Select *Set Workstation Default to Current*.
+The above selected toolbar group is set as default for this workstation.
+
+To clear an existing setting click *Clear Workstation Default*.
+
+Circulation and Cataloguing are the default toolbar groups. Local system
+administrators can <<_customizable_toolbar,create new groups>> for
+individual accounts, workstations or all in a particular library.
+
+++ /dev/null
-Button Bar/Toolbar
-------------------
-
-indexterm:[staff client, button bar]
-indexterm:[staff client, toolbar]
-
-There is an optional toolbar with buttons providing quick access to commonly
-used staff client functions. When activated the toolbar appears below the
-menu bar.
-
-image::media/workstation-button_bar-1.png[button bar]
-
-The look of the buttons can be customized. Use _Mode_, _Label Position_ and
-_Icon Size_ on the _Toolbar_ menu shown on the screen below to select your
-preference.
-
-A group of buttons can be selected or activated by default for all
-workstations at a particular library (see
-<<_library_settings_editor,Library Settings>> for details). A different
-default group can be set up on individual workstations by the following
-steps.
-
-. Go to *Admin -> Workstation Administration -> Toolbars -> Current*.
-+
-image::media/workstation-button_bar-2.png[button bar 2]
-+
-. Choose a group from the list.
-. Go back to the above menu. Select *Set Workstation Default to Current*.
-The above selected toolbar group is set as default for this workstation.
-
-To clear an existing setting click *Clear Workstation Default*.
-
-Circulation and Cataloguing are the default toolbar groups. Local system
-administrators can <<_customizable_toolbar,create new groups>> for
-individual accounts, workstations or all in a particular library.
-
--- /dev/null
+Column Picker
+-------------
+
+indexterm:[Column Picker]
+
+From many screens and lists, you can click on the column picker
+drop-down menu to change which columns are displayed.
+
+image::media/column_picker_web.png[column_picker_xul]
+
+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.
+
+image::media/column_picker_web_save.png[column_picker_xul_save]
+
+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*.
+
+image::media/column_picker_dojo.png[column_picker_dojo]
+
+
+++ /dev/null
-Column Picker
--------------
-
-indexterm:[Column Picker]
-
-From many screens and lists, you can click on the column picker
-drop-down menu to change which columns are displayed.
-
-image::media/column_picker_web.png[column_picker_xul]
-
-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.
-
-image::media/column_picker_web_save.png[column_picker_xul_save]
-
-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*.
-
-image::media/column_picker_dojo.png[column_picker_dojo]
-
-
--- /dev/null
+New Options for Double Clicking
+-------------------------------
+
+Double Click to Retrieve a Patron's Record
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+. Click *Search -> Search for Patrons* to access a patron's record
+. Enter search terms.
+. Retrieve a list of possible matches. Double click on the record that you want to open.
+
+image::media/Double_Click1.jpg[Double_Click1]
+
+
+Double Click to Retrieve Item Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+. Enter search terms to retrieve a bibliographic record.
+. Click *Actions for this Record* -> *Holdings Maintenance*.
+. Double click on an item.
++
+image::media/Double_Click3.jpg[Double_Click3]
++
+. The copy information will appear in a new tab.
+++ /dev/null
-New Options for Double Clicking
--------------------------------
-
-Double Click to Retrieve a Patron's Record
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-. Click *Search -> Search for Patrons* to access a patron's record
-. Enter search terms.
-. Retrieve a list of possible matches. Double click on the record that you want to open.
-
-image::media/Double_Click1.jpg[Double_Click1]
-
-
-Double Click to Retrieve Item Attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-. Enter search terms to retrieve a bibliographic record.
-. Click *Actions for this Record* -> *Holdings Maintenance*.
-. Double click on an item.
-+
-image::media/Double_Click3.jpg[Double_Click3]
-+
-. The copy information will appear in a new tab.
--- /dev/null
+Logging in to Evergreen
+-----------------------
+
+indexterm:[staff client, logging in]
+indexterm:[SSL certificate]
+
+. Select the _Locale_ to match your language preference.
+. Enter the _Hostname_ of the Evergreen server you are connecting.
+. Click _Test Server_ to ensure that you are able to reach the
+server. You should see ``200 : OK'' indicated in green for _Status_ and _Version_.
++
+[NOTE]
+============
+If _Status_ indicates ``There was an error testing this server'', check for a typo
+in the _Hostname_ field or ask your administrator for the correct _Hostname_
+to use.
+
+IF _version_ indicates ``404 Not Found'', the server does not support the version
+of your staff client. You will need to download the correct version or contact
+your system administrator.
+
+If your server has a self-signed SSL certificate, you may need to click _Add SSL Exception_
+in order to login.
+============
++
+. Enter your _Username_ and _Password_ and click _Login_.
+. If this is the first time you login from the workstation, you will
+need to <<register_workstation,register your workstation>>.
+
+Standalone Interface
+~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[staff client, standalone interface]
+
+If your connection to Evergreen is lost, click _Standalone
+Interface_ to circulate items or register patrons while connection is down.
+
+[[preset_tabs]]
+Preset Tabs in Evergreen Client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To have preset tabs waiting when Evergreen opens you will need to modify the
+*Evergreen shortcut* on your desktop.
+
+. First, you need to copy your shortcut. There are a couple of ways to do this.
+.. Right-mouse click and drag icon; upon release select *Create Shortcut
+Here*.
++
+image::media/create_shortcut_here.png[]
++
+.. Right-mouse click icon, select *Send to*, and select *Desktop (create
+shortcut)*.
++
+image::media/send_to_desktop.png[]
++
+. Right-mouse click the new shortcut and select *Properties*.
++
+image::media/shortcut_properties.png[]
++
+. Listed in the *Target* box you will see something like the following path
+surrounded by quotation marks: "C:\Program Files\Evergreen Staff Client MVLC\evergreen.exe"
++
+image::media/shortcut_properties_window.png[]
++
+. Place your cursor after the ending quotation mark. Enter a space after the
+last quotation mark and then enter the tab code from the list below. Add
+multiple tabs with a space separating them.
++
+image::media/preset_tabs.png[]
++
+For Example, to have Checkout, Checkin, Catalog Search, and a blank tab preset:
+"C:\Program Files\Evergreen Staff Client MVLC\evergreen.exe" -ilscheckout -ilscheckin -ilsurl XUL_OPAC_WRAPPER -ilstab
+. The following options are available:
+
+- -ILScheckin : Opens the Check In interface
+- -ILScheckout : Opens the Check Out interface
+- -ILSurl <url/constant> : Opens the specified page
+- -ILSnew : Opens a new "menu" window
+- -ILStab : Opens a new (default) tab
+- -ILSnew_default : Opens a new "menu" window with a guaranteed default tab
+- -ILSoffline/-ILSstandalone : Opens the standalone interface
+- -ILSlogin : Opens the login page
++
+[TIP]
+.Useful Tab Codes
+=====================
+ - -ilsurl XUL_PATRON_DISPLAY : Opens a Patron Search tab
+ - -ilsurl XUL_HOLD_PULL_LIST : Opens a Pull List tab
+ - -ilsurl XUL_HOLDS_BROWSER : Opens a Browse Holds Shelf tab
+ - -ilsurl XUL_OPAC_WRAPPER : Opens an Advanced Catalog search tab
+ - -ilsurl XUL_COPY_STATUS : Opens an Item status by barcode tab
+ - -ilsurl XUL_RECORD_BUCKETS : Opens a Manage Record Buckets tab
+ - -ilsurl XUL_COPY_BUCKETS : Opens a Manage Copy Buckets tab
+ - -ilsurl XUL_MARC_NEW : Opens a Create new MARC record tab
+ - -ilsurl XUL_Z3950_IMPORT : Opens an Import record from Z39.50 tab
+ - To open two windows, one with checkin and checkout, one with Marc and Z39.50, use:
+ +
+ -ilscheckin -ilscheckout -ilsnew -ilsurl XUL_MARC_NEW -ilsurl XUL_Z3950_IMPORT
+========================
++
+. You may want to rename your shortcut to reflect its purpose. For example, you
+could have one icon set to open circulation-related tabs and one icon to open
+cataloging-related tabs. Right-mouse click and select *Rename* to do this.
+
+Auto Login
+~~~~~~~~~~~
+
+To use auto login, you will need to modify the *Evergreen shortcut* on your desktop. There are three new commands which are necessary for automatic login:
+
+- -ilsuser
+- -ilspassword
+- -ilshost
+
+You will need all three to have your client successfully login. To enable
+automatic login we need to modify the Evergreen shortcut on your desktop. If
+your shortcut already has preset tab commands, then place the automatic login
+commands after those commands.
+
+. First, if your workstation will have multiple logins (circ, cat, admin) you need to copy a shortcut for each. There are a couple of ways to do this.
+.. Right-mouse click and drag icon; upon release select *Create Shortcut Here*.
++
+image::media/create_shortcut_here.png[]
++
+.. Right-mouse click icon, select *Send to*, and select *Desktop (create shortcut)*.
++
+image::media/send_to_desktop.png[]
++
+. Right-mouse click the new shortcut and select *Properties*.
++
+image::media/shortcut_properties.png[]
++
+Listed in the *Target* box you will see something like the following path
+surrounded by quotation marks: "C:\Program Files\Evergreen Staff Client MVLC\evergreen.exe"
++
+image::media/shortcut_properties_window.png[]
++
+. Place your cursor after the ending quotation mark and enter a space after the
+last quotation mark.
++
+image::media/target_box.png[]
++
+.. After the space enter the login code for username followed by a space and
+the username +
+-ilsuser circuser
+.. Enter a space and then the login code for password followed by the password +
+-ilspassword circpass
+.. Finally, enter the login code for host followed by a space and the host
+address (this is the exact address which shows up in the Server Hostname box
+when you manually login to the client. +
+-ilshost evergreen.mvlcstaff.org
++
+image::media/auto_login.png[]
++
+[NOTE]
+When you double-click on the new shortcut it may seem like nothing is
+happening, but it really is! It takes the program a few moments to digest the
+new requests and to do the login.
+
+Logging Out
+~~~~~~~~~~~
+
+indexterm:[staff client, logging out]
+
+There are several ways to end your Evergreen staff client session:
+
+* Click the *Exit Evergreen* button on the bottom of the login page.
+* Click the *x* at the top left of the *login* window.
+* Choose *File -> Quit Program* from the menu of the application window.
+
+[CAUTION]
+============
+Clicking the *x* on the application window (not the login window) will not exit
+Evergreen, but only close the window.
+
+A new application window can be opened by clicking _Open New Window_ from the
+login window.
+============
+
+++ /dev/null
-Logging in to Evergreen
------------------------
-
-indexterm:[staff client, logging in]
-indexterm:[SSL certificate]
-
-. Select the _Locale_ to match your language preference.
-. Enter the _Hostname_ of the Evergreen server you are connecting.
-. Click _Test Server_ to ensure that you are able to reach the
-server. You should see ``200 : OK'' indicated in green for _Status_ and _Version_.
-+
-[NOTE]
-============
-If _Status_ indicates ``There was an error testing this server'', check for a typo
-in the _Hostname_ field or ask your administrator for the correct _Hostname_
-to use.
-
-IF _version_ indicates ``404 Not Found'', the server does not support the version
-of your staff client. You will need to download the correct version or contact
-your system administrator.
-
-If your server has a self-signed SSL certificate, you may need to click _Add SSL Exception_
-in order to login.
-============
-+
-. Enter your _Username_ and _Password_ and click _Login_.
-. If this is the first time you login from the workstation, you will
-need to <<register_workstation,register your workstation>>.
-
-Standalone Interface
-~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[staff client, standalone interface]
-
-If your connection to Evergreen is lost, click _Standalone
-Interface_ to circulate items or register patrons while connection is down.
-
-[[preset_tabs]]
-Preset Tabs in Evergreen Client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To have preset tabs waiting when Evergreen opens you will need to modify the
-*Evergreen shortcut* on your desktop.
-
-. First, you need to copy your shortcut. There are a couple of ways to do this.
-.. Right-mouse click and drag icon; upon release select *Create Shortcut
-Here*.
-+
-image::media/create_shortcut_here.png[]
-+
-.. Right-mouse click icon, select *Send to*, and select *Desktop (create
-shortcut)*.
-+
-image::media/send_to_desktop.png[]
-+
-. Right-mouse click the new shortcut and select *Properties*.
-+
-image::media/shortcut_properties.png[]
-+
-. Listed in the *Target* box you will see something like the following path
-surrounded by quotation marks: "C:\Program Files\Evergreen Staff Client MVLC\evergreen.exe"
-+
-image::media/shortcut_properties_window.png[]
-+
-. Place your cursor after the ending quotation mark. Enter a space after the
-last quotation mark and then enter the tab code from the list below. Add
-multiple tabs with a space separating them.
-+
-image::media/preset_tabs.png[]
-+
-For Example, to have Checkout, Checkin, Catalog Search, and a blank tab preset:
-"C:\Program Files\Evergreen Staff Client MVLC\evergreen.exe" -ilscheckout -ilscheckin -ilsurl XUL_OPAC_WRAPPER -ilstab
-. The following options are available:
-
-- -ILScheckin : Opens the Check In interface
-- -ILScheckout : Opens the Check Out interface
-- -ILSurl <url/constant> : Opens the specified page
-- -ILSnew : Opens a new "menu" window
-- -ILStab : Opens a new (default) tab
-- -ILSnew_default : Opens a new "menu" window with a guaranteed default tab
-- -ILSoffline/-ILSstandalone : Opens the standalone interface
-- -ILSlogin : Opens the login page
-+
-[TIP]
-.Useful Tab Codes
-=====================
- - -ilsurl XUL_PATRON_DISPLAY : Opens a Patron Search tab
- - -ilsurl XUL_HOLD_PULL_LIST : Opens a Pull List tab
- - -ilsurl XUL_HOLDS_BROWSER : Opens a Browse Holds Shelf tab
- - -ilsurl XUL_OPAC_WRAPPER : Opens an Advanced Catalog search tab
- - -ilsurl XUL_COPY_STATUS : Opens an Item status by barcode tab
- - -ilsurl XUL_RECORD_BUCKETS : Opens a Manage Record Buckets tab
- - -ilsurl XUL_COPY_BUCKETS : Opens a Manage Copy Buckets tab
- - -ilsurl XUL_MARC_NEW : Opens a Create new MARC record tab
- - -ilsurl XUL_Z3950_IMPORT : Opens an Import record from Z39.50 tab
- - To open two windows, one with checkin and checkout, one with Marc and Z39.50, use:
- +
- -ilscheckin -ilscheckout -ilsnew -ilsurl XUL_MARC_NEW -ilsurl XUL_Z3950_IMPORT
-========================
-+
-. You may want to rename your shortcut to reflect its purpose. For example, you
-could have one icon set to open circulation-related tabs and one icon to open
-cataloging-related tabs. Right-mouse click and select *Rename* to do this.
-
-Auto Login
-~~~~~~~~~~~
-
-To use auto login, you will need to modify the *Evergreen shortcut* on your desktop. There are three new commands which are necessary for automatic login:
-
-- -ilsuser
-- -ilspassword
-- -ilshost
-
-You will need all three to have your client successfully login. To enable
-automatic login we need to modify the Evergreen shortcut on your desktop. If
-your shortcut already has preset tab commands, then place the automatic login
-commands after those commands.
-
-. First, if your workstation will have multiple logins (circ, cat, admin) you need to copy a shortcut for each. There are a couple of ways to do this.
-.. Right-mouse click and drag icon; upon release select *Create Shortcut Here*.
-+
-image::media/create_shortcut_here.png[]
-+
-.. Right-mouse click icon, select *Send to*, and select *Desktop (create shortcut)*.
-+
-image::media/send_to_desktop.png[]
-+
-. Right-mouse click the new shortcut and select *Properties*.
-+
-image::media/shortcut_properties.png[]
-+
-Listed in the *Target* box you will see something like the following path
-surrounded by quotation marks: "C:\Program Files\Evergreen Staff Client MVLC\evergreen.exe"
-+
-image::media/shortcut_properties_window.png[]
-+
-. Place your cursor after the ending quotation mark and enter a space after the
-last quotation mark.
-+
-image::media/target_box.png[]
-+
-.. After the space enter the login code for username followed by a space and
-the username +
--ilsuser circuser
-.. Enter a space and then the login code for password followed by the password +
--ilspassword circpass
-.. Finally, enter the login code for host followed by a space and the host
-address (this is the exact address which shows up in the Server Hostname box
-when you manually login to the client. +
--ilshost evergreen.mvlcstaff.org
-+
-image::media/auto_login.png[]
-+
-[NOTE]
-When you double-click on the new shortcut it may seem like nothing is
-happening, but it really is! It takes the program a few moments to digest the
-new requests and to do the login.
-
-Logging Out
-~~~~~~~~~~~
-
-indexterm:[staff client, logging out]
-
-There are several ways to end your Evergreen staff client session:
-
-* Click the *Exit Evergreen* button on the bottom of the login page.
-* Click the *x* at the top left of the *login* window.
-* Choose *File -> Quit Program* from the menu of the application window.
-
-[CAUTION]
-============
-Clicking the *x* on the application window (not the login window) will not exit
-Evergreen, but only close the window.
-
-A new application window can be opened by clicking _Open New Window_ from the
-login window.
-============
-
--- /dev/null
+Patron Border Color Enhancement
+-------------------------------
+
+This feature gives librarians new choices for color coding patron penalties.
+
+In version 2.3, if the staff_alert column on the Standing Penalty Type is set to
+True and no other more serious penalty (as defined by the CSS) trumps it, then,
+when a patron incurs a penalty, a blue border will appear around the patron's
+name.
+
+For example, by default, the standing penalty type, ALERT_NOTE, has the
+staff_alert value set to TRUE. If I apply an alert to a user's account, and no
+other penalty color takes precedence over it, then a blue border will appear
+around the patron's name.
+
+image::media/Patron_Border_Color_Enhancements2.jpg[Patron_Border_Color_Enhancements2]
+
+In addition, librarians now can customize the color coding on custom penalty
+types. For example, librarians can create a penalty type and, using the CSS
+classname PATRON_HAS_CUSTOM_PENALTY, apply a custom color box to the patron's
+record.
+
+++ /dev/null
-Patron Border Color Enhancement
--------------------------------
-
-This feature gives librarians new choices for color coding patron penalties.
-
-In version 2.3, if the staff_alert column on the Standing Penalty Type is set to
-True and no other more serious penalty (as defined by the CSS) trumps it, then,
-when a patron incurs a penalty, a blue border will appear around the patron's
-name.
-
-For example, by default, the standing penalty type, ALERT_NOTE, has the
-staff_alert value set to TRUE. If I apply an alert to a user's account, and no
-other penalty color takes precedence over it, then a blue border will appear
-around the patron's name.
-
-image::media/Patron_Border_Color_Enhancements2.jpg[Patron_Border_Color_Enhancements2]
-
-In addition, librarians now can customize the color coding on custom penalty
-types. For example, librarians can create a penalty type and, using the CSS
-classname PATRON_HAS_CUSTOM_PENALTY, apply a custom color box to the patron's
-record.
-
--- /dev/null
+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*
+
+image::media/Saved_Catalog_Searches_2_21.jpg[Saved_Catalog_Searches_2_21]
+
+
+NOTE: 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.
+
+image::media/Saved_Catalog_Searches_2_22.jpg[Saved_Catalog_Searches_2_22]
+++ /dev/null
-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*
-
-image::media/Saved_Catalog_Searches_2_21.jpg[Saved_Catalog_Searches_2_21]
-
-
-NOTE: 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.
-
-image::media/Saved_Catalog_Searches_2_22.jpg[Saved_Catalog_Searches_2_22]
--- /dev/null
+Return to Search Results from MARC Record
+-----------------------------------------
+
+This feature enables you to return to your title search results directly from any view of the MARC record, including the OPAC View, MARC Record, MARC Edit, and Holdings Maintenance. You can use this feature to page through records in the MARC Record View or Edit interfaces. You do not have to return to the OPAC View to access title results.
+
+image::media/Search_Results1.jpg[Search_Results1]
+++ /dev/null
-Return to Search Results from MARC Record
------------------------------------------
-
-This feature enables you to return to your title search results directly from any view of the MARC record, including the OPAC View, MARC Record, MARC Edit, and Holdings Maintenance. You can use this feature to page through records in the MARC Record View or Edit interfaces. You do not have to return to the OPAC View to access title results.
-
-image::media/Search_Results1.jpg[Search_Results1]
--- /dev/null
+Sorting Columns
+---------------
+
+This feature enables you to sort display columns so that you can find easily the
+information that you need on a screen that contains multiple columns. You can
+sort display columns on any screen that is built on a grid, such as the Check In
+screen or the On Shelf Pull List.
+
+You can also sort the columns on the following Administration screens:
+Circulation Policies, Hold Policies, Circulation Limit Sets, Barcode Completion,
+Acquisitions User Request List, and Vandelay Import Errors.
+
+You can sort items in an ascending or descending order, and you can prioritize
+the order in which columns will sort. The following use cases illustrate how to
+sort items within the Circulation and Administration interfaces.
+
+Sorting the On Shelf Pull List
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You want to capture items that are on the shelf to fill current holds. To
+simplify this process, you will sort the items on the On Shelf Pull List by Copy
+Location and Call Number.
+
+. Click *Circulation* -> *Pull List for Hold Requests*.
+. The first column that you want to sort is the column, Current Copy Location. Right click the column header, Current Copy Location.
+. Click *Sort First (Descending)*.
++
+image::media/Sorting_Columns3.jpg[Sorting_Columns3]
++
+. The next column that you want to sort is the column, Call Number. Right click the column header, Call Number.
+. Click *Sort Next (Ascending)*.
++
+image::media/Sorting_Columns4.jpg[Sorting_Columns4]
++
+. The pull list has now been sorted by copy location and call number.
+
+image::media/Sorting_Columns5.jpg[Sorting_Columns5]
+
+NOTE: If you wanted to sort more columns, you could continue the process by clicking *Sort Next* for any subsequent columns.
+
+
+Sorting Circulation Policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You want to sort the display of circulation policies in your staff client.
+
+. Click *Administration* -> *Local Administration* -> *Circulation Policies*.
+. Right click on any column header.
+. A pop-up box appears.
++
+image::media/Sorting_Columns2.jpg[Sorting_Columns2]
++
+. Check the *Display* box if you want to display a column in the staff client.
+. Check the *Auto Width* box if you want the width of the columns to adjust to fit the staff client.
+. Select a sort priority.
+.. A sort priority of "0" indicates that no sorting has been applied. Columns will display in their default order.
+.. A sort priority of "1" indicates that ascending sorting should be applied to this column first. Subsequent sorts will be applied as you continue to enter increasing numbers.
+.. A sort priority of "-1" indicates that descending sorting should be applied to this column.
+. Click *Save*. The circulation policies will now sort according to your selections each time that you log into the staff client.
+++ /dev/null
-Sorting Columns
----------------
-
-This feature enables you to sort display columns so that you can find easily the
-information that you need on a screen that contains multiple columns. You can
-sort display columns on any screen that is built on a grid, such as the Check In
-screen or the On Shelf Pull List.
-
-You can also sort the columns on the following Administration screens:
-Circulation Policies, Hold Policies, Circulation Limit Sets, Barcode Completion,
-Acquisitions User Request List, and Vandelay Import Errors.
-
-You can sort items in an ascending or descending order, and you can prioritize
-the order in which columns will sort. The following use cases illustrate how to
-sort items within the Circulation and Administration interfaces.
-
-Sorting the On Shelf Pull List
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You want to capture items that are on the shelf to fill current holds. To
-simplify this process, you will sort the items on the On Shelf Pull List by Copy
-Location and Call Number.
-
-. Click *Circulation* -> *Pull List for Hold Requests*.
-. The first column that you want to sort is the column, Current Copy Location. Right click the column header, Current Copy Location.
-. Click *Sort First (Descending)*.
-+
-image::media/Sorting_Columns3.jpg[Sorting_Columns3]
-+
-. The next column that you want to sort is the column, Call Number. Right click the column header, Call Number.
-. Click *Sort Next (Ascending)*.
-+
-image::media/Sorting_Columns4.jpg[Sorting_Columns4]
-+
-. The pull list has now been sorted by copy location and call number.
-
-image::media/Sorting_Columns5.jpg[Sorting_Columns5]
-
-NOTE: If you wanted to sort more columns, you could continue the process by clicking *Sort Next* for any subsequent columns.
-
-
-Sorting Circulation Policies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You want to sort the display of circulation policies in your staff client.
-
-. Click *Administration* -> *Local Administration* -> *Circulation Policies*.
-. Right click on any column header.
-. A pop-up box appears.
-+
-image::media/Sorting_Columns2.jpg[Sorting_Columns2]
-+
-. Check the *Display* box if you want to display a column in the staff client.
-. Check the *Auto Width* box if you want the width of the columns to adjust to fit the staff client.
-. Select a sort priority.
-.. A sort priority of "0" indicates that no sorting has been applied. Columns will display in their default order.
-.. A sort priority of "1" indicates that ascending sorting should be applied to this column first. Subsequent sorts will be applied as you continue to enter increasing numbers.
-.. A sort priority of "-1" indicates that descending sorting should be applied to this column.
-. Click *Save*. The circulation policies will now sort according to your selections each time that you log into the staff client.
--- /dev/null
+Check-boxes
+-----------
+
+indexterm:[Check-boxes, sticky settings]
+
+Most staff client check-boxes are ``sticky'' -- if you select or deselect
+them, that status persists. For example, *Auto-Print*, which will print
+the relevant receipts automatically in certain functions, is sticky. If
+you select it on one login, it will persist for future logins until you
+uncheck the box.
+
+image::media/staff_client-3.png[staff_client-3]
+
+*Fast Item Add* is another ``sticky'' check box that makes it possible to
+add volume and item records from the MARC editor.
+
+image::media/staff_client-4.png[staff_client-4]
+++ /dev/null
-Check-boxes
------------
-
-indexterm:[Check-boxes, sticky settings]
-
-Most staff client check-boxes are ``sticky'' -- if you select or deselect
-them, that status persists. For example, *Auto-Print*, which will print
-the relevant receipts automatically in certain functions, is sticky. If
-you select it on one login, it will persist for future logins until you
-uncheck the box.
-
-image::media/staff_client-3.png[staff_client-3]
-
-*Fast Item Add* is another ``sticky'' check box that makes it possible to
-add volume and item records from the MARC editor.
-
-image::media/staff_client-4.png[staff_client-4]
--- /dev/null
+Tab Buttons
+-----------
+
+This feature enables you to add a new tab to the Evergreen staff client by clicking the + sign adjacent to the tab that you currently have opened. As in previous versions, you can also add new tabs by clicking *File -> New Tab*, or use the hotkey, Ctrl+T.
+
+image::media/New_Tab_Button1.jpg[New_Tab_Button1]
+++ /dev/null
-Tab Buttons
------------
-
-This feature enables you to add a new tab to the Evergreen staff client by clicking the + sign adjacent to the tab that you currently have opened. As in previous versions, you can also add new tabs by clicking *File -> New Tab*, or use the hotkey, Ctrl+T.
-
-image::media/New_Tab_Button1.jpg[New_Tab_Button1]
--- /dev/null
+TPac Configuration and Customization
+------------------------------------
+
+Template toolkit documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For more general information about template toolkit see: http://template-toolkit.org/docs/index.html[official
+documentation].
+
+The purpose of this chapter is to focus on the
+Evergreen-specific uses of Template Toolkit ('TT') in the OPAC.
+
+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!)
+
+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`
+
+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.
+
+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`.
+
+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/`.
+
+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
+[source, html]
+------------------------------------------------------------------------------
+[% 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.
+
+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)
+[source, bash]
+------------------------------------------------------------------------------
+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
+[source,xml]
+------------------------------------------------------------------------------
+<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
+[source,bash]
+------------------------------------------------------------------------------
+bash# /etc/init.d/apache2 reload
+------------------------------------------------------------------------------
+
+You should now be able to see your change at http://localhost/eg/opac/advanced
+
+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)
+[source,xml]
+------------------------------------------------------------------------------
+# 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)
+[source,xml]
+------------------------------------------------------------------------------
+<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>
+------------------------------------------------------------------------------
+
+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"
+[source,bash]
+------------------------------------------------------------------------------
+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
+[source,bash]
+------------------------------------------------------------------------------
+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
+[source,html]
+------------------------------------------------------------------------------
+<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).
+
+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
+[source,bash]
+------------------------------------------------------------------------------
+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
+------------------------------------------------------------------------------
+
+++ /dev/null
-TPac Configuration and Customization
-------------------------------------
-
-Template toolkit documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For more general information about template toolkit see: http://template-toolkit.org/docs/index.html[official
-documentation].
-
-The purpose of this chapter is to focus on the
-Evergreen-specific uses of Template Toolkit ('TT') in the OPAC.
-
-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!)
-
-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`
-
-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.
-
-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`.
-
-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/`.
-
-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
-[source, html]
-------------------------------------------------------------------------------
-[% 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.
-
-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)
-[source, bash]
-------------------------------------------------------------------------------
-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
-[source,xml]
-------------------------------------------------------------------------------
-<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
-[source,bash]
-------------------------------------------------------------------------------
-bash# /etc/init.d/apache2 reload
-------------------------------------------------------------------------------
-
-You should now be able to see your change at http://localhost/eg/opac/advanced
-
-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)
-[source,xml]
-------------------------------------------------------------------------------
-# 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)
-[source,xml]
-------------------------------------------------------------------------------
-<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>
-------------------------------------------------------------------------------
-
-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"
-[source,bash]
-------------------------------------------------------------------------------
-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
-[source,bash]
-------------------------------------------------------------------------------
-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
-[source,html]
-------------------------------------------------------------------------------
-<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).
-
-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
-[source,bash]
-------------------------------------------------------------------------------
-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
-------------------------------------------------------------------------------
-
--- /dev/null
+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.
+
+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*.
+
+image::media/User_Activity_Types1A.jpg[User_Activity_Types1A]
+
+
+Using this Feature
+~~~~~~~~~~~~~~~~~~
+
+The last activity date for user logins appears in the patron's summary.
+
+image::media/User_Activity_Types2A.jpg[User_Activity_Types2A]
+
+++ /dev/null
-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.
-
-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*.
-
-image::media/User_Activity_Types1A.jpg[User_Activity_Types1A]
-
-
-Using this Feature
-~~~~~~~~~~~~~~~~~~
-
-The last activity date for user logins appears in the patron's summary.
-
-image::media/User_Activity_Types2A.jpg[User_Activity_Types2A]
-
--- /dev/null
+Tab Browser-Based 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.
+
+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.
+++ /dev/null
-Tab Browser-Based 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.
-
-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.
--- /dev/null
+Logging into Evergreen
+-----------------------
+
+indexterm:[staff client, logging in]
+indexterm:[SSL certificate]
+
+. 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*.
+[NOTE]
+Although workstation registration is not required in the web client, it is
+highly recommended that you register the workstation for all web client features
+to work correctly. If you have not yet registered a workstation, you need to log
+in with the workstation field unset and then follow instructions to
+<<register_workstation,register your workstation>>.
+
+[[browser_defaults]]
+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.
+
+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*.
+
+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*.
+
+Logging Out
+~~~~~~~~~~~
+
+indexterm:[staff client, 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*
+
+[CAUTION]
+Exiting the browser will not log you out of the web client.
+
+++ /dev/null
-Logging into Evergreen
------------------------
-
-indexterm:[staff client, logging in]
-indexterm:[SSL certificate]
-
-. 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*.
-[NOTE]
-Although workstation registration is not required in the web client, it is
-highly recommended that you register the workstation for all web client features
-to work correctly. If you have not yet registered a workstation, you need to log
-in with the workstation field unset and then follow instructions to
-<<register_workstation,register your workstation>>.
-
-[[browser_defaults]]
-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.
-
-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*.
-
-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*.
-
-Logging Out
-~~~~~~~~~~~
-
-indexterm:[staff client, 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*
-
-[CAUTION]
-Exiting the browser will not log you out of the web client.
-
--- /dev/null
+Workstation Administration
+--------------------------
+
+indexterm:[staff client, configuration]
+indexterm:[workstation, configuration]
+indexterm:[configuration]
+
+Copy Editor: Copy Location Name First
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[copy editor, shelving location]
+
+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.
+
+Font and Sound Settings
+~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[staff client, fonts, zooming]
+indexterm:[staff client, sounds]
+
+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_.
++
+image::media/workstation_admin-1.jpg[disable sound]
++
+. To change the size of the font, pick the desired option and click _Save
+to Disk_.
+
+image::media/workstation_admin-2.jpg[font size]
+
+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.
+
+Select Hotkeys
+~~~~~~~~~~~~~~
+
+indexterm:[staff client, 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_.
++
+image::media/workstation_admin-3.png[select hotkeys]
++
+* *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.
+
+Configure Printers
+~~~~~~~~~~~~~~~~~~
+
+indexterm:[staff client, 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.
++
+image::media/workstation_admin-4.png[printer context]
++
+* *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.
++
+image::media/workstation_admin-5.png[set default 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.
+
+image::media/workstation_admin-6.jpg[page setup]
+
+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)
+
+[NOTE]
+====================================
+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.
+====================================
+
+++ /dev/null
-Workstation Administration
---------------------------
-
-indexterm:[staff client, configuration]
-indexterm:[workstation, configuration]
-indexterm:[configuration]
-
-Copy Editor: Copy Location Name First
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[copy editor, shelving location]
-
-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.
-
-Font and Sound Settings
-~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[staff client, fonts, zooming]
-indexterm:[staff client, sounds]
-
-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_.
-+
-image::media/workstation_admin-1.jpg[disable sound]
-+
-. To change the size of the font, pick the desired option and click _Save
-to Disk_.
-
-image::media/workstation_admin-2.jpg[font size]
-
-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.
-
-Select Hotkeys
-~~~~~~~~~~~~~~
-
-indexterm:[staff client, 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_.
-+
-image::media/workstation_admin-3.png[select hotkeys]
-+
-* *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.
-
-Configure Printers
-~~~~~~~~~~~~~~~~~~
-
-indexterm:[staff client, 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.
-+
-image::media/workstation_admin-4.png[printer context]
-+
-* *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.
-+
-image::media/workstation_admin-5.png[set default 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.
-
-image::media/workstation_admin-6.jpg[page setup]
-
-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)
-
-[NOTE]
-====================================
-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.
-====================================
-
--- /dev/null
+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).
+
+Configure Toolbar
+^^^^^^^^^^^^^^^^^
+
+. Click *Admin* -> *Workstation Administration* -> *Toolbars* -> *Configure
+Toolbars*.
+
+. Click *New Toolbar*.
+
+. Enter label for toolbar.
++
+image::media/Customizable_Toolbar1.jpg[Customizable_Toolbar1]
++
+. 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.
++
+image::media/Customizable_Toolbar2.jpg[Customizable_Toolbar2]
++
+. 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)`.
++
+image::media/Customizable_Toolbar3.jpg[Customizable_Toolbar3]
++
+. To add a dividing line between buttons that appear on the same side of the
+screen, select *toolbarseparator*, and click `--> (A)`.
++
+image::media/Customizable_Toolbar4.jpg[Customizable_Toolbar4]
++
+. 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
+++ /dev/null
-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).
-
-Configure Toolbar
-^^^^^^^^^^^^^^^^^
-
-. Click *Admin* -> *Workstation Administration* -> *Toolbars* -> *Configure
-Toolbars*.
-
-. Click *New Toolbar*.
-
-. Enter label for toolbar.
-+
-image::media/Customizable_Toolbar1.jpg[Customizable_Toolbar1]
-+
-. 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.
-+
-image::media/Customizable_Toolbar2.jpg[Customizable_Toolbar2]
-+
-. 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)`.
-+
-image::media/Customizable_Toolbar3.jpg[Customizable_Toolbar3]
-+
-. To add a dividing line between buttons that appear on the same side of the
-screen, select *toolbarseparator*, and click `--> (A)`.
-+
-image::media/Customizable_Toolbar4.jpg[Customizable_Toolbar4]
-+
-. 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
--- /dev/null
+Receipt Template Editor
+-----------------------
+indexterm:[receipt template editor]
+indexterm:[receipt template editor, macros]
+indexterm:[receipt template editor, checkout]
+
+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.
++
+image::media/receipt-2.png[select checkout]
++
+. Make edits to the Receipt on the right hand side.
++
+image::media/receipt-3.jpg[receipt-3]
++
+. Click out of the section you are editing to see what your changes will look right on the Left hand side.
++
+image::media/receipt-3.jpg[receipt-3]
++
+. Click ''Save Locally'' in the Upper right hand corner.
++
+image::media/receipt-15.jpg[receipt-15]
+
+
+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 <<macros, 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.
+
+IMPORTANT: *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.
+
+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.
+
+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.
++
+image::media/receipt-17.jpg[receipt-17]
+
+
+Importing Templates
+^^^^^^^^^^^^^^^^^^^
+
+. Click Import.
++
+image::media/receipt-20.jpg[receipt-20]
++
+. Navigate to and select the template that you want to import. Click Open.
++
+image::media/receipt-21.jpg[receipt-21]
++
+. Click OK.
+. Click Save Locally.
+. Click OK.
++
+image::media/receipt-23.jpg[receipts-23]
+
+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.
+
+TIP: Always remember to ''Save Locally''.
+
+Print Holds Slip with Landscape Layout
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[receipt template editor, holds receipt, 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:
++
+[source, html]
+------------------------
+<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:
++
+[source, html]
+------------------------
+<div style="moz-transform: rotate(90deg);height: 300px; width: 200px;">
+------------------------
++
+image::media/Print_Holds_Slip1.jpg[Print_Holds_Slip1]
++
+. The holds slip will print with the configured text in a landscape layout:
++
+image::media/Print_Holds_Slip2.jpg[Print_Holds_Slip2]
+
+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
+[source,html]
+----------------------------------------------------------------------------------
+<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
+[source,html]
+----------------------------------------------------------------------------------
+<li>%title%<br/>
+By: %author%<br/>
+Barcode: %barcode%<br/>
+Due: %due_date%
+----------------------------------------------------------------------------------
+Footer
+[source,html]
+----------------------------------------------------------------------------------
+</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/>
+----------------------------------------------------------------------------------
+
+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
+[source,html]
+----------------------------------------------------------------------------------
+<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
+[source,html]
+----------------------------------------------------------------------------------
+<em>%formatted_note%</em><br/>
+----------------------------------------------------------------------------------
+Footer
+[source,html]
+----------------------------------------------------------------------------------
+Request date: %request_date%<br/>
+<br/>
+Slip Date: %TODAY_D% %TODAY_I%:%TODAY_M%<br/>
+Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/>.<br/>
+----------------------------------------------------------------------------------
+
+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
+[source,html]
+----------------------------------------------------------------------------------
+<p style="padding-top:80px; padding-bottom:80px">
+<font size="6"><b>
+%SUBSTR(0,4)%%PATRON_LASTNAME%%SUBSTR_END%
+ %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
+[source,html]
+----------------------------------------------------------------------------------
+<em>%formatted_note%</em><br/>
+----------------------------------------------------------------------------------
+Footer
+[source,html]
+----------------------------------------------------------------------------------
+Request date: %request_date%<br/>
+<hr style="border: 1px dotted"/><br/>
+Slip Date: %TODAY_TRIM%<br/>
+Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/>.<br/>
+----------------------------------------------------------------------------------
+
+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
+[source,html]
+----------------------------------------------------------------------------------
+<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
+[source,html]
+----------------------------------------------------------------------------------
+<em>%formatted_note%</em><br/>
+----------------------------------------------------------------------------------
+Footer
+[source,html]
+----------------------------------------------------------------------------------
+<br/>Request date: %request_date%<br/>
+Slip Date: %TODAY_TRIM%<br/>
+Printed at %SHORTNAME%<br/>
+<br/><br/>.<br/>
+----------------------------------------------------------------------------------
+
+Receipt Templates
+~~~~~~~~~~~~~~~~~
+This is a complete list of all the receipts currently in use in Evergreen.
+
+[horizontal]
+*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/>
+
+[[macros]]
+
+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.
+
+General Macros
+^^^^^^^^^^^^^^
+indexterm:[receipt template editor, macros]
+
+[horizontal]
+%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_editor, 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.
+
+indexterm:[receipt template editor, includes]
+
+* %INCLUDE(notice_text)%
+* %INCLUDE(alert_text)%
+* %INCLUDE(event_text)%
+* %INCLUDE(footer_text)%%
+* %INCLUDE(header_text)%
+
+Additional Macros for various slip types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Holds*
+
+[horizontal]
+%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*
+
+[horizontal]
+%title%:: Title
+%author%:: Author
+%barcode%:: Item Barcode
+%due_date%:: Due Date: formated by the date field in the library settings editor
+
+*Payment*
+
+[horizontal]
+%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*
+
+[horizontal]
+%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.
+
+.*General Transits*
+
+[horizontal]
+%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.
+
+
+.*Transit Slip*
+
+[horizontal]
+%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
+++ /dev/null
-Receipt Template Editor
------------------------
-indexterm:[receipt template editor]
-indexterm:[receipt template editor, macros]
-indexterm:[receipt template editor, checkout]
-
-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.
-+
-image::media/receipt-2.png[select checkout]
-+
-. Make edits to the Receipt on the right hand side.
-+
-image::media/receipt-3.jpg[receipt-3]
-+
-. Click out of the section you are editing to see what your changes will look right on the Left hand side.
-+
-image::media/receipt-3.jpg[receipt-3]
-+
-. Click ''Save Locally'' in the Upper right hand corner.
-+
-image::media/receipt-15.jpg[receipt-15]
-
-
-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 <<macros, 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.
-
-IMPORTANT: *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.
-
-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.
-
-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.
-+
-image::media/receipt-17.jpg[receipt-17]
-
-
-Importing Templates
-^^^^^^^^^^^^^^^^^^^
-
-. Click Import.
-+
-image::media/receipt-20.jpg[receipt-20]
-+
-. Navigate to and select the template that you want to import. Click Open.
-+
-image::media/receipt-21.jpg[receipt-21]
-+
-. Click OK.
-. Click Save Locally.
-. Click OK.
-+
-image::media/receipt-23.jpg[receipts-23]
-
-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.
-
-TIP: Always remember to ''Save Locally''.
-
-Print Holds Slip with Landscape Layout
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[receipt template editor, holds receipt, 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:
-+
-[source, html]
-------------------------
-<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:
-+
-[source, html]
-------------------------
-<div style="moz-transform: rotate(90deg);height: 300px; width: 200px;">
-------------------------
-+
-image::media/Print_Holds_Slip1.jpg[Print_Holds_Slip1]
-+
-. The holds slip will print with the configured text in a landscape layout:
-+
-image::media/Print_Holds_Slip2.jpg[Print_Holds_Slip2]
-
-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
-[source,html]
-----------------------------------------------------------------------------------
-<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
-[source,html]
-----------------------------------------------------------------------------------
-<li>%title%<br/>
-By: %author%<br/>
-Barcode: %barcode%<br/>
-Due: %due_date%
-----------------------------------------------------------------------------------
-Footer
-[source,html]
-----------------------------------------------------------------------------------
-</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/>
-----------------------------------------------------------------------------------
-
-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
-[source,html]
-----------------------------------------------------------------------------------
-<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
-[source,html]
-----------------------------------------------------------------------------------
-<em>%formatted_note%</em><br/>
-----------------------------------------------------------------------------------
-Footer
-[source,html]
-----------------------------------------------------------------------------------
-Request date: %request_date%<br/>
-<br/>
-Slip Date: %TODAY_D% %TODAY_I%:%TODAY_M%<br/>
-Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/>.<br/>
-----------------------------------------------------------------------------------
-
-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
-[source,html]
-----------------------------------------------------------------------------------
-<p style="padding-top:80px; padding-bottom:80px">
-<font size="6"><b>
-%SUBSTR(0,4)%%PATRON_LASTNAME%%SUBSTR_END%
- %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
-[source,html]
-----------------------------------------------------------------------------------
-<em>%formatted_note%</em><br/>
-----------------------------------------------------------------------------------
-Footer
-[source,html]
-----------------------------------------------------------------------------------
-Request date: %request_date%<br/>
-<hr style="border: 1px dotted"/><br/>
-Slip Date: %TODAY_TRIM%<br/>
-Printed by %STAFF_FIRSTNAME% at %SHORTNAME%<br/>.<br/>
-----------------------------------------------------------------------------------
-
-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
-[source,html]
-----------------------------------------------------------------------------------
-<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
-[source,html]
-----------------------------------------------------------------------------------
-<em>%formatted_note%</em><br/>
-----------------------------------------------------------------------------------
-Footer
-[source,html]
-----------------------------------------------------------------------------------
-<br/>Request date: %request_date%<br/>
-Slip Date: %TODAY_TRIM%<br/>
-Printed at %SHORTNAME%<br/>
-<br/><br/>.<br/>
-----------------------------------------------------------------------------------
-
-Receipt Templates
-~~~~~~~~~~~~~~~~~
-This is a complete list of all the receipts currently in use in Evergreen.
-
-[horizontal]
-*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/>
-
-[[macros]]
-
-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.
-
-General Macros
-^^^^^^^^^^^^^^
-indexterm:[receipt template editor, macros]
-
-[horizontal]
-%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_editor, 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.
-
-indexterm:[receipt template editor, includes]
-
-* %INCLUDE(notice_text)%
-* %INCLUDE(alert_text)%
-* %INCLUDE(event_text)%
-* %INCLUDE(footer_text)%%
-* %INCLUDE(header_text)%
-
-Additional Macros for various slip types
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*Holds*
-
-[horizontal]
-%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*
-
-[horizontal]
-%title%:: Title
-%author%:: Author
-%barcode%:: Item Barcode
-%due_date%:: Due Date: formated by the date field in the library settings editor
-
-*Payment*
-
-[horizontal]
-%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*
-
-[horizontal]
-%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.
-
-.*General Transits*
-
-[horizontal]
-%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.
-
-
-.*Transit Slip*
-
-[horizontal]
-%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
--- /dev/null
+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.
+
+Data elements that affect your circulation policies
+---------------------------------------------------
+
+There are a few data elements which must be considered when setting up your
+circulation policies.
+
+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.
+
+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.
+
+image::media/copy_locations_editor.png[screenshot of Copy Location Editor]
+
+* Copy locations can also be used as a data element in circulation policies.
+
+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.
+
+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*.
+
+image::media/circ_duration_rules.jpg[]
+
+*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*.
+
+image::media/circ_recurring_fine_rules.jpg[]
+
+*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*.
+
+image::media/circ_max_fine_rules.jpg[]
+
+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.
+
+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.
+
+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.
+
+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*
+
+image::media/circ_example1.png[]
+
+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*
+
+image::media/circ_example2.png[]
+
+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*
+
+image::media/circ_example3.png[]
+
+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.
+
+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.
+++ /dev/null
-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.
-
-Data elements that affect your circulation policies
----------------------------------------------------
-
-There are a few data elements which must be considered when setting up your
-circulation policies.
-
-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.
-
-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.
-
-image::media/copy_locations_editor.png[screenshot of Copy Location Editor]
-
-* Copy locations can also be used as a data element in circulation policies.
-
-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.
-
-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*.
-
-image::media/circ_duration_rules.jpg[]
-
-*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*.
-
-image::media/circ_recurring_fine_rules.jpg[]
-
-*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*.
-
-image::media/circ_max_fine_rules.jpg[]
-
-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.
-
-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.
-
-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.
-
-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*
-
-image::media/circ_example1.png[]
-
-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*
-
-image::media/circ_example2.png[]
-
-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*
-
-image::media/circ_example3.png[]
-
-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.
-
-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.
--- /dev/null
+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.
+
+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.
+
+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*
+
+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.
+
+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.
+
+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*
+
+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.
+
+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.
+
+[source, bash]
+------------------------------------------------------------------------------
+autogen.sh
+------------------------------------------------------------------------------
+
+Set closed dates using the Closed Dates Editor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[Closed Dates]
+
+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.
+
+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*.
+
+image::media/closed_dates.png[]
+
+Now that your organizational structure is established, you can begin
+configuring permissions for the staff users of your Evergreen system.
+
+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.
+
+++ /dev/null
-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.
-
-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.
-
-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*
-
-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.
-
-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.
-
-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*
-
-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.
-
-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.
-
-[source, bash]
-------------------------------------------------------------------------------
-autogen.sh
-------------------------------------------------------------------------------
-
-Set closed dates using the Closed Dates Editor
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[Closed Dates]
-
-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.
-
-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*.
-
-image::media/closed_dates.png[]
-
-Now that your organizational structure is established, you can begin
-configuring permissions for the staff users of your Evergreen system.
-
-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.
-
--- /dev/null
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+[[secondaryperms]]
+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.
+
+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_.
++
+image::media/sup-permissions-1_web_client.png[Secondary Permissions Group]
++
+. From the dropdown menu select one of the secondary permission groups.
++
+image::media/sup-permissions-2_web_client.png[Secondary Permission Group List]
++
+. Click _Add_.
+. Click _Apply Changes_.
++
+image::media/sup-permissions-3.png[Secondary Permission Group Save]
++
+. Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account.
+
+
+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_.
++
+image::media/sup-permissions-1_web_client.png[Secondary Permissions Group]
++
+. Click _Delete_ beside the permission group you would like to remove.
++
+image::media/sup-permissions-4_web_client.png[Secondary Permissions Group Delete]
++
+. Click _Apply Changes_.
++
+image::media/sup-permissions-5_web_client.png[Secondary Permissions Group Save]
++
+. Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account.
+
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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):
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+ 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.
+++ /dev/null
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-[[secondaryperms]]
-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.
-
-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_.
-+
-image::media/sup-permissions-1_web_client.png[Secondary Permissions Group]
-+
-. From the dropdown menu select one of the secondary permission groups.
-+
-image::media/sup-permissions-2_web_client.png[Secondary Permission Group List]
-+
-. Click _Add_.
-. Click _Apply Changes_.
-+
-image::media/sup-permissions-3.png[Secondary Permission Group Save]
-+
-. Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account.
-
-
-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_.
-+
-image::media/sup-permissions-1_web_client.png[Secondary Permissions Group]
-+
-. Click _Delete_ beside the permission group you would like to remove.
-+
-image::media/sup-permissions-4_web_client.png[Secondary Permissions Group Delete]
-+
-. Click _Apply Changes_.
-+
-image::media/sup-permissions-5_web_client.png[Secondary Permissions Group Save]
-+
-. Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account.
-
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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):
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
- 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.
--- /dev/null
+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.
+
+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.
+
+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.
+
+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.
+
+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
+----
+
+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.
+
+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.
+
+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_.
+
+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/_.
+
+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.
+
+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"
+
+----
+
+[NOTE]
+====
+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
+----
+
+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.
+
+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
+----
+
+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:
+
+[options="header"]
+|===
+|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.
+
+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 https://translations.launchpad.net/evergreen[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 <<_setting_a_default_language_and_adding_optional_languages,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
+----
+
+
+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.
+
+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"},
+----
+
+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.
+
+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') %]
+----
+
+
+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.
+
+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."
+
+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
+----
+
+[id="_content_cafe"]
+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.
+
+Change the _return_behavior_on_no_jacket_image_ to set the behavior of your
+service when an image is not available for an item. By default this value is set
+to T which will result in a small image with the text "No Image Available" in
+place of a book cover. If you set this value to 1 a 1X1 blank image will be in
+place of a book cover.
+
+Obalkyknih.cz
+~~~~~~~~~~~~~
+
+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 http://obalkyknih.cz/signup[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.)
+
+Enabling Obalkyknih.cz in Evergreen
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set obalkyknih_cz.enabled to true in '/openils/var/templates/opac/parts/config.tt2':
+
+[source,perl]
+----
+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):
+
+[source,xml]
+----
+<!-- <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:
+
+[source,xml]
+----
+<summary>false</summary>
+----
+
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+
+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.
+
+image::media/clear-added-content-cache-1.png[Clear Cache Link]
+
+Once clicked, there is a pop up that will display what was cleared from the cache.
+
+image::media/clear-added-content-cache-2.jpg[Example Popup]
+
+You will need to reload the record in the staff client to obtain the new images from your
+Added Content Supplier.
+
+
+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.
+
+
+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.
+
+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).
+
+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.
+
+[NOTE]
+=============
+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.
+
+[NOTE]
+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*.
+
+[NOTE]
+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.
+
+Sitemap generator
+-----------------
+A http://www.sitemaps.org[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.
+
+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.
+
+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
+------------------------------------------------------------------------
+
+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
+----
+
+++ /dev/null
-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.
-
-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.
-
-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.
-
-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.
-
-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
-----
-
-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.
-
-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.
-
-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_.
-
-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/_.
-
-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.
-
-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"
-
-----
-
-[NOTE]
-====
-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
-----
-
-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.
-
-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
-----
-
-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:
-
-[options="header"]
-|===
-|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.
-
-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 https://translations.launchpad.net/evergreen[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 <<_setting_a_default_language_and_adding_optional_languages,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
-----
-
-
-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.
-
-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"},
-----
-
-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.
-
-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') %]
-----
-
-
-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.
-
-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."
-
-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
-----
-
-[id="_content_cafe"]
-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.
-
-Change the _return_behavior_on_no_jacket_image_ to set the behavior of your
-service when an image is not available for an item. By default this value is set
-to T which will result in a small image with the text "No Image Available" in
-place of a book cover. If you set this value to 1 a 1X1 blank image will be in
-place of a book cover.
-
-Obalkyknih.cz
-~~~~~~~~~~~~~
-
-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 http://obalkyknih.cz/signup[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.)
-
-Enabling Obalkyknih.cz in Evergreen
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Set obalkyknih_cz.enabled to true in '/openils/var/templates/opac/parts/config.tt2':
-
-[source,perl]
-----
-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):
-
-[source,xml]
-----
-<!-- <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:
-
-[source,xml]
-----
-<summary>false</summary>
-----
-
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-
-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.
-
-image::media/clear-added-content-cache-1.png[Clear Cache Link]
-
-Once clicked, there is a pop up that will display what was cleared from the cache.
-
-image::media/clear-added-content-cache-2.jpg[Example Popup]
-
-You will need to reload the record in the staff client to obtain the new images from your
-Added Content Supplier.
-
-
-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.
-
-
-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.
-
-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).
-
-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.
-
-[NOTE]
-=============
-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.
-
-[NOTE]
-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*.
-
-[NOTE]
-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.
-
-Sitemap generator
------------------
-A http://www.sitemaps.org[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.
-
-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.
-
-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
-------------------------------------------------------------------------
-
-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
-----
-
--- /dev/null
+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.
+
+NOTE: 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.
+
+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.
\ No newline at end of file
+++ /dev/null
-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.
-
-NOTE: 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.
-
-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.
\ No newline at end of file
--- /dev/null
+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.
+
+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*.
+
+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.
+
+WARNING: 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.
+
+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)
+
+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.
++
+image::media/create_match_sets.png[]
+. Click *Save Changes to Expression*.
+
+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.
+
+image::media/record_quality_metrics.png[]
+
+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 <<_import_item_attributes_2,full list of import fields>>
+
+NOTE: All fields (except for Name, Tag and Keep) can contain static
+values, a MARC subfield code (such as "a"), or an XPATH query.
+
+image::media/batch_import_profile.png[Partial Screenshot of a Holdings Import Profile]
+
+
+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.
+
+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.
+++ /dev/null
-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.
-
-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*.
-
-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.
-
-WARNING: 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.
-
-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)
-
-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.
-+
-image::media/create_match_sets.png[]
-. Click *Save Changes to Expression*.
-
-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.
-
-image::media/record_quality_metrics.png[]
-
-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 <<_import_item_attributes_2,full list of import fields>>
-
-NOTE: All fields (except for Name, Tag and Keep) can contain static
-values, a MARC subfield code (such as "a"), or an XPATH query.
-
-image::media/batch_import_profile.png[Partial Screenshot of a Holdings Import Profile]
-
-
-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.
-
-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.
--- /dev/null
+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:
++
+[source,sql]
+----------------------------------
+ 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
+ );
+-----------------------------------
++
+NOTE: 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.
++
+[source,sql]
+----------------------------------
+ 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:
++
+[source,sql]
+----------------------------------
+ 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:
++
+[source,sql]
+----------------------------------
+ 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 .
++
+[source,sql]
+----------------------------------
+ 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:
++
+[source,sql]
+----------------------------------
+ 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:
++
+[source,sql]
+----------------------------------
+ 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.
+
+[source,sql]
+----------------------------------
+ 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.
+
+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:
+
+[source,sql]
+----------------------------------
+ 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.
+
+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.
+
+++ /dev/null
-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:
-+
-[source,sql]
-----------------------------------
- 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
- );
------------------------------------
-+
-NOTE: 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.
-+
-[source,sql]
-----------------------------------
- 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:
-+
-[source,sql]
-----------------------------------
- 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:
-+
-[source,sql]
-----------------------------------
- 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 .
-+
-[source,sql]
-----------------------------------
- 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:
-+
-[source,sql]
-----------------------------------
- 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:
-+
-[source,sql]
-----------------------------------
- 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.
-
-[source,sql]
-----------------------------------
- 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.
-
-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:
-
-[source,sql]
-----------------------------------
- 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.
-
-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.
-
--- /dev/null
+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.
+
+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:
+
+.856 field for electronic resources: indicators and subfields
+[width="100%",options="header"]
+|=============================================================================
+|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.
+
+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.
+
+[source,python]
+------------------------------------------------------------------------------
+#!/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:
++
+[source,sql]
+------------------------------------------------------------------------------
+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:
++
+[source,sql]
+------------------------------------------------------------------------------
+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:
++
+[source,sql]
+------------------------------------------------------------------------------
+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:
++
+[source,sql]
+------------------------------------------------------------------------------
+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.
+
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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:
+
+[source,sql]
+------------------------------------------------------------------------------
+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.
+++ /dev/null
-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.
-
-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:
-
-.856 field for electronic resources: indicators and subfields
-[width="100%",options="header"]
-|=============================================================================
-|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.
-
-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.
-
-[source,python]
-------------------------------------------------------------------------------
-#!/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:
-+
-[source,sql]
-------------------------------------------------------------------------------
-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:
-+
-[source,sql]
-------------------------------------------------------------------------------
-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:
-+
-[source,sql]
-------------------------------------------------------------------------------
-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:
-+
-[source,sql]
-------------------------------------------------------------------------------
-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.
-
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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:
-
-[source,sql]
-------------------------------------------------------------------------------
-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.
--- /dev/null
+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.
+
+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.
+
+Managing Funds
+--------------
+
+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.
+
+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.
+
+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.
+
+Ordering
+--------
+
+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.
+
+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.
+
+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.
+
+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*.
++
+image::media/order_record_loading.png[]
++
+. 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.
+
+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.
+++ /dev/null
-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.
-
-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.
-
-Managing Funds
---------------
-
-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.
-
-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.
-
-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.
-
-Ordering
---------
-
-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.
-
-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.
-
-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.
-
-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*.
-+
-image::media/order_record_loading.png[]
-+
-. 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.
-
-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.
--- /dev/null
+[[attributions]]
+[appendix]
+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
+++ /dev/null
-[[attributions]]
-[appendix]
-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
--- /dev/null
+Working with the MARC Editor
+----------------------------
+
+You can use the MARC Editor to edit MARC fields, sub-fields, and indicators.
+
+Editing MARC Records
+~~~~~~~~~~~~~~~~~~~~
+
+. Retrieve the record.
+. Actions for this 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.
+* Fast Item Add allows attaching items quickly with call number and barcode. When _Save_ is clicked, the copy editor will open.
+. 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.
++
+[NOTE]
+==========
+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 Record_. The record stays open in the editor. You can close the tab or switch to
+another view under _Actions for this Record_ (for example to view it as it appears in the OPAC).
+
+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.
+
+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 Record_.
+
+. Click _OK_ to save record edits.
+
+. 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.
+
+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. For the fixed fields that do not already contain possible values in the database, the user will see the basic clipboard operation options (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 *Actions for this Record*.
+. Click *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.
++
+image::media/ffrc1.jpg[]
++
+. Select the appropriate value for the fixed field from the menu options.
++
+image::media/ffrc2.jpg[]
++
+. Continue editing the MARC record, as needed. Once you are finished editing the record, click *Save Record*.
+
+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).
+
+image::media/ffrc3.jpg[]
+
+MARC Editor users retain the option of leaving the fixed field value blank or entering special values (such as # or | ).
+
+[NOTE]
+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.
+
+++ /dev/null
-Working with the MARC Editor
-----------------------------
-
-You can use the MARC Editor to edit MARC fields, sub-fields, and indicators.
-
-Editing MARC Records
-~~~~~~~~~~~~~~~~~~~~
-
-. Retrieve the record.
-. Actions for this 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.
-* Fast Item Add allows attaching items quickly with call number and barcode. When _Save_ is clicked, the copy editor will open.
-. 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.
-+
-[NOTE]
-==========
-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 Record_. The record stays open in the editor. You can close the tab or switch to
-another view under _Actions for this Record_ (for example to view it as it appears in the OPAC).
-
-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.
-
-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 Record_.
-
-. Click _OK_ to save record edits.
-
-. 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.
-
-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. For the fixed fields that do not already contain possible values in the database, the user will see the basic clipboard operation options (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 *Actions for this Record*.
-. Click *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.
-+
-image::media/ffrc1.jpg[]
-+
-. Select the appropriate value for the fixed field from the menu options.
-+
-image::media/ffrc2.jpg[]
-+
-. Continue editing the MARC record, as needed. Once you are finished editing the record, click *Save Record*.
-
-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).
-
-image::media/ffrc3.jpg[]
-
-MARC Editor users retain the option of leaving the fixed field value blank or entering special values (such as # or | ).
-
-[NOTE]
-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.
-
--- /dev/null
+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).
+
+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.
+
+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.
+
+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
+
+++ /dev/null
-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).
-
-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.
-
-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.
-
-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
-
--- /dev/null
+Managing Authorities
+--------------------
+This section describes how you can create, import, view, modify, merge, and delete authority records in Evergreen.
+
+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.
+
+
+[[_importing_authority_records_from_the_staff_client]]
+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.
+
+
+[TIP]
+=================
+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.
+=================
+
+
+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.
+
+[NOTE]
+=================
+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.
+=================
+
+[TIP]
+=================
+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.
+=================
+
+Manage Authorities Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Evergreen to view, edit, merge, and delete authority records you would use the *Manage Authorities* interface
+through the *Cataloging* menu.
+
+
+
+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
+
+
+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.
+
+[TIP]
+=================
+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.
+=================
+
+++ /dev/null
-Managing Authorities
---------------------
-This section describes how you can create, import, view, modify, merge, and delete authority records in Evergreen.
-
-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.
-
-
-[[_importing_authority_records_from_the_staff_client]]
-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.
-
-
-[TIP]
-=================
-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.
-=================
-
-
-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.
-
-[NOTE]
-=================
-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.
-=================
-
-[TIP]
-=================
-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.
-=================
-
-Manage Authorities Interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In Evergreen to view, edit, merge, and delete authority records you would use the *Manage Authorities* interface
-through the *Cataloging* menu.
-
-
-
-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
-
-
-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.
-
-[TIP]
-=================
-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.
-=================
-
--- /dev/null
+Batch Importing MARC Records
+----------------------------
+[[batchimport]]
+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.
+
+Permissions
+~~~~~~~~~~~
+
+To use match sets to import records, you will need the following permission:
+
+ADMIN_IMPORT_MATCH_SET
+
+
+Record Display Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature enables you to specify the tags and subfields that will display in
+records that appear in the import queue.
+
+
+[[matchsets]]
+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.
+
+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*.
++
+image::media/Batch_Importing_MARC_Records1.jpg[Batch_Importing_MARC_Records1]
+
+. 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.
++
+image::media/Batch_Importing_MARC_Records2.jpg[Batch_Importing_MARC_Records2]
+
+. Click *Ok.*
+
+. Drag the completed match point under the folder with the
+appropriately-named Boolean folder under the Expression tree.
++
+image::media/Batch_Importing_MARC_Records3.jpg[Batch_Importing_MARC_Records3]
++
+The match point will nest underneath the folder in the Expression tree.
++
+image::media/Batch_Importing_MARC_Records4.jpg[Batch_Importing_MARC_Records4]
+
+. 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.
++
+image::media/Batch_Importing_MARC_Records5.jpg[Batch_Importing_MARC_Records5]
+
+. 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.*
++
+image::media/Batch_Importing_MARC_Records6.jpg[Batch_Importing_MARC_Records6]
+
+. 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*.
++
+image::media/Batch_Importing_MARC_Records7.jpg[Batch_Importing_MARC_Records7]
+
+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*.
+
+
+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*.
++
+image::media/Batch_Importing_MARC_Records8.jpg[Batch_Importing_MARC_Records8]
+
+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.
+
+
+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*.
+
+NOTE: All fields (except for Name, Tag and Keep) can contain static
+values, a MARC subfield code (such as "a"), or an XPATH query.
+
+image::media/batch_import_profile.png[Partial Screenshot of a Holdings Import Profile]
+
+.Holdings Import Profile Fields
+[options="header"]
+|=============================
+|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.
+|Keep | Yes | 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.
+|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 ||
+|==================
+
+
+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.
++
+NOTE: 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.
++
+image::media/marc_batch_import_acq_overlay.png[Batch Importing MARC Records]
+
+. 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.
++
+image::media/Batch_Importing_MARC_Records15.jpg[Batch_Importing_MARC_Records15]
+
+. 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.
++
+image::media/Batch_Importing_MARC_Records10.jpg[Batch_Importing_MARC_Records10]
+
+. 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*.
++
+image::media/marc_batch_import_popup.png[Batch Importing MARC Records Popup]
+
+. 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.
++
+image::media/Batch_Importing_MARC_Records12.jpg[Batch_Importing_MARC_Records12]
+
+. 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.
++
+image::media/Batch_Importing_MARC_Records14.jpg[Batch_Importing_MARC_Records14]
+
+
+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
+
+++ /dev/null
-Batch Importing MARC Records
-----------------------------
-[[batchimport]]
-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.
-
-Permissions
-~~~~~~~~~~~
-
-To use match sets to import records, you will need the following permission:
-
-ADMIN_IMPORT_MATCH_SET
-
-
-Record Display Attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This feature enables you to specify the tags and subfields that will display in
-records that appear in the import queue.
-
-
-[[matchsets]]
-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.
-
-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*.
-+
-image::media/Batch_Importing_MARC_Records1.jpg[Batch_Importing_MARC_Records1]
-
-. 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.
-+
-image::media/Batch_Importing_MARC_Records2.jpg[Batch_Importing_MARC_Records2]
-
-. Click *Ok.*
-
-. Drag the completed match point under the folder with the
-appropriately-named Boolean folder under the Expression tree.
-+
-image::media/Batch_Importing_MARC_Records3.jpg[Batch_Importing_MARC_Records3]
-+
-The match point will nest underneath the folder in the Expression tree.
-+
-image::media/Batch_Importing_MARC_Records4.jpg[Batch_Importing_MARC_Records4]
-
-. 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.
-+
-image::media/Batch_Importing_MARC_Records5.jpg[Batch_Importing_MARC_Records5]
-
-. 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.*
-+
-image::media/Batch_Importing_MARC_Records6.jpg[Batch_Importing_MARC_Records6]
-
-. 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*.
-+
-image::media/Batch_Importing_MARC_Records7.jpg[Batch_Importing_MARC_Records7]
-
-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*.
-
-
-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*.
-+
-image::media/Batch_Importing_MARC_Records8.jpg[Batch_Importing_MARC_Records8]
-
-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.
-
-
-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*.
-
-NOTE: All fields (except for Name, Tag and Keep) can contain static
-values, a MARC subfield code (such as "a"), or an XPATH query.
-
-image::media/batch_import_profile.png[Partial Screenshot of a Holdings Import Profile]
-
-.Holdings Import Profile Fields
-[options="header"]
-|=============================
-|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.
-|Keep | Yes | 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.
-|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 ||
-|==================
-
-
-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.
-+
-NOTE: 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.
-+
-image::media/marc_batch_import_acq_overlay.png[Batch Importing MARC Records]
-
-. 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.
-+
-image::media/Batch_Importing_MARC_Records15.jpg[Batch_Importing_MARC_Records15]
-
-. 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.
-+
-image::media/Batch_Importing_MARC_Records10.jpg[Batch_Importing_MARC_Records10]
-
-. 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*.
-+
-image::media/marc_batch_import_popup.png[Batch Importing MARC Records Popup]
-
-. 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.
-+
-image::media/Batch_Importing_MARC_Records12.jpg[Batch_Importing_MARC_Records12]
-
-. 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.
-+
-image::media/Batch_Importing_MARC_Records14.jpg[Batch_Importing_MARC_Records14]
-
-
-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
-
--- /dev/null
+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.
+
+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.
++
+[NOTE]
+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
+
+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.
+
+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.
+
+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);+
+
+[NOTE]
+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.
+
+
+++ /dev/null
-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.
-
-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.
-+
-[NOTE]
-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
-
-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.
-
-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.
-
-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);+
-
-[NOTE]
-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.
-
-
--- /dev/null
+Cataloging in the Web Client
+----------------------------
+
+Cataloguers should use this part for understanding the cataloguing procedures used in Evergreen.
+
+
+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.
+
+++ /dev/null
-Cataloging in the Web Client
-----------------------------
-
-Cataloguers should use this part for understanding the cataloguing procedures used in Evergreen.
-
-
-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.
-
--- /dev/null
+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.
+
+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
+
+1. Retrieve the bibliographic record to which you would like to link an item.
+
+2. Click *Actions for this Record -> Mark as Target for Conjoined Items.*
++
+image::media/conjoined_menu_markfor.png[Menu: Mark as Target for Conjoined Items]
+
+3. A confirmation message will appear. Click *OK.*
+
+4. In a new tab, retrieve the bibliographic record with the item that
+you want to link to the other record.
+
+5. Click *Actions for this Record -> Holdings Maintenance.*
+
+6. 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.*
++
+image::media/conj2.jpg[conj2]
+
+7. 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.
++
+image::media/conj3.jpg[conj3]
++
+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.*
++
+image::media/conj4.jpg[conj4]
+
+8. The *Result* column will indicate that the *Peer Type* [has been] *Updated.*
++
+image::media/conj5.jpg[conj5]
+
+9. 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.
++
+image::media/conjoined_opac.png[Catalog Record showing Conjoined Item link]
+
+
+.Scenario 2: I want to link an item to another bibliographic record, and I do have the item in hand
+
+1. Retrieve the bibliographic record to which you would like to add the item.
+
+2. Click *Actions for this Record -> Manage Conjoined Items.*
++
+image::media/conjoined_menu_markfor.png[Menu: Manage Conjoined Items]
+
+3. 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.
+
+4. 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.
+
+5. Click *Link to Bib (Submit).*
++
+image::media/conj10.jpg[conj10]
+
+6. The linked item will appear in the screen. The *Result* column indicates Success.
+
+7. To confirm the linkage, click *Actions for this Record -> OPAC View.*
+
+8. 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
+
+1. Retrieve the bibliographic record that has a copy linked to it.
+
+2. Click *Actions for this Record -> Manage Conjoined Items.*
+
+3. Select the copy that you want to edit, and right-click or click
+*Actions for Selected Items.*
+
+4. Make any changes, and click *OK.*
+
+
+UPDATE_COPY - Link items to bibliographic records
+++ /dev/null
-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.
-
-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
-
-1. Retrieve the bibliographic record to which you would like to link an item.
-
-2. Click *Actions for this Record -> Mark as Target for Conjoined Items.*
-+
-image::media/conjoined_menu_markfor.png[Menu: Mark as Target for Conjoined Items]
-
-3. A confirmation message will appear. Click *OK.*
-
-4. In a new tab, retrieve the bibliographic record with the item that
-you want to link to the other record.
-
-5. Click *Actions for this Record -> Holdings Maintenance.*
-
-6. 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.*
-+
-image::media/conj2.jpg[conj2]
-
-7. 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.
-+
-image::media/conj3.jpg[conj3]
-+
-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.*
-+
-image::media/conj4.jpg[conj4]
-
-8. The *Result* column will indicate that the *Peer Type* [has been] *Updated.*
-+
-image::media/conj5.jpg[conj5]
-
-9. 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.
-+
-image::media/conjoined_opac.png[Catalog Record showing Conjoined Item link]
-
-
-.Scenario 2: I want to link an item to another bibliographic record, and I do have the item in hand
-
-1. Retrieve the bibliographic record to which you would like to add the item.
-
-2. Click *Actions for this Record -> Manage Conjoined Items.*
-+
-image::media/conjoined_menu_markfor.png[Menu: Manage Conjoined Items]
-
-3. 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.
-
-4. 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.
-
-5. Click *Link to Bib (Submit).*
-+
-image::media/conj10.jpg[conj10]
-
-6. The linked item will appear in the screen. The *Result* column indicates Success.
-
-7. To confirm the linkage, click *Actions for this Record -> OPAC View.*
-
-8. 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
-
-1. Retrieve the bibliographic record that has a copy linked to it.
-
-2. Click *Actions for this Record -> Manage Conjoined Items.*
-
-3. Select the copy that you want to edit, and right-click or click
-*Actions for Selected Items.*
-
-4. Make any changes, and click *OK.*
-
-
-UPDATE_COPY - Link items to bibliographic records
--- /dev/null
+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*.
+
+image::media/copy-bucket-2.png[Cataloguing Menu]
+
+NOTE: The words _copy_ and _item_ are used interchangeably in Evergreen.
+
+Managing Copy Buckets
+~~~~~~~~~~~~~~~~~~~~~
+
+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).
+
+1. In the _Copy Bucket_ interface on the click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
++
+image::media/copy-bucket-new-1.png[Copy Bucket Interface]
++
+2. From the drop down menu select *New Bucket*.
++
+image::media/copy-bucket-new-2.png[Copy Bucket Interface]
++
+3. Enter a _Name_ and a _Description_ (optional) for your bucket and click *Create Bucket*.
++
+image::media/copy-bucket-new-3.png[Copy Bucket Interface]
++
+The bucket can also be set as _Publicly Visible_ at this time.
+
+NOTE: The functionality for making buckets publicly visible does not appear to be in place at this time.
+
+Editing Copy Buckets
+^^^^^^^^^^^^^^^^^^^^
+
+1. In the _Copy Bucket_ interface click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
++
+image::media/copy-bucket-new-1.png[Copy Bucket Interface]
++
+2. From the drop down menu select the bucket you would like to edit. The bucket will load in the interface.
+3. Click on *Buckets*.
+4. From the drop down menu select *Edit Bucket*.
++
+image::media/copy-bucket-edit-1.png[Copy Bucket Interface]
++
+5. Update the desired information and click *Apply Changes*.
++
+image::media/copy-bucket-edit-2.png[Copy Bucket Interface]
+
+NOTE: The functionality for making buckets publicly visible does not appear to be in place at this time.
+
+Sharing Copy Buckets
+^^^^^^^^^^^^^^^^^^^^
+
+Finding the Bucket ID
++++++++++++++++++++++
+
+1. 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.
+
+image::media/copy-bucket-share-1.png[Bucket ID URL]
+
+Opening a Shared Bucket
++++++++++++++++++++++++
+
+1. In the _Copy Bucket_ interface click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
++
+image::media/copy-bucket-new-1.png[Copy Bucket Interface]
++
+3. From the drop down menu select *Shared Bucket*.
++
+image::media/copy-bucket-share-2.png[Copy Bucket Interface]
++
+4. Enter the bucket ID and click *Load Bucket*.
++
+image::media/copy-bucket-share-3.png[Copy Bucket Interface]
++
+5. The shared bucket will display and can be worked with the same as any bucket you own.
++
+image::media/copy-bucket-share-4.png[Copy Bucket Interface]
+
+Deleting Copy Buckets
+^^^^^^^^^^^^^^^^^^^^^
+
+1. In the _Copy Bucket_ interface click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
++
+image::media/copy-bucket-new-1.png[Copy Bucket Interface]
++
+2. From the drop down menu select the bucket you would like to delete. The bucket will load in the interface.
+3. Click on *Buckets*.
+4. From the drop down menu select *Delete Bucket*.
++
+image::media/copy-bucket-delete-1.png[Copy Bucket Interface]
++
+5. On the confirmation pop up click *Delete Bucket*.
+6. Refresh your screen.
+
+
+Adding Copies to a Bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From the Copy Bucket Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. In the _Copy Bucket_ interface click on the *Pending Copies* tab.
++
+image::media/copy-bucket-pending-1.png[Copy Bucket Interface]
++
+2. Scan in all of the items you wish to add to the bucket.
++
+image::media/copy-bucket-pending-3.png[Copy Bucket Interface]
++
+3. Click on *Buckets*.
+4. 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).
++
+image::media/copy-bucket-pending-2.png[Copy Bucket Interface]
++
+5. Use the check boxes to select the item(s) you wish to add to the bucket.
+6. Click *Actions*.
+7. From the drop down menu select *Add To Bucket*.
++
+image::media/copy-bucket-pending-4.png[Copy Bucket Interface]
++
+8. The number of items in the bucket, displayed beside the bucket name, will update as will the number on the *Bucket View* tab.
++
+image::media/copy-bucket-pending-5.png[Copy Bucket Interface]
+
+NOTE: 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.
+
+
+From a Catalogue Search
+^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Retrieve the title through a catalogue search.
+2. If it is not your default view click on the *Holdings View* tab.
++
+image::media/copy-bucket-cat-1.png[Holdings View]
++
+3. Use the check boxes to select the item(s) you would like to add to the bucket.
+4. Click *Actions*.
+5. From the drop down menu select *Add Items to Bucket*
++
+image::media/copy-bucket-cat-2.png[Holdings View]
++
+6. Enter a name for your bucket or select an existing from the drop down menu.
+7. Click *Add To New Bucket* or *Add To Selected Bucket*.
++
+image::media/copy-bucket-cat-3.png[Copy Bucket Interface]
++
+8. Repeat steps 1 through 7 to add additional copies.
+
+
+From the Item Status Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+NOTE: Functionality currently missing.
+
+Removing Copies from a Bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
++
+image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
++
+3. Click on *Buckets*.
+4. From the drop down menu select the bucket containing the item(s) you would like to remove.
++
+image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
++
+5. Use the check boxes to select the item(s) you wish to remove from the bucket.
+6. Click *Actions*.
+7. From the drop down menu select *Remove Selected Copies from Bucket*.
++
+image::media/copy-bucket-remove-3.png[Copy Bucket Interface]
++
+8. Your bucket will reload and the selected item(s) will no longer be in the bucket.
+
+Editing Copies in a Bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
++
+image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
++
+3. Click on *Buckets*.
+4. From the drop down menu select the bucket containing the item(s) you would like to edit.
++
+image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
++
+5. Use the check boxes to select the item(s) you wish to edit.
+6. Click *Actions*.
+7. From the drop down menu select *Edit Selected Copies*.
++
+image::media/copy-bucket-edit-copy-1.png[Copy Bucket Interface]
++
+8. The _Copy Editor_ will open in a new tab. Make your edits and then click *Save and Exit*.
++
+image::media/copy-bucket-edit-copy-2.png[Copy Bucket Interface]
++
+9. Your items have been updated.
++
+image::media/copy-bucket-edit-copy-3.png[Copy Bucket Interface]
+
+Deleting Copies from the Catalogue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
++
+image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
++
+3. Click on *Buckets*.
+4. From the drop down menu select the bucket containing the item(s) you would like to delete from the catalogue.
++
+image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
++
+5. Use the check boxes to select the item(s) you wish to delete.
+6. Click *Actions*.
+7. From the drop down menu select *Delete Selected Copies from Catalog*.
++
+image::media/copy-bucket-delete-copy-1.png[Copy Bucket Interface]
++
+8. On the confirmation pop up click *OK/Continue*.
++
+image::media/copy-bucket-delete-copy-2.png[Copy Bucket Interface]
++
+9. The items have been deleted from the catalogue.
+
+
+Placing Holds on Copies in a Bucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
++
+image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
++
+3. Click on *Buckets*.
+4. From the drop down menu select the bucket containing the item(s) you would like to place a hold on.
++
+image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
++
+5. Use the check boxes to select the item(s) you wish to delete.
+6. Click *Actions*.
+7. From the drop down menu select *Request Seleted Copies*.
++
+image::media/copy-bucket-request-1.png[Copy Bucket Interface]
++
+8. 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.
++
+image::media/copy-bucket-request-2.png[Copy Bucket Interface]
++
+9. Select the correct _Pickup Library_.
+10. Select the correct _Hold Type_. (More explanation of the hold types needed here.)
+11. Click *OK*.
+12. The hold has been placed.
+
+
+Transferring Copies to Volumes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Retrieve the title through a catalogue search.
+2. If it is not your default view click on the *Holdings View* tab.
++
+image::media/copy-bucket-cat-1.png[Holdings View]
++
+3. Use the check boxes to select the volume you would like to transfer the item(s) to.
+4. Click *Actions*.
+5. From the drop down menu select *Volume as Item Transfer Destination*
++
+image::media/copy-bucket-transfer-1.png[Holdings View]
++
+6. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
++
+image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
++
+7. Click on *Buckets*.
+8. From the drop down menu select the bucket containing the item(s) you would like to transfer to the volume.
++
+image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
++
+9. Use the check boxes to select the item(s) you wish to transfer.
+10. Click *Actions*.
+11. From the drop down menu select *Transfer Selected Copies to Marked Volume*.
++
+image::media/copy-bucket-transfer-2.png[Copy Bucket Interface]
++
+12. The item(s) is transferred.
++
+image::media/copy-bucket-transfer-3.png[Copy Bucket Interface]
+
+
+
+
+
+
+++ /dev/null
-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*.
-
-image::media/copy-bucket-2.png[Cataloguing Menu]
-
-NOTE: The words _copy_ and _item_ are used interchangeably in Evergreen.
-
-Managing Copy Buckets
-~~~~~~~~~~~~~~~~~~~~~
-
-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).
-
-1. In the _Copy Bucket_ interface on the click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
-+
-image::media/copy-bucket-new-1.png[Copy Bucket Interface]
-+
-2. From the drop down menu select *New Bucket*.
-+
-image::media/copy-bucket-new-2.png[Copy Bucket Interface]
-+
-3. Enter a _Name_ and a _Description_ (optional) for your bucket and click *Create Bucket*.
-+
-image::media/copy-bucket-new-3.png[Copy Bucket Interface]
-+
-The bucket can also be set as _Publicly Visible_ at this time.
-
-NOTE: The functionality for making buckets publicly visible does not appear to be in place at this time.
-
-Editing Copy Buckets
-^^^^^^^^^^^^^^^^^^^^
-
-1. In the _Copy Bucket_ interface click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
-+
-image::media/copy-bucket-new-1.png[Copy Bucket Interface]
-+
-2. From the drop down menu select the bucket you would like to edit. The bucket will load in the interface.
-3. Click on *Buckets*.
-4. From the drop down menu select *Edit Bucket*.
-+
-image::media/copy-bucket-edit-1.png[Copy Bucket Interface]
-+
-5. Update the desired information and click *Apply Changes*.
-+
-image::media/copy-bucket-edit-2.png[Copy Bucket Interface]
-
-NOTE: The functionality for making buckets publicly visible does not appear to be in place at this time.
-
-Sharing Copy Buckets
-^^^^^^^^^^^^^^^^^^^^
-
-Finding the Bucket ID
-+++++++++++++++++++++
-
-1. 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.
-
-image::media/copy-bucket-share-1.png[Bucket ID URL]
-
-Opening a Shared Bucket
-+++++++++++++++++++++++
-
-1. In the _Copy Bucket_ interface click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
-+
-image::media/copy-bucket-new-1.png[Copy Bucket Interface]
-+
-3. From the drop down menu select *Shared Bucket*.
-+
-image::media/copy-bucket-share-2.png[Copy Bucket Interface]
-+
-4. Enter the bucket ID and click *Load Bucket*.
-+
-image::media/copy-bucket-share-3.png[Copy Bucket Interface]
-+
-5. The shared bucket will display and can be worked with the same as any bucket you own.
-+
-image::media/copy-bucket-share-4.png[Copy Bucket Interface]
-
-Deleting Copy Buckets
-^^^^^^^^^^^^^^^^^^^^^
-
-1. In the _Copy Bucket_ interface click *Buckets* in either the _Pending Copies_ or _Bucket View_ tab.
-+
-image::media/copy-bucket-new-1.png[Copy Bucket Interface]
-+
-2. From the drop down menu select the bucket you would like to delete. The bucket will load in the interface.
-3. Click on *Buckets*.
-4. From the drop down menu select *Delete Bucket*.
-+
-image::media/copy-bucket-delete-1.png[Copy Bucket Interface]
-+
-5. On the confirmation pop up click *Delete Bucket*.
-6. Refresh your screen.
-
-
-Adding Copies to a Bucket
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-From the Copy Bucket Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-1. In the _Copy Bucket_ interface click on the *Pending Copies* tab.
-+
-image::media/copy-bucket-pending-1.png[Copy Bucket Interface]
-+
-2. Scan in all of the items you wish to add to the bucket.
-+
-image::media/copy-bucket-pending-3.png[Copy Bucket Interface]
-+
-3. Click on *Buckets*.
-4. 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).
-+
-image::media/copy-bucket-pending-2.png[Copy Bucket Interface]
-+
-5. Use the check boxes to select the item(s) you wish to add to the bucket.
-6. Click *Actions*.
-7. From the drop down menu select *Add To Bucket*.
-+
-image::media/copy-bucket-pending-4.png[Copy Bucket Interface]
-+
-8. The number of items in the bucket, displayed beside the bucket name, will update as will the number on the *Bucket View* tab.
-+
-image::media/copy-bucket-pending-5.png[Copy Bucket Interface]
-
-NOTE: 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.
-
-
-From a Catalogue Search
-^^^^^^^^^^^^^^^^^^^^^^^
-
-1. Retrieve the title through a catalogue search.
-2. If it is not your default view click on the *Holdings View* tab.
-+
-image::media/copy-bucket-cat-1.png[Holdings View]
-+
-3. Use the check boxes to select the item(s) you would like to add to the bucket.
-4. Click *Actions*.
-5. From the drop down menu select *Add Items to Bucket*
-+
-image::media/copy-bucket-cat-2.png[Holdings View]
-+
-6. Enter a name for your bucket or select an existing from the drop down menu.
-7. Click *Add To New Bucket* or *Add To Selected Bucket*.
-+
-image::media/copy-bucket-cat-3.png[Copy Bucket Interface]
-+
-8. Repeat steps 1 through 7 to add additional copies.
-
-
-From the Item Status Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-NOTE: Functionality currently missing.
-
-Removing Copies from a Bucket
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
-+
-image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
-+
-3. Click on *Buckets*.
-4. From the drop down menu select the bucket containing the item(s) you would like to remove.
-+
-image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
-+
-5. Use the check boxes to select the item(s) you wish to remove from the bucket.
-6. Click *Actions*.
-7. From the drop down menu select *Remove Selected Copies from Bucket*.
-+
-image::media/copy-bucket-remove-3.png[Copy Bucket Interface]
-+
-8. Your bucket will reload and the selected item(s) will no longer be in the bucket.
-
-Editing Copies in a Bucket
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
-+
-image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
-+
-3. Click on *Buckets*.
-4. From the drop down menu select the bucket containing the item(s) you would like to edit.
-+
-image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
-+
-5. Use the check boxes to select the item(s) you wish to edit.
-6. Click *Actions*.
-7. From the drop down menu select *Edit Selected Copies*.
-+
-image::media/copy-bucket-edit-copy-1.png[Copy Bucket Interface]
-+
-8. The _Copy Editor_ will open in a new tab. Make your edits and then click *Save and Exit*.
-+
-image::media/copy-bucket-edit-copy-2.png[Copy Bucket Interface]
-+
-9. Your items have been updated.
-+
-image::media/copy-bucket-edit-copy-3.png[Copy Bucket Interface]
-
-Deleting Copies from the Catalogue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
-+
-image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
-+
-3. Click on *Buckets*.
-4. From the drop down menu select the bucket containing the item(s) you would like to delete from the catalogue.
-+
-image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
-+
-5. Use the check boxes to select the item(s) you wish to delete.
-6. Click *Actions*.
-7. From the drop down menu select *Delete Selected Copies from Catalog*.
-+
-image::media/copy-bucket-delete-copy-1.png[Copy Bucket Interface]
-+
-8. On the confirmation pop up click *OK/Continue*.
-+
-image::media/copy-bucket-delete-copy-2.png[Copy Bucket Interface]
-+
-9. The items have been deleted from the catalogue.
-
-
-Placing Holds on Copies in a Bucket
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
-+
-image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
-+
-3. Click on *Buckets*.
-4. From the drop down menu select the bucket containing the item(s) you would like to place a hold on.
-+
-image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
-+
-5. Use the check boxes to select the item(s) you wish to delete.
-6. Click *Actions*.
-7. From the drop down menu select *Request Seleted Copies*.
-+
-image::media/copy-bucket-request-1.png[Copy Bucket Interface]
-+
-8. 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.
-+
-image::media/copy-bucket-request-2.png[Copy Bucket Interface]
-+
-9. Select the correct _Pickup Library_.
-10. Select the correct _Hold Type_. (More explanation of the hold types needed here.)
-11. Click *OK*.
-12. The hold has been placed.
-
-
-Transferring Copies to Volumes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Retrieve the title through a catalogue search.
-2. If it is not your default view click on the *Holdings View* tab.
-+
-image::media/copy-bucket-cat-1.png[Holdings View]
-+
-3. Use the check boxes to select the volume you would like to transfer the item(s) to.
-4. Click *Actions*.
-5. From the drop down menu select *Volume as Item Transfer Destination*
-+
-image::media/copy-bucket-transfer-1.png[Holdings View]
-+
-6. Open the _Copy Bucket_ interface. By default you are on the *Bucket View* tab.
-+
-image::media/copy-bucket-remove-1.png[Copy Bucket Interface]
-+
-7. Click on *Buckets*.
-8. From the drop down menu select the bucket containing the item(s) you would like to transfer to the volume.
-+
-image::media/copy-bucket-remove-2.png[Copy Bucket Interface]
-+
-9. Use the check boxes to select the item(s) you wish to transfer.
-10. Click *Actions*.
-11. From the drop down menu select *Transfer Selected Copies to Marked Volume*.
-+
-image::media/copy-bucket-transfer-2.png[Copy Bucket Interface]
-+
-12. The item(s) is transferred.
-+
-image::media/copy-bucket-transfer-3.png[Copy Bucket Interface]
-
-
-
-
-
-
--- /dev/null
+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.
+
+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.
+
+image::media/Link_Checker1.jpg[Link_Checker1]
+
+
+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.
+
+image::media/Link_Checker2.jpg[Link_Checker2]
+
+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.
+
+image::media/Link_Checker6.jpg[Link_Checker6]
+
+Manage Your Sessions
+~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+
+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.
+
+
+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.
+
+++ /dev/null
-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.
-
-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.
-
-image::media/Link_Checker1.jpg[Link_Checker1]
-
-
-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.
-
-image::media/Link_Checker2.jpg[Link_Checker2]
-
-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.
-
-image::media/Link_Checker6.jpg[Link_Checker6]
-
-Manage Your Sessions
-~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-
-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.
-
-
-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.
-
--- /dev/null
+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.
+
+
+Add a Monograph Part to an Existing Record
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add a monograph part to an existing record in the catalog:
+
+1. Retrieve a record.
+
+2. Click *Actions for this Record -> Manage Parts*
++
+image::media/manage_parts_menu.png[Menu: Manage Parts]
+
+3. Click *New Monograph Part*
+
+4. 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.
++
+image::media/monograph_parts2.jpg[monograph_parts2]
+
+5. 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*.
++
+image::media/monograph_parts3.jpg[monograph_parts3]
+
+6. The *Unified Volume/Copy Creator* opens. Enter the number of volumes
+that you want to add to the catalog and the volume description.
+
+7. Enter the number of copies and barcode(s) of each item.
+
+8. Select the *part designation* from the drop down menu adjacent to the barcode field.
+
+9. Apply a template to the copies, or edit fields in the *Copy Editor*.
++
+image::media/monograph_parts4.jpg[monograph_parts4]
+
+10. Click *Create Volumes/Items*.
+
+11. The *Holdings Maintenance* screen will refresh to demonstrate the
+addition of the part information. These fields also appear in the OPAC
+View.
++
+image::media/manage_parts_opac.png[Catalog Record showing copies with part details]
+
+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.{nbsp}1++ may have variants
+like ++V.1++, ++Vol{nbsp}1++, or ++{nbsp}Vol.{nbsp}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
+++ /dev/null
-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.
-
-
-Add a Monograph Part to an Existing Record
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To add a monograph part to an existing record in the catalog:
-
-1. Retrieve a record.
-
-2. Click *Actions for this Record -> Manage Parts*
-+
-image::media/manage_parts_menu.png[Menu: Manage Parts]
-
-3. Click *New Monograph Part*
-
-4. 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.
-+
-image::media/monograph_parts2.jpg[monograph_parts2]
-
-5. 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*.
-+
-image::media/monograph_parts3.jpg[monograph_parts3]
-
-6. The *Unified Volume/Copy Creator* opens. Enter the number of volumes
-that you want to add to the catalog and the volume description.
-
-7. Enter the number of copies and barcode(s) of each item.
-
-8. Select the *part designation* from the drop down menu adjacent to the barcode field.
-
-9. Apply a template to the copies, or edit fields in the *Copy Editor*.
-+
-image::media/monograph_parts4.jpg[monograph_parts4]
-
-10. Click *Create Volumes/Items*.
-
-11. The *Holdings Maintenance* screen will refresh to demonstrate the
-addition of the part information. These fields also appear in the OPAC
-View.
-+
-image::media/manage_parts_opac.png[Catalog Record showing copies with part details]
-
-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.{nbsp}1++ may have variants
-like ++V.1++, ++Vol{nbsp}1++, or ++{nbsp}Vol.{nbsp}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
--- /dev/null
+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*.
+
+image::media/Overlay_Existing_Record_via_Z39_50_Import1.jpg[]
+
+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*
+
+
+image::media/Overlay_Existing_Record_via_Z39_50_Import2.jpg[]
+
+
+8) A confirmation message appears. Click *OK*.
+
+9) Select the record that you want to replace the existing catalog record.
+
+10) Click *Overlay.*
+
+
+image::media/Overlay_Existing_Record_via_Z39_50_Import3.jpg[]
+
+
+11) The record that you selected will open in the MARC Editor. Make any desired changes to the record, and click *Overlay Record*.
+
+image::media/Overlay_Existing_Record_via_Z39_50_Import4.jpg[]
+
+
+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*.
+
+
+image::media/Overlay_Existing_Record_via_Z39_50_Import5.jpg[]
+
+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.
+
+
+image::media/Overlay_Existing_Record_via_Z39_50_Import6.jpg[]
+++ /dev/null
-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*.
-
-image::media/Overlay_Existing_Record_via_Z39_50_Import1.jpg[]
-
-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*
-
-
-image::media/Overlay_Existing_Record_via_Z39_50_Import2.jpg[]
-
-
-8) A confirmation message appears. Click *OK*.
-
-9) Select the record that you want to replace the existing catalog record.
-
-10) Click *Overlay.*
-
-
-image::media/Overlay_Existing_Record_via_Z39_50_Import3.jpg[]
-
-
-11) The record that you selected will open in the MARC Editor. Make any desired changes to the record, and click *Overlay Record*.
-
-image::media/Overlay_Existing_Record_via_Z39_50_Import4.jpg[]
-
-
-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*.
-
-
-image::media/Overlay_Existing_Record_via_Z39_50_Import5.jpg[]
-
-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.
-
-
-image::media/Overlay_Existing_Record_via_Z39_50_Import6.jpg[]
--- /dev/null
+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 *Actions for this Record*.
+. Click *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.
++
+image::media/pcw1.jpg[]
++
+. Click *Add/Replace 007*. The 007 row will appear in the record.
+. Right-click in the 007 textbox field.
++
+image::media/pcw2.jpg[]
++
+. Click *Physical Characteristics Wizard*.
+
+image::media/pcw3.jpg[]
+
+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 pipe symbol (vertical bar) for each position that represents a potential value for the selected Category of Material and will skip obsolete values.
+
+image::media/pcw4.jpg[]
+
+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.
+
+image::media/pcw5.jpg[]
+
+As a visual reference, the position that the wizard is displaying will appear in bold font. That way, users know which position they are working on at any given point within the wizard.
+
+image::media/pcw6.jpg[]
+
+Once the user enters all of the applicable values for the 007 field and is ready to exit the wizard, click *OK*.
+
+image::media/pcw7.jpg[]
+
+All of the values selected will be stored and displayed within the 007 field of the bibliographic record.
+
+image::media/pcw8.jpg[]
+
+Continue editing the MARC record, as needed. Once the user is finished editing the record, click *Save Record*.
+
+image::media/pcw9.jpg[]
+
+*To Access the MARC 007 Field Physical Characteristics Wizard for a Record that Already Contains the 007 Field (i.e. Edit an Existing 007 Field):*
+
+. Within the bibliographic record that needs to be edited, select *Actions for this Record*.
+. Click *MARC Edit*.
+. Right-click in the 007 textbox field.
+. Click *Physical Characteristics Wizard*.
++
+image::media/pcw10.jpg[]
++
+. Click the *Previous* and *Next* buttons to navigate forward and backward through the various positions. The current position that the wizard is on will be indicated by bold font.
+. Each position will display a label that describes the significance of that position. For the position that needs to be edited, choose its appropriate value from the dropdown options.
++
+image::media/pcw11.jpg[]
++
+. Once all edits of the 007 field are made, click *OK*.
+. After finishing all other edits to the MARC record, click *Save Record*.
+
+[NOTE]
+If the user edits an existing 007 field that does not already account for the skipped positions, then Evergreen will not automatically generate where the skipped positions should be in the 007 field. It is recommended that users delete the existing 007 field and start with a new 007 field, to ensure that Evergreen appropriately accounts for the obsolete positions for the Category of Material selected.
+
+*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.
+
+++ /dev/null
-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 *Actions for this Record*.
-. Click *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.
-+
-image::media/pcw1.jpg[]
-+
-. Click *Add/Replace 007*. The 007 row will appear in the record.
-. Right-click in the 007 textbox field.
-+
-image::media/pcw2.jpg[]
-+
-. Click *Physical Characteristics Wizard*.
-
-image::media/pcw3.jpg[]
-
-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 pipe symbol (vertical bar) for each position that represents a potential value for the selected Category of Material and will skip obsolete values.
-
-image::media/pcw4.jpg[]
-
-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.
-
-image::media/pcw5.jpg[]
-
-As a visual reference, the position that the wizard is displaying will appear in bold font. That way, users know which position they are working on at any given point within the wizard.
-
-image::media/pcw6.jpg[]
-
-Once the user enters all of the applicable values for the 007 field and is ready to exit the wizard, click *OK*.
-
-image::media/pcw7.jpg[]
-
-All of the values selected will be stored and displayed within the 007 field of the bibliographic record.
-
-image::media/pcw8.jpg[]
-
-Continue editing the MARC record, as needed. Once the user is finished editing the record, click *Save Record*.
-
-image::media/pcw9.jpg[]
-
-*To Access the MARC 007 Field Physical Characteristics Wizard for a Record that Already Contains the 007 Field (i.e. Edit an Existing 007 Field):*
-
-. Within the bibliographic record that needs to be edited, select *Actions for this Record*.
-. Click *MARC Edit*.
-. Right-click in the 007 textbox field.
-. Click *Physical Characteristics Wizard*.
-+
-image::media/pcw10.jpg[]
-+
-. Click the *Previous* and *Next* buttons to navigate forward and backward through the various positions. The current position that the wizard is on will be indicated by bold font.
-. Each position will display a label that describes the significance of that position. For the position that needs to be edited, choose its appropriate value from the dropdown options.
-+
-image::media/pcw11.jpg[]
-+
-. Once all edits of the 007 field are made, click *OK*.
-. After finishing all other edits to the MARC record, click *Save Record*.
-
-[NOTE]
-If the user edits an existing 007 field that does not already account for the skipped positions, then Evergreen will not automatically generate where the skipped positions should be in the 007 field. It is recommended that users delete the existing 007 field and start with a new 007 field, to ensure that Evergreen appropriately accounts for the obsolete positions for the Category of Material selected.
-
-*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.
-
--- /dev/null
+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*.
+
+image::media/copy_edit_link_1.jpg[Copy Edit Link]
+
+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.
+
+++ /dev/null
-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*.
-
-image::media/copy_edit_link_1.jpg[Copy Edit Link]
-
-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.
-
--- /dev/null
+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.
+
+image::media/Locate_Z39_50_Matches4.jpg[Locate_Z39.50_Matches4]
+
+
+
+*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*.
+
+image::media/Locate_Z39_50_Matches1.jpg[Locate_Z39.50_Matches1]
+
+. 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*.
+
+image::media/Locate_Z39_50_Matches2.jpg[Locate_Z39.50_Matches2]
+
+. 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*.
+
+image::media/Locate_Z39_50_Matches3.jpg[Locate_Z39.50_Matches3]
+
+. 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.
+
+++ /dev/null
-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.
-
-image::media/Locate_Z39_50_Matches4.jpg[Locate_Z39.50_Matches4]
-
-
-
-*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*.
-
-image::media/Locate_Z39_50_Matches1.jpg[Locate_Z39.50_Matches1]
-
-. 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*.
-
-image::media/Locate_Z39_50_Matches2.jpg[Locate_Z39.50_Matches2]
-
-. 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*.
-
-image::media/Locate_Z39_50_Matches3.jpg[Locate_Z39.50_Matches3]
-
-. 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.
-
--- /dev/null
+Circulation Limits
+==================
+Thomas Berezansky <tsbere@mvlc.org>
+:Date: 2011-10-14
+
+== Limit Groups
+
+Limit Groups can be thought of as "Tags" the system places on circulations so
+that it can find them later. They are placed on circulations based on
+association with Limit Sets.
+
+Limit Groups are global, like Circulation Modifiers, and are edited via the
+Admin->Server Administration->Circulation Limit Groups menu.
+
+Limit Groups are selected by their Name, but support an optional description.
+This description may be useful for storing why a given group was created, or
+what it is intended for.
+
+== Limit Sets
+
+Limit Sets define rules for limiting the number of active circulations a patron
+may have based on Circulation Modifiers and Limit Groups. They support a number
+of options:
+
+Owning Library:: The library that that "owns" the limit set and can edit the
+parameters it contains.
+Name:: The name used to select the limit set when attaching it to Circulation
+Matchpoints.
+Items Out:: The maximum number of items from the associated Circulation
+Modifiers and Limit Groups allowed to be checked out. If set to zero (0) then no
+limiting will be done, but Limit Groups may still be tagged.
+Min Depth:: The minimum depth in the org tree to consider as valid circulation
+libraries for counting, based on Org Unit Type depths.
+Global:: If enabled then treat the Min Depth setting as defining the "Root" of
+the tree, and then include the entire tree below the "Root". Otherwise only
+direct ancestors and descendants of the circulation library will be checked.
+Description:: A description that may be used to describe what purpose the limit
+set is supposed to be serving.
+
+Limit Sets support linking Circulation Modifiers and Limit Groups, and count
+circulations that match any of them. Care has been taken to ensure that even if
+a circulation matches multiple criteria it will only be counted once per Limit
+Set, however.
+
+Limit Sets are configured via the Admin->Local Administration->Circulation Limit
+Sets menu.
+
+=== A Min Depth/Global Example
+
+The Min Depth and Global options are fairly hard to just describe, so lets look
+at a quick example using the default org tree:
+
+* CONS
+** SYS1
+*** BR1
+**** SL1
+*** BR2
+** SYS2
+*** BR3
+**** BM1
+*** BR4
+
+The tree has depths of 0 (CONS) through 3 (SL1/BM1). Using BR1 as a consistent
+circulation library we can build a table of Depth/Global combinations and
+expected included libraries:
+
+.BR1 Depth/Global comparisons
+[options="header"]
+|===============================
+|Depth|Global|Included Libraries
+|0 |False |CONS,SYS1,BR1,SL1
+|0 |True |ALL
+|1 |False |SYS1,BR1,SL1
+|1 |True |SYS1,BR1,BR2,SL1
+|2 |False |BR1,SL1
+|2 |True |BR1,SL1
+|3 |False |SL1
+|3 |True |SL1
+|===============================
+
+== "Tagging" Circulations
+
+In order to count circulations that have no circulation modifier the system has
+to know how to find them. When using circulation modifiers this is easy, just
+look for circulations with items assigned the modifier. But say you want to be
+able to count every video, regardless of circulation modifiers? That is where
+Limit Groups come in.
+
+Limit Groups are automatically recorded from the circulation policies as the
+Limit Sets are looked over. Those Limit Groups assigned to the Limit Sets that
+are not flagged as "Check Only" will be attached to the circulation so that
+later circulations can find them.
+
+It is possible to make Limit Sets that do not check, but only tag. This is
+accomplished by setting "Items Out" to zero (0).
+
+== Associating Limit Sets with Matchpoints
+
+Limit Sets alone are useless if they are not associated with circulation
+matchpoints. When creating or editing matchpoints you can add, remove, or adjust
+settings on linked Limit Sets.
+
+The options available for an attached limit set are:
+
+Fallthrough:: If enabled the Limit Set will be applied whenever the matchpoint
+matches a potential circulation. If not enabled the limit set will only be
+applied when the matchpoint is the first match for a potential circulation.
+Active:: An inactive Limit Set link will never be checked, for tagging or
+counting.
+
+== Limit Sets on Empty Rules
+
+For limiting without otherwise changing circulation rules you can create an
+"empty" rule and attach one or more Limit Sets to it. In this case an empty rule
+is one that does not set any of the "result" fields, but instead lets everything
+fall through to less specific rules. Top level rules based on Marc Type could be
+created for the sole purpose of attaching Limit Sets that allow 0 "Items Out".
+This would allow for a quick top-level tagging of all circulations by Marc Type,
+without otherwise introducing limits, in the event you have reason to limit
+based on that information later.
+
+== Limit a single library's items, regardless of checkout library
+
+For example, videos from BR2 limited to 5 anywhere:
+
+. Create a Limit Group, say "BR2 Videos"
+. Create a Limit Set:
+* Items Out: 5
+* Min Depth: 0
+* Global: True
+* Limit Groups: "BR2 Videos"
+. Create an "empty" matchpoint that is at the top of the org/permission trees
+with Marc Type g and circ library BR2.
+. Attach your limit set to the matchpoint with Fallthrough enabled.
+
+This should limit BR2's videos to 5 out, no matter where they are being checked
+out. Videos owned by others should be unaffected, even if circulating out of
+BR2.
+++ /dev/null
-Circulation Limits
-==================
-Thomas Berezansky <tsbere@mvlc.org>
-:Date: 2011-10-14
-
-== Limit Groups
-
-Limit Groups can be thought of as "Tags" the system places on circulations so
-that it can find them later. They are placed on circulations based on
-association with Limit Sets.
-
-Limit Groups are global, like Circulation Modifiers, and are edited via the
-Admin->Server Administration->Circulation Limit Groups menu.
-
-Limit Groups are selected by their Name, but support an optional description.
-This description may be useful for storing why a given group was created, or
-what it is intended for.
-
-== Limit Sets
-
-Limit Sets define rules for limiting the number of active circulations a patron
-may have based on Circulation Modifiers and Limit Groups. They support a number
-of options:
-
-Owning Library:: The library that that "owns" the limit set and can edit the
-parameters it contains.
-Name:: The name used to select the limit set when attaching it to Circulation
-Matchpoints.
-Items Out:: The maximum number of items from the associated Circulation
-Modifiers and Limit Groups allowed to be checked out. If set to zero (0) then no
-limiting will be done, but Limit Groups may still be tagged.
-Min Depth:: The minimum depth in the org tree to consider as valid circulation
-libraries for counting, based on Org Unit Type depths.
-Global:: If enabled then treat the Min Depth setting as defining the "Root" of
-the tree, and then include the entire tree below the "Root". Otherwise only
-direct ancestors and descendants of the circulation library will be checked.
-Description:: A description that may be used to describe what purpose the limit
-set is supposed to be serving.
-
-Limit Sets support linking Circulation Modifiers and Limit Groups, and count
-circulations that match any of them. Care has been taken to ensure that even if
-a circulation matches multiple criteria it will only be counted once per Limit
-Set, however.
-
-Limit Sets are configured via the Admin->Local Administration->Circulation Limit
-Sets menu.
-
-=== A Min Depth/Global Example
-
-The Min Depth and Global options are fairly hard to just describe, so lets look
-at a quick example using the default org tree:
-
-* CONS
-** SYS1
-*** BR1
-**** SL1
-*** BR2
-** SYS2
-*** BR3
-**** BM1
-*** BR4
-
-The tree has depths of 0 (CONS) through 3 (SL1/BM1). Using BR1 as a consistent
-circulation library we can build a table of Depth/Global combinations and
-expected included libraries:
-
-.BR1 Depth/Global comparisons
-[options="header"]
-|===============================
-|Depth|Global|Included Libraries
-|0 |False |CONS,SYS1,BR1,SL1
-|0 |True |ALL
-|1 |False |SYS1,BR1,SL1
-|1 |True |SYS1,BR1,BR2,SL1
-|2 |False |BR1,SL1
-|2 |True |BR1,SL1
-|3 |False |SL1
-|3 |True |SL1
-|===============================
-
-== "Tagging" Circulations
-
-In order to count circulations that have no circulation modifier the system has
-to know how to find them. When using circulation modifiers this is easy, just
-look for circulations with items assigned the modifier. But say you want to be
-able to count every video, regardless of circulation modifiers? That is where
-Limit Groups come in.
-
-Limit Groups are automatically recorded from the circulation policies as the
-Limit Sets are looked over. Those Limit Groups assigned to the Limit Sets that
-are not flagged as "Check Only" will be attached to the circulation so that
-later circulations can find them.
-
-It is possible to make Limit Sets that do not check, but only tag. This is
-accomplished by setting "Items Out" to zero (0).
-
-== Associating Limit Sets with Matchpoints
-
-Limit Sets alone are useless if they are not associated with circulation
-matchpoints. When creating or editing matchpoints you can add, remove, or adjust
-settings on linked Limit Sets.
-
-The options available for an attached limit set are:
-
-Fallthrough:: If enabled the Limit Set will be applied whenever the matchpoint
-matches a potential circulation. If not enabled the limit set will only be
-applied when the matchpoint is the first match for a potential circulation.
-Active:: An inactive Limit Set link will never be checked, for tagging or
-counting.
-
-== Limit Sets on Empty Rules
-
-For limiting without otherwise changing circulation rules you can create an
-"empty" rule and attach one or more Limit Sets to it. In this case an empty rule
-is one that does not set any of the "result" fields, but instead lets everything
-fall through to less specific rules. Top level rules based on Marc Type could be
-created for the sole purpose of attaching Limit Sets that allow 0 "Items Out".
-This would allow for a quick top-level tagging of all circulations by Marc Type,
-without otherwise introducing limits, in the event you have reason to limit
-based on that information later.
-
-== Limit a single library's items, regardless of checkout library
-
-For example, videos from BR2 limited to 5 anywhere:
-
-. Create a Limit Group, say "BR2 Videos"
-. Create a Limit Set:
-* Items Out: 5
-* Min Depth: 0
-* Global: True
-* Limit Groups: "BR2 Videos"
-. Create an "empty" matchpoint that is at the top of the org/permission trees
-with Marc Type g and circ library BR2.
-. Attach your limit set to the matchpoint with Fallthrough enabled.
-
-This should limit BR2's videos to 5 out, no matter where they are being checked
-out. Videos owned by others should be unaffected, even if circulating out of
-BR2.
--- /dev/null
+Booking Module
+--------------
+
+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.
+
+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.
+
+image::media/booking-create-1_web_client.png[]
+
+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.
+
+image::media/booking-create-2_web_client.png[]
+
+4) For non-catalogued resources, the Bookable Resource Type and the items associated with the type will appear.
+
+image::media/booking-create-3_web_client.png[]
+
+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.
+
+image::media/booking-create-4_web_client.png[]
+
+[NOTE]
+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.
+
+image::media/booking-create-5_web_client.png[]
+
+7) Select the pickup location from the dropdown list.
+
+image::media/booking-create-6_web_client.png[]
+
+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.
+
+image::media/booking-create-7.png[]
+
+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.
+
+image::media/booking-create-9_web_client.png[]
+
+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
+
+image::media/booking-create-module-1_web_client.png[]
+
+2) Choose a Bookable Resource Type and click Next or enter the barcode of a catalogued resource and click Next.
+
+image::media/booking-create-module-2.png[]
+
+3) For non-catalogued resources, a screen showing the Bookable Resource Type and the items associated with the type will appear.
+
+image::media/booking-create-module-3_web_client.png[]
+
+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.
+
+image::media/booking-create-module-4_web_client.png[]
+
+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.
+
+image::media/booking-create-4_web_client.png[]
+
+[NOTE]
+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.
+
+image::media/booking-create-5_web_client.png[]
+
+7) Select the pickup location from the dropdown list.
+
+image::media/booking-create-6_web_client.png[]
+
+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.
+
+image::media/booking-create-7.png[]
+
+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.
+
+image::media/booking-create-9_web_client.png[]
+
+
+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.
+
+[NOTE]
+Reservations on catalogued items can be created on Item Status (F5) screen. Select the item, then Actions for Selected Items → Book Item Now.
+
+Reservation Pull List
+~~~~~~~~~~~~~~~~~~~~~
+
+Reservation pull list can be generated dynamically on the Staff Client.
+
+1) To create a pull list, select Booking --> Pull List.
+
+image::media/booking-pull-1_web_client.png[]
+
+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.
+
+image::media/booking-pull-2.png[]
+
+4) The pull list will appear. Click Print to print the pull list.
+
+image::media/booking-pull-3.png[]
+
+Capturing Items for Reservations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Reservations must be captured before they are ready to be picked up by the patron.
+
+[CAUTION]
+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.
+
+image::media/booking-capture-1_web_client.png[]
+
+2) Scan the item barcode or type the barcode then click Capture.
+
+image::media/booking-capture-2_web_client.png[]
+
+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.
+
+image::media/booking-capture-3.png[]
+
+
+Picking Up Reservations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+[CAUTION]
+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.
+
+
+image::media/booking-pickup-1_web_client.png[]
+
+image::media/booking-pickup-module-1_web_client.png[]
+
+
+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.
+
+image::media/booking-pickup-2.png[]
+
+4) The screen will refresh to show that the patron has picked up the reservation(s).
+
+image::media/booking-pickup-3.png[]
+
+
+Returning Reservations
+~~~~~~~~~~~~~~~~~~~~~~
+
+[CAUTION]
+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
+
+image::media/booking-return-module-1.png[]
+
+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.
+
+image::media/booking-return-module-2.png[]
+
+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.
+
+image::media/booking-return-2.png[]
+
+5) The screen will refresh to show any resources that remain out and the reservations that have been returned.
+
+image::media/booking-return-module-4.png[]
+
+[NOTE]
+Reservations can be returned from within patron records by selecting Other --> Booking --> Return Reservations
+
+Cancelling a Reservation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A reservation can be cancelled in a patron’s record or reservation creation screen.
+
+Cancel a reservation from the patron record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1) Retrieve the patron's record.
+
+2) Select Other --> Booking --> Create or Cancel Reservations.
+
+image::media/booking-create-1_web_client.png[]
+
+3) The existing reservations will appear at the bottom of the screen.
+
+image::media/booking-cancel-1.png[]
+
+4) Highlight the reservation that you want to cancel. Click Cancel Selected.
+
+image::media/booking-cancel-2.png[]
+
+[NOTE]
+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.
+
+image::media/booking-cancel-4.png[]
+
+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.
+
+
+
+
+
+
+
+
+++ /dev/null
-Booking Module
---------------
-
-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.
-
-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.
-
-image::media/booking-create-1_web_client.png[]
-
-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.
-
-image::media/booking-create-2_web_client.png[]
-
-4) For non-catalogued resources, the Bookable Resource Type and the items associated with the type will appear.
-
-image::media/booking-create-3_web_client.png[]
-
-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.
-
-image::media/booking-create-4_web_client.png[]
-
-[NOTE]
-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.
-
-image::media/booking-create-5_web_client.png[]
-
-7) Select the pickup location from the dropdown list.
-
-image::media/booking-create-6_web_client.png[]
-
-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.
-
-image::media/booking-create-7.png[]
-
-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.
-
-image::media/booking-create-9_web_client.png[]
-
-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
-
-image::media/booking-create-module-1_web_client.png[]
-
-2) Choose a Bookable Resource Type and click Next or enter the barcode of a catalogued resource and click Next.
-
-image::media/booking-create-module-2.png[]
-
-3) For non-catalogued resources, a screen showing the Bookable Resource Type and the items associated with the type will appear.
-
-image::media/booking-create-module-3_web_client.png[]
-
-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.
-
-image::media/booking-create-module-4_web_client.png[]
-
-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.
-
-image::media/booking-create-4_web_client.png[]
-
-[NOTE]
-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.
-
-image::media/booking-create-5_web_client.png[]
-
-7) Select the pickup location from the dropdown list.
-
-image::media/booking-create-6_web_client.png[]
-
-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.
-
-image::media/booking-create-7.png[]
-
-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.
-
-image::media/booking-create-9_web_client.png[]
-
-
-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.
-
-[NOTE]
-Reservations on catalogued items can be created on Item Status (F5) screen. Select the item, then Actions for Selected Items → Book Item Now.
-
-Reservation Pull List
-~~~~~~~~~~~~~~~~~~~~~
-
-Reservation pull list can be generated dynamically on the Staff Client.
-
-1) To create a pull list, select Booking --> Pull List.
-
-image::media/booking-pull-1_web_client.png[]
-
-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.
-
-image::media/booking-pull-2.png[]
-
-4) The pull list will appear. Click Print to print the pull list.
-
-image::media/booking-pull-3.png[]
-
-Capturing Items for Reservations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Reservations must be captured before they are ready to be picked up by the patron.
-
-[CAUTION]
-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.
-
-image::media/booking-capture-1_web_client.png[]
-
-2) Scan the item barcode or type the barcode then click Capture.
-
-image::media/booking-capture-2_web_client.png[]
-
-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.
-
-image::media/booking-capture-3.png[]
-
-
-Picking Up Reservations
-~~~~~~~~~~~~~~~~~~~~~~~
-
-[CAUTION]
-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.
-
-
-image::media/booking-pickup-1_web_client.png[]
-
-image::media/booking-pickup-module-1_web_client.png[]
-
-
-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.
-
-image::media/booking-pickup-2.png[]
-
-4) The screen will refresh to show that the patron has picked up the reservation(s).
-
-image::media/booking-pickup-3.png[]
-
-
-Returning Reservations
-~~~~~~~~~~~~~~~~~~~~~~
-
-[CAUTION]
-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
-
-image::media/booking-return-module-1.png[]
-
-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.
-
-image::media/booking-return-module-2.png[]
-
-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.
-
-image::media/booking-return-2.png[]
-
-5) The screen will refresh to show any resources that remain out and the reservations that have been returned.
-
-image::media/booking-return-module-4.png[]
-
-[NOTE]
-Reservations can be returned from within patron records by selecting Other --> Booking --> Return Reservations
-
-Cancelling a Reservation
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-A reservation can be cancelled in a patron’s record or reservation creation screen.
-
-Cancel a reservation from the patron record
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-1) Retrieve the patron's record.
-
-2) Select Other --> Booking --> Create or Cancel Reservations.
-
-image::media/booking-create-1_web_client.png[]
-
-3) The existing reservations will appear at the bottom of the screen.
-
-image::media/booking-cancel-1.png[]
-
-4) Highlight the reservation that you want to cancel. Click Cancel Selected.
-
-image::media/booking-cancel-2.png[]
-
-[NOTE]
-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.
-
-image::media/booking-cancel-4.png[]
-
-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.
-
-
-
-
-
-
-
-
--- /dev/null
+Circulating Items
+-----------------
+
+Check Out (F1)
+~~~~~~~~~~~~~~
+
+Regular Items
+^^^^^^^^^^^^^
+
+1) To check out an item press *F1*, click *Check Out* on the Circulation
+toolbar, or select *Circulation* -> *Check Out Items*.
+
+image::media/checkout_menu.png[]
+
+2) Scan or enter patron's barcode and click *Submit* if entering barcode
+manually. If scanning, number is submitted automatically.
+
+image::media/retrieve_patron.png[]
+
+3) Scan or enter item barcode manually, clicking *Submit* if manual.
+
+image::media/checkout_item_barcode.png[]
+
+4) Due date is now displayed.
+
+image::media/due_date_display.png[]
+
+5) When all items are scanned, hit the *F1* key or click the *Check Out* button
+on the Circulation toolbar to generate slip receipt or to exit patron record if
+not printing slip receipts.
+
+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, click *Pre-Cataloged*.
+
+image::media/pre_cat_alert.png[]
+
+4) Enter required information and click *Check Out*.
+
+image::media/precat.png[]
+
+[TIP]
+On check-in, Evergreen will prompt staff to re-route the item to cataloging.
+
+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. Use the
+calendar widget to select a date. Or click in day, month or year, then use the
+up or down arrows to make the change or simply delete the data, then enter
+again. Time is used for hourly loan only. This date applies to all items until
+you change the date, de-select the *Specific Due Date* checkbox, or quit the
+patron record.
+
+image::media/specify_due_date1.png[]
+
+image::media/specify_due_date2.png[]
+
+Check In (F2)
+~~~~~~~~~~~~~
+
+Regular check in
+^^^^^^^^^^^^^^^^
+
+1) To check in an item, select *Circulation -> Check In Items*, click *Check In*
+on the Circulation toolbar, or press *F2*.
+
+image::media/check_in_menu.png[]
+
+2) Scan item barcode or enter manually and click *Submit*.
+
+image::media/checkin_barcode.png[]
+
+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.
+
+image::media/overdue_checkin.png[]
+
+Backdated check in
+^^^^^^^^^^^^^^^^^^
+
+This is useful for clearing a book drop.
+
+1) To change effective check-in date, select *Circulation* -> *Check In Items*,
+or press *F2*. Use the calendar widget to choose the effective date.
+
+image::media/backdate_checkin.png[]
+
+2) The top green bar changes to red. The new effective date is now displayed in
+the header.
+
+image::media/backdate_red.png[]
+
+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.
+
+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 for Selected Items ->
+Backdate Post-Checkin.
+
+image::media/backdate_post_checkin.png[]
+
+2) Use the calendar widget to select an effective check-in date. Click Apply.
+Overdue fines, if any, will be adjusted according to the new effective check-in
+date.
+
+image::media/backdate_post_date.png[]
+
+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 Cataloging with Cataloging status.
+- Suppress 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 removed if already created
+or not be inserted if not yet created (e.g. hourly loans). The fines are removed
+with an account_adjustment payment type.
+- Auto-Print Hold and Transit Slips: slips will be automatically printed without
+prompt for confirmation.
+
+These options may be selected simultaneously. The selected option is displayed
+in the header area.
+
+image::media/checkin_options.png[]
+
+
+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.
+
+Renewing via a Patron's Account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1) Retrieve the patron record and go to the *Items Out* screen.
+
+image::media/items_out_click.png[]
+
+TIP: Add "Holds Count" from the column picker to quickly see whether an item to be renewed has holds.
+
+2) Select the item you want to renew. *Click on Actions for Selected Items* ->
+*Renew*. If you want to renew all items in the account, click *Renew All*
+instead.
+
+image::media/renew_action.png[]
+
+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*.
+
+image::media/renew_specific_date.png[]
+
+[TIP]
+Renewal can also be done on the *Item Status* screen. See the section called
+<<itemstatus,Item Status (F5)>> for more information.
+
+Renewing by Item Barcode
+^^^^^^^^^^^^^^^^^^^^^^^^
+1) To renew items by barcode, select *Circulation* -> *Renew Items* or press
+*CTRL-F2*.
+
+2) Scan or manually entire the item barcode.
+
+image::media/renew_item.png[]
+
+3) If you want to specify the due date, click *Specific Due Date* and select a
+new due date from the calendar.
+
+image::media/renew_item_calendar.png[]
+
+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 for Selected Items* ->
+*Edit Due Date*.
+
+image::media/edit_due_date_action.png[]
+
+3) Select a new due date in the pop-up window, then click *Apply*.
+
+[TIP]
+You can select multiple items by pressing down the CTRL key on your keyboard and
+clicking each items you want to edit.
+
+[NOTE]
+Editing a due date is not included in the renewal count.
+
+Marking Items Lost and Claimed Returned
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lost Items
+^^^^^^^^^^
+1) To mark items Lost, retrieve patron record and click *Items Out*.
+
+2) Select the item. Click on *Actions for Selected Items* -> *Mark Lost (by
+Patron)*.
+
+image::media/mark_lost.png[]
+
+3) The lost item now displays in the *Other/Special Circulations section of the
+patron record, unless otherwise customized through the Items Out display setting
+available in the Library Settings Editor.
+
+image::media/lost_cr_section.png[]
+
+4) The lost item also adds to the count of *Lost* items in the patron summary on
+the left (or top) of the screen.
+
+image::media/patron_summary_checkouts.jpg[]
+
+[NOTE]
+.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.
+========================
+
+Refunding and Clearing Negative Balances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If an item is returned after a lost bill has been paid, there may be a negative
+balance on the bill. See ... for more information on settings that affect
+negative balances. See <<removing_negative_balances, Removing Negative Balances
+from a Patron Account>> for more information on clearing that balance.
+
+
+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 for Selected Items* -> *Mark Claimed
+Returned* from the dropdown menu.
+
+image::media/mark_claims_returned.png[]
+
+3) Select a date and click *Apply*.
+
+image::media/claimed_date.png[]
+
+4) Any overdue fines associated with the transaction will now be based on the
+Claimed Returned date.
+
+5) The Claimed Returned item now displays in the *Other/Special Circulations*
+section of the patron record, unless otherwise customized through the Items Out
+display setting available in the Library Settings Editor.
+
+image::media/lost_cr_section.png[]
+
+6) The Claimed Returned item adds to the count of Check Outs that are Claimed
+Returned in the patron summary on the left (or top) of the screen. It also adds
+to the total *Claims-returned Count* (including those that are current Check
+Outs and those that have since been returned) that is displayed when editing the
+patron's record.
+
+image::media/patron_summary_checkouts.jpg[]
+
+[NOTE]
+.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.
+- Marking a lost transaction Claimed Returned will not remove a lost item
+billing or lost item processing fee unless the _Void lost item billing when
+claims returned_ and/or the _Void lost item processing fee when claims returned_
+settings are enabled. Both settings are available via the Library Settings
+editor.
+====================================
+
+Enhancements to Items Out
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the *Items Out* interface in the patron's account is divided into two sections beneath the patron information: *Items Out* and *Other/Special Circulations*. In previous versions of Evergreen, all circulations appeared in the *Items Out* portion of the interface except for those marked LOST, LONGOVERDUE, or CLAIMSRETURNED, which appeared in the *Other/Special Circulations* portion of the interface.
+
+This enhancement enables you to customize the placement of items in the LOST, LONGOVERDUE, or CLAIMSRETURNED statuses in the top or bottom list. The value of this enhancement includes increased control over and organization of the Items Out interface.
+
+1) Three new org unit settings enable you to control the placement of these items. To access these settings, click *Admin* -> *Local Administration* -> *Library Settings Editor*, and search for the following settings:
+
+* Items Out Lost Display Setting
+
+* Items Out Long-Overdue Display Setting
+
+* Items Out Claims Returned Display Setting
+
+The value for each setting is a numeric code describing the list in which the circulation should be placed when the item is checked out, and whether the circulation should appear in the bottom list when checked in, regardless of the state of the transaction. For example, an item may be checked in but the circulation may remain open because fees or fines are owed by the patron.
+
+2) Enter the appropriate value, and click *Update setting*.
+
+1 = Top list, then bottom list
+2 = Bottom list, then bottom list
+5 = Top list, then do not display
+6 = Bottom list, then do not display
+
+To Hide the bottom list entirely, set the value for all special statuses to "5".
+
+Note that if all of the special statuses are hidden, then the interface more accurately represents a patron's items out instead of a combination of items out and items with special circumstances. Alternatively, if all items out and items with special statuses display in the top list, then the bottom list is hidden, and more screen space exists to display a patron's items out.
+
+
+Mark an Item Long Overdue
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Marking an item Long Overdue*
+
+Once an item has been overdue for a configurable amount of time, Evergreen can
+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.
+
+image::media/long_overdue1.jpg[Patron Account-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.
+
+image::media/long_overdue2.jpg[Long Overdue Checkin]
+
+*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_LONGOVERDUE.override
+
+** Allows the user to check-in long-overdue items thus removing the long-overdue
+ status on the item
+
+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*.
+
+image::media/record_in_house_action.png[]
+
+2) To record in-house use for cataloged items, enter number of uses, scan
+barcode or type barcode and click *Submit*.
+
+image::media/in_house_use.png[]
+
+[NOTE]
+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.
+
+[[itemstatus]]
+Item Status (F5)
+~~~~~~~~~~~~~~~~
+
+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.
+
+Checking item status
+^^^^^^^^^^^^^^^^^^^^
+
+1) To check the status of an item, select *Search* -> *Search for copies by
+Barcode* or *Circulation* -> *Show Item Status by Barcode*; click the *Item
+Status button* on the circulation or cataloging toolbar; or press *F5*.
+
+image::media/item_status_menu.png[]
+
+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.
+
+image::media/item_status_barcode.png[]
+
+3) Click the *Alternate View* button, and the item summary and circulation
+history will be displayed.
+
+image::media/item_status_altview.png[]
+
+4) Click *List View* to go back.
+
+image::media/item_status_list_view.png[]
+
+[NOTE]
+If the item's status is "Available", the displayed due date refers to the
+previous circulation's due date.
+
+[TIP]
+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.
+
+Viewing past circulations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+1) To view past circulations, retrieve the item on the *Item Status* screen as
+described above.
+
+2) Select *Actions for Selected Items* -> *Show Last Few Circulations*.
+
+image::media/last_few_circs_action.png[]
+
+3) The item's recent circulation history is displayed.
+
+image::media/last_few_circs_display.png[]
+
+4) To retrieve the patron(s) of the last circulations, click the *Retrieve Last
+Patron* or the *Retrieve All These Patrons* button at the bottom of the above
+screen. Patron record(s) will be displayed in new tab(s).
+
+[TIP]
+The number of items that displays in the circulation history can be set in Local
+ *Administration* -> *Library Settings Editor*.
+
+[NOTE]
+You can also retrieve the past circulations on the patron's Items Out screen and
+from the Check In screen.
+
+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*.
+
+image::media/mark_missing_damaged.png[]
+
+[NOTE}
+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.
+
+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*.
+
+image::media/copy_edit_alert.png[]
+
+4) Click *Alert Message* in the *Miscellaneous* column. The background color of
+the box changes. Type in the message then click *Apply*.
+
+image::media/copy_alert_message.png[]
+
+5) Click *Modify Copies*, then confirm the action.
+
+
+
+
+++ /dev/null
-Circulating Items
------------------
-
-Check Out (F1)
-~~~~~~~~~~~~~~
-
-Regular Items
-^^^^^^^^^^^^^
-
-1) To check out an item press *F1*, click *Check Out* on the Circulation
-toolbar, or select *Circulation* -> *Check Out Items*.
-
-image::media/checkout_menu.png[]
-
-2) Scan or enter patron's barcode and click *Submit* if entering barcode
-manually. If scanning, number is submitted automatically.
-
-image::media/retrieve_patron.png[]
-
-3) Scan or enter item barcode manually, clicking *Submit* if manual.
-
-image::media/checkout_item_barcode.png[]
-
-4) Due date is now displayed.
-
-image::media/due_date_display.png[]
-
-5) When all items are scanned, hit the *F1* key or click the *Check Out* button
-on the Circulation toolbar to generate slip receipt or to exit patron record if
-not printing slip receipts.
-
-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, click *Pre-Cataloged*.
-
-image::media/pre_cat_alert.png[]
-
-4) Enter required information and click *Check Out*.
-
-image::media/precat.png[]
-
-[TIP]
-On check-in, Evergreen will prompt staff to re-route the item to cataloging.
-
-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. Use the
-calendar widget to select a date. Or click in day, month or year, then use the
-up or down arrows to make the change or simply delete the data, then enter
-again. Time is used for hourly loan only. This date applies to all items until
-you change the date, de-select the *Specific Due Date* checkbox, or quit the
-patron record.
-
-image::media/specify_due_date1.png[]
-
-image::media/specify_due_date2.png[]
-
-Check In (F2)
-~~~~~~~~~~~~~
-
-Regular check in
-^^^^^^^^^^^^^^^^
-
-1) To check in an item, select *Circulation -> Check In Items*, click *Check In*
-on the Circulation toolbar, or press *F2*.
-
-image::media/check_in_menu.png[]
-
-2) Scan item barcode or enter manually and click *Submit*.
-
-image::media/checkin_barcode.png[]
-
-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.
-
-image::media/overdue_checkin.png[]
-
-Backdated check in
-^^^^^^^^^^^^^^^^^^
-
-This is useful for clearing a book drop.
-
-1) To change effective check-in date, select *Circulation* -> *Check In Items*,
-or press *F2*. Use the calendar widget to choose the effective date.
-
-image::media/backdate_checkin.png[]
-
-2) The top green bar changes to red. The new effective date is now displayed in
-the header.
-
-image::media/backdate_red.png[]
-
-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.
-
-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 for Selected Items ->
-Backdate Post-Checkin.
-
-image::media/backdate_post_checkin.png[]
-
-2) Use the calendar widget to select an effective check-in date. Click Apply.
-Overdue fines, if any, will be adjusted according to the new effective check-in
-date.
-
-image::media/backdate_post_date.png[]
-
-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 Cataloging with Cataloging status.
-- Suppress 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 removed if already created
-or not be inserted if not yet created (e.g. hourly loans). The fines are removed
-with an account_adjustment payment type.
-- Auto-Print Hold and Transit Slips: slips will be automatically printed without
-prompt for confirmation.
-
-These options may be selected simultaneously. The selected option is displayed
-in the header area.
-
-image::media/checkin_options.png[]
-
-
-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.
-
-Renewing via a Patron's Account
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-1) Retrieve the patron record and go to the *Items Out* screen.
-
-image::media/items_out_click.png[]
-
-TIP: Add "Holds Count" from the column picker to quickly see whether an item to be renewed has holds.
-
-2) Select the item you want to renew. *Click on Actions for Selected Items* ->
-*Renew*. If you want to renew all items in the account, click *Renew All*
-instead.
-
-image::media/renew_action.png[]
-
-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*.
-
-image::media/renew_specific_date.png[]
-
-[TIP]
-Renewal can also be done on the *Item Status* screen. See the section called
-<<itemstatus,Item Status (F5)>> for more information.
-
-Renewing by Item Barcode
-^^^^^^^^^^^^^^^^^^^^^^^^
-1) To renew items by barcode, select *Circulation* -> *Renew Items* or press
-*CTRL-F2*.
-
-2) Scan or manually entire the item barcode.
-
-image::media/renew_item.png[]
-
-3) If you want to specify the due date, click *Specific Due Date* and select a
-new due date from the calendar.
-
-image::media/renew_item_calendar.png[]
-
-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 for Selected Items* ->
-*Edit Due Date*.
-
-image::media/edit_due_date_action.png[]
-
-3) Select a new due date in the pop-up window, then click *Apply*.
-
-[TIP]
-You can select multiple items by pressing down the CTRL key on your keyboard and
-clicking each items you want to edit.
-
-[NOTE]
-Editing a due date is not included in the renewal count.
-
-Marking Items Lost and Claimed Returned
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Lost Items
-^^^^^^^^^^
-1) To mark items Lost, retrieve patron record and click *Items Out*.
-
-2) Select the item. Click on *Actions for Selected Items* -> *Mark Lost (by
-Patron)*.
-
-image::media/mark_lost.png[]
-
-3) The lost item now displays in the *Other/Special Circulations section of the
-patron record, unless otherwise customized through the Items Out display setting
-available in the Library Settings Editor.
-
-image::media/lost_cr_section.png[]
-
-4) The lost item also adds to the count of *Lost* items in the patron summary on
-the left (or top) of the screen.
-
-image::media/patron_summary_checkouts.jpg[]
-
-[NOTE]
-.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.
-========================
-
-Refunding and Clearing Negative Balances
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If an item is returned after a lost bill has been paid, there may be a negative
-balance on the bill. See ... for more information on settings that affect
-negative balances. See <<removing_negative_balances, Removing Negative Balances
-from a Patron Account>> for more information on clearing that balance.
-
-
-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 for Selected Items* -> *Mark Claimed
-Returned* from the dropdown menu.
-
-image::media/mark_claims_returned.png[]
-
-3) Select a date and click *Apply*.
-
-image::media/claimed_date.png[]
-
-4) Any overdue fines associated with the transaction will now be based on the
-Claimed Returned date.
-
-5) The Claimed Returned item now displays in the *Other/Special Circulations*
-section of the patron record, unless otherwise customized through the Items Out
-display setting available in the Library Settings Editor.
-
-image::media/lost_cr_section.png[]
-
-6) The Claimed Returned item adds to the count of Check Outs that are Claimed
-Returned in the patron summary on the left (or top) of the screen. It also adds
-to the total *Claims-returned Count* (including those that are current Check
-Outs and those that have since been returned) that is displayed when editing the
-patron's record.
-
-image::media/patron_summary_checkouts.jpg[]
-
-[NOTE]
-.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.
-- Marking a lost transaction Claimed Returned will not remove a lost item
-billing or lost item processing fee unless the _Void lost item billing when
-claims returned_ and/or the _Void lost item processing fee when claims returned_
-settings are enabled. Both settings are available via the Library Settings
-editor.
-====================================
-
-Enhancements to Items Out
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, the *Items Out* interface in the patron's account is divided into two sections beneath the patron information: *Items Out* and *Other/Special Circulations*. In previous versions of Evergreen, all circulations appeared in the *Items Out* portion of the interface except for those marked LOST, LONGOVERDUE, or CLAIMSRETURNED, which appeared in the *Other/Special Circulations* portion of the interface.
-
-This enhancement enables you to customize the placement of items in the LOST, LONGOVERDUE, or CLAIMSRETURNED statuses in the top or bottom list. The value of this enhancement includes increased control over and organization of the Items Out interface.
-
-1) Three new org unit settings enable you to control the placement of these items. To access these settings, click *Admin* -> *Local Administration* -> *Library Settings Editor*, and search for the following settings:
-
-* Items Out Lost Display Setting
-
-* Items Out Long-Overdue Display Setting
-
-* Items Out Claims Returned Display Setting
-
-The value for each setting is a numeric code describing the list in which the circulation should be placed when the item is checked out, and whether the circulation should appear in the bottom list when checked in, regardless of the state of the transaction. For example, an item may be checked in but the circulation may remain open because fees or fines are owed by the patron.
-
-2) Enter the appropriate value, and click *Update setting*.
-
-1 = Top list, then bottom list
-2 = Bottom list, then bottom list
-5 = Top list, then do not display
-6 = Bottom list, then do not display
-
-To Hide the bottom list entirely, set the value for all special statuses to "5".
-
-Note that if all of the special statuses are hidden, then the interface more accurately represents a patron's items out instead of a combination of items out and items with special circumstances. Alternatively, if all items out and items with special statuses display in the top list, then the bottom list is hidden, and more screen space exists to display a patron's items out.
-
-
-Mark an Item Long Overdue
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Marking an item Long Overdue*
-
-Once an item has been overdue for a configurable amount of time, Evergreen can
-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.
-
-image::media/long_overdue1.jpg[Patron Account-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.
-
-image::media/long_overdue2.jpg[Long Overdue Checkin]
-
-*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_LONGOVERDUE.override
-
-** Allows the user to check-in long-overdue items thus removing the long-overdue
- status on the item
-
-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*.
-
-image::media/record_in_house_action.png[]
-
-2) To record in-house use for cataloged items, enter number of uses, scan
-barcode or type barcode and click *Submit*.
-
-image::media/in_house_use.png[]
-
-[NOTE]
-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.
-
-[[itemstatus]]
-Item Status (F5)
-~~~~~~~~~~~~~~~~
-
-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.
-
-Checking item status
-^^^^^^^^^^^^^^^^^^^^
-
-1) To check the status of an item, select *Search* -> *Search for copies by
-Barcode* or *Circulation* -> *Show Item Status by Barcode*; click the *Item
-Status button* on the circulation or cataloging toolbar; or press *F5*.
-
-image::media/item_status_menu.png[]
-
-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.
-
-image::media/item_status_barcode.png[]
-
-3) Click the *Alternate View* button, and the item summary and circulation
-history will be displayed.
-
-image::media/item_status_altview.png[]
-
-4) Click *List View* to go back.
-
-image::media/item_status_list_view.png[]
-
-[NOTE]
-If the item's status is "Available", the displayed due date refers to the
-previous circulation's due date.
-
-[TIP]
-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.
-
-Viewing past circulations
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-1) To view past circulations, retrieve the item on the *Item Status* screen as
-described above.
-
-2) Select *Actions for Selected Items* -> *Show Last Few Circulations*.
-
-image::media/last_few_circs_action.png[]
-
-3) The item's recent circulation history is displayed.
-
-image::media/last_few_circs_display.png[]
-
-4) To retrieve the patron(s) of the last circulations, click the *Retrieve Last
-Patron* or the *Retrieve All These Patrons* button at the bottom of the above
-screen. Patron record(s) will be displayed in new tab(s).
-
-[TIP]
-The number of items that displays in the circulation history can be set in Local
- *Administration* -> *Library Settings Editor*.
-
-[NOTE]
-You can also retrieve the past circulations on the patron's Items Out screen and
-from the Check In screen.
-
-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*.
-
-image::media/mark_missing_damaged.png[]
-
-[NOTE}
-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.
-
-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*.
-
-image::media/copy_edit_alert.png[]
-
-4) Click *Alert Message* in the *Miscellaneous* column. The background color of
-the box changes. Type in the message then click *Apply*.
-
-image::media/copy_alert_message.png[]
-
-5) Click *Modify Copies*, then confirm the action.
-
-
-
-
--- /dev/null
+Circulating Items
+-----------------
+
+Check Out
+~~~~~~~~~~
+
+Regular Items
+^^^^^^^^^^^^^
+
+1) To check out an item click *Check Out Items* from the Circulation and Patrons toolbar, or select *Circulation* -> *Check Out*.
+
+image::media/checkout_menu_web_client.png[]
+
+2) Scan or enter patron's barcode and click *Submit* if entering barcode manually. If scanning, number is submitted automatically.
+
+image::media/retrieve_patron_web_client.png[]
+
+3) Scan or enter item barcode manually, clicking *Submit* if manual.
+
+image::media/checkout_item_barcode_web_client.png[]
+
+4) Due date is now displayed.
+
+image::media/due_date_display_web_client.png[]
+
+5) When all items are scanned, click the *Done* button to generate slip receipt or to exit patron record if not printing slip receipts.
+
+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*.
+
+image::media/precat_web_client.png[]
+
+[TIP]
+On check-in, Evergreen will prompt staff to re-route the item to cataloging.
+
+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.
+
+image::media/specify_due_date1_web_client.png[]
+
+
+Check In
+~~~~~~~~
+
+Regular check in
+^^^^^^^^^^^^^^^^
+
+1) To check in an item click *Check In Items* from the Circulation and Patrons toolbar, or select *Circulation* -> *Check In*.
+
+image::media/check_in_menu_web_client.png[]
+
+2) Scan item barcode or enter manually and click *Submit*.
+
+image::media/checkin_barcode_web_client.png[]
+
+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.
+
+image::media/overdue_checkin_web_client.png[]
+
+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.
+
+image::media/backdate_checkin_web_client.png[]
+
+2) The new effective date is now displayed in the red bar above the Barcode field.
+
+image::media/backdate_red_web_client.png[]
+
+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.
+
+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*.
+
+image::media/backdate_post_checkin_web_client.png[]
+
+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.
+
+image::media/backdate_post_date_web_client.png[]
+
+[TIP]
+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.
+
+image::media/checkin_options_web_client.png[]
+
+====================================================
+
+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.
+
+Renewing via a Patron's Account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1) Retrieve the patron record and go to the *Items Out* screen.
+
+image::media/items_out_click_web_client.png[]
+
+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.
+
+image::media/renew_action_web_client.png[]
+
+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*.
+
+//image::media/renew_specific_date_web_client.png[]
+
+
+Renewing by Item Barcode
+^^^^^^^^^^^^^^^^^^^^^^^^
+1) To renew items by barcode, select *Circulation* -> *Renew Items*.
+
+2) Scan or manually entire the item barcode.
+
+image::media/renew_item_web_client.png[]
+
+3) If you want to specify the due date, click *Specific Due Date* and enter a new due date in yyyy-mm-dd format.
+
+image::media/renew_item_calendar_web_client.png[]
+
+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*.
+
+image::media/edit_due_date_action_web_client.png[]
+
+3) Enter a new due date in yyyy-mm-dd format in the pop-up window, then click *OK*.
+
+[NOTE]
+Editing a due date is not included in the renewal count.
+
+Marking Items Lost and Claimed Returned
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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)*.
+
+image::media/mark_lost_web_client.png[]
+
+3) The lost item now displays as lost in the *Items Checked Out* section of the patron record.
+
+image::media/lost_section_web_client.png[]
+
+4) The lost item also adds to the count of *Lost* items in the patron summary on the left (or top) of the screen.
+
+image::media/patron_summary_checkouts_web_client.png[]
+
+[NOTE]
+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.
+==========================
+
+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.
+
+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.
+
+image::media/mark_claims_returned_web_client.png[]
+
+3) Enter date in yyyy-mm-dd format and click *Submit*.
+
+image::media/claimed_date_web_client.png[]
+
+4) The Claimed Returned item now displays in the *Other/Special Circulations* section of the patron record.
+
+image::media/cr_section_web_client.png[]
+
+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.
+
+image::media/patron_summary_checkouts_web_client.png[]
+
+[NOTE]
+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.
+====================================
+
+In-house Use
+~~~~~~~~~~~~
+1) To record in-house use, select *Circulation* -> *Record In-House Use*.
+
+image::media/record_in_house_action_web_client.png[]
+
+2) To record in-house use for cataloged items, enter number of uses, scan barcode or type barcode and click *Submit*.
+
+image::media/in_house_use_web_client.png[]
+
+[NOTE]
+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.
+
+[[itemstatus_web_client]]
+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.
+
+Checking item status
+^^^^^^^^^^^^^^^^^^^^
+
+1) To check the status of an item, select *Search* -> *Search for copies by Barcode*.
+
+image::media/item_status_menu_web_client.png[]
+
+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.
+
+image::media/item_status_barcode_web_client.png[]
+
+3) Click the *Detail View* button and the item summary and circulation history will be displayed.
+
+image::media/item_status_altview_web_client.png[]
+
+4) Click *List View* to go back.
+
+image::media/item_status_list_view_web_client.png[]
+
+[NOTE]
+If the item's status is "Available", the displayed due date refers to the previous circulation's due date.
+
+[TIP]
+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.
+
+Viewing past circulations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+1) To view past circulations, retrieve the item on the *Item Status* screen as described above.
+
+2) Select *Detail view*.
+
+image::media/last_few_circs_action_web_client.png[]
+
+3) Choose *Recent Circ History*. The item’s recent circulation history is displayed.
+
+image::media/last_few_circs_display_web_client.png[]
+
+4) To retrieve the patron(s) of the last circulations, click on the name of the patron. The patron record will be displayed.
+
+[TIP]
+The number of items that displays in the circulation history can be set in Local *Administration* -> *Library Settings Editor*.
+
+[NOTE]
+You can also retrieve the past circulations on the patron's Items Out screen and from the Check In screen.
+
+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*.
+
+// image::media/mark_missing_damaged_web_client.png[]
+
+[NOTE]
+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.
+
+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*.
+
+//image::media/copy_edit_alert_web_client.png[]
+
+4) Click *Alert Message* in the *Miscellaneous* column. The background color of the box changes. Type in the message then click *Apply*.
+
+//image::media/copy_alert_message_web_client.png[]
+
+5) Click *Modify Copies*, then confirm the action.
+
+
+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.
+
+image::media/long_overdue1.jpg[Patron Account-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.
+
+image::media/long_overdue2.jpg[Long Overdue Checkin]
+
+*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_LONGOVERDUE.override
+
+** Allows the user to check-in long-overdue items thus removing the long-overdue status on the item
+
+
+
+++ /dev/null
-Circulating Items
------------------
-
-Check Out
-~~~~~~~~~~
-
-Regular Items
-^^^^^^^^^^^^^
-
-1) To check out an item click *Check Out Items* from the Circulation and Patrons toolbar, or select *Circulation* -> *Check Out*.
-
-image::media/checkout_menu_web_client.png[]
-
-2) Scan or enter patron's barcode and click *Submit* if entering barcode manually. If scanning, number is submitted automatically.
-
-image::media/retrieve_patron_web_client.png[]
-
-3) Scan or enter item barcode manually, clicking *Submit* if manual.
-
-image::media/checkout_item_barcode_web_client.png[]
-
-4) Due date is now displayed.
-
-image::media/due_date_display_web_client.png[]
-
-5) When all items are scanned, click the *Done* button to generate slip receipt or to exit patron record if not printing slip receipts.
-
-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*.
-
-image::media/precat_web_client.png[]
-
-[TIP]
-On check-in, Evergreen will prompt staff to re-route the item to cataloging.
-
-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.
-
-image::media/specify_due_date1_web_client.png[]
-
-
-Check In
-~~~~~~~~
-
-Regular check in
-^^^^^^^^^^^^^^^^
-
-1) To check in an item click *Check In Items* from the Circulation and Patrons toolbar, or select *Circulation* -> *Check In*.
-
-image::media/check_in_menu_web_client.png[]
-
-2) Scan item barcode or enter manually and click *Submit*.
-
-image::media/checkin_barcode_web_client.png[]
-
-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.
-
-image::media/overdue_checkin_web_client.png[]
-
-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.
-
-image::media/backdate_checkin_web_client.png[]
-
-2) The new effective date is now displayed in the red bar above the Barcode field.
-
-image::media/backdate_red_web_client.png[]
-
-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.
-
-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*.
-
-image::media/backdate_post_checkin_web_client.png[]
-
-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.
-
-image::media/backdate_post_date_web_client.png[]
-
-[TIP]
-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.
-
-image::media/checkin_options_web_client.png[]
-
-====================================================
-
-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.
-
-Renewing via a Patron's Account
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-1) Retrieve the patron record and go to the *Items Out* screen.
-
-image::media/items_out_click_web_client.png[]
-
-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.
-
-image::media/renew_action_web_client.png[]
-
-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*.
-
-//image::media/renew_specific_date_web_client.png[]
-
-
-Renewing by Item Barcode
-^^^^^^^^^^^^^^^^^^^^^^^^
-1) To renew items by barcode, select *Circulation* -> *Renew Items*.
-
-2) Scan or manually entire the item barcode.
-
-image::media/renew_item_web_client.png[]
-
-3) If you want to specify the due date, click *Specific Due Date* and enter a new due date in yyyy-mm-dd format.
-
-image::media/renew_item_calendar_web_client.png[]
-
-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*.
-
-image::media/edit_due_date_action_web_client.png[]
-
-3) Enter a new due date in yyyy-mm-dd format in the pop-up window, then click *OK*.
-
-[NOTE]
-Editing a due date is not included in the renewal count.
-
-Marking Items Lost and Claimed Returned
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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)*.
-
-image::media/mark_lost_web_client.png[]
-
-3) The lost item now displays as lost in the *Items Checked Out* section of the patron record.
-
-image::media/lost_section_web_client.png[]
-
-4) The lost item also adds to the count of *Lost* items in the patron summary on the left (or top) of the screen.
-
-image::media/patron_summary_checkouts_web_client.png[]
-
-[NOTE]
-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.
-==========================
-
-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.
-
-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.
-
-image::media/mark_claims_returned_web_client.png[]
-
-3) Enter date in yyyy-mm-dd format and click *Submit*.
-
-image::media/claimed_date_web_client.png[]
-
-4) The Claimed Returned item now displays in the *Other/Special Circulations* section of the patron record.
-
-image::media/cr_section_web_client.png[]
-
-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.
-
-image::media/patron_summary_checkouts_web_client.png[]
-
-[NOTE]
-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.
-====================================
-
-In-house Use
-~~~~~~~~~~~~
-1) To record in-house use, select *Circulation* -> *Record In-House Use*.
-
-image::media/record_in_house_action_web_client.png[]
-
-2) To record in-house use for cataloged items, enter number of uses, scan barcode or type barcode and click *Submit*.
-
-image::media/in_house_use_web_client.png[]
-
-[NOTE]
-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.
-
-[[itemstatus_web_client]]
-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.
-
-Checking item status
-^^^^^^^^^^^^^^^^^^^^
-
-1) To check the status of an item, select *Search* -> *Search for copies by Barcode*.
-
-image::media/item_status_menu_web_client.png[]
-
-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.
-
-image::media/item_status_barcode_web_client.png[]
-
-3) Click the *Detail View* button and the item summary and circulation history will be displayed.
-
-image::media/item_status_altview_web_client.png[]
-
-4) Click *List View* to go back.
-
-image::media/item_status_list_view_web_client.png[]
-
-[NOTE]
-If the item's status is "Available", the displayed due date refers to the previous circulation's due date.
-
-[TIP]
-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.
-
-Viewing past circulations
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-1) To view past circulations, retrieve the item on the *Item Status* screen as described above.
-
-2) Select *Detail view*.
-
-image::media/last_few_circs_action_web_client.png[]
-
-3) Choose *Recent Circ History*. The item’s recent circulation history is displayed.
-
-image::media/last_few_circs_display_web_client.png[]
-
-4) To retrieve the patron(s) of the last circulations, click on the name of the patron. The patron record will be displayed.
-
-[TIP]
-The number of items that displays in the circulation history can be set in Local *Administration* -> *Library Settings Editor*.
-
-[NOTE]
-You can also retrieve the past circulations on the patron's Items Out screen and from the Check In screen.
-
-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*.
-
-// image::media/mark_missing_damaged_web_client.png[]
-
-[NOTE]
-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.
-
-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*.
-
-//image::media/copy_edit_alert_web_client.png[]
-
-4) Click *Alert Message* in the *Miscellaneous* column. The background color of the box changes. Type in the message then click *Apply*.
-
-//image::media/copy_alert_message_web_client.png[]
-
-5) Click *Modify Copies*, then confirm the action.
-
-
-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.
-
-image::media/long_overdue1.jpg[Patron Account-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.
-
-image::media/long_overdue2.jpg[Long Overdue Checkin]
-
-*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_LONGOVERDUE.override
-
-** Allows the user to check-in long-overdue items thus removing the long-overdue status on the item
-
-
-
--- /dev/null
+Circulation - Patron Record
+---------------------------
+
+[[circulation_searching_patrons]]
+Searching Patrons
+~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, searching for]
+
+To search for a patron, select the Patron Search option from the toolbar,
+_Search -> Search for Patrons_ from the menu bar, or *F4*.
+
+The Patron Search screen will display. The orientation of the search pane may
+be vertical or horizontal, depending on your library’s configuration. It will
+contain options to search on the following fields:
+
+* Last Name
+* First Name
+* Middle Name
+* Alias
+* Address 1
+* Address 2
+* City
+* Zip
+* Phone
+* Email
+* State
+* Barcode
+* OPAC Login ID
+
+Use the options above the search fields to include patrons marked ``inactive''
+in your search results or to limit results to patrons in a specific library
+branch or in a specific permission group.
+
+image::media/circulation_patron_records-1.png[circulation_patron_records 1]
+
+.Tips for searching
+[TIP]
+===================
+* Search one field or combine fields for more precise results.
+* Truncate search terms for more search results.
+===================
+
+Once you have located the desired patron, highlight the entry for this patron in
+the results screen. A summary for this patron will display in place of the
+search fields.
+
+image::media/circulation_patron_records-2.png[circulation_patron_records 2]
+
+Use the _Retrieve Patron_ button to retrieve the patron for circulation or
+editing.
+
+image::media/circulation_patron_records-3.png[circulation_patron_records 3]
+
+The _Search Form_ button may be used to resume searching for patrons.
+
+Registering New Patrons
+~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, registering]
+
+To register a new patron, select _Patron Registration_ from the toolbar,
+_Circulation -> Register Patron_ from the menu bar, or *shift + F1*. The Patron
+Registration form will display.
+
+image::media/circulation_patron_records-4.png[Patron registration form]
+
+Mandatory fields display in yellow.
+
+image::media/circulation_patron_records-5.png[circulation_patron_records 5]
+
+The _Show Only Required Fields_ and _Show Suggested Fields_ may be used to limit
+the options on this page.
+
+image::media/circulation_patron_records-6.png[circulation_patron_records 6]
+
+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_.
+
+image::media/circulation_patron_records-7.png[circulation_patron_records 7]
+
+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.
+
+image::media/circulation_patron_records-8.png[circulation_patron_records 8]
+
+[TIP]
+============================================================================
+* 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.
+============================================================================
+
+New Patron Duplicate Search
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As a new patron is being registered Evergreen checks some of the information entered against existing patrons to catch duplicate registrations.
+
+The fields that are checked are patron name (_First Name_ and _Last Name_), _Email_, _Daytime Phone_, _Evening Phone_, and _Other Phone_. Both active and inactive patrons are checked.
+
+When a match is found a link will appear indicating how many duplicate patrons there are and what information they match on.
+
+image::media/patron-reg-duplicate-search-1.png[patron registration]
+
+To view the duplicate matches click on the link. This performs a patron search in a new tab.
+
+WARNING: This search only includes inactive patrons if the _Include inactive patrons?_ check box is checked.
+
+image::media/patron-reg-duplicate-search-2.png[patron search]
+
+
+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.”
+
+image::media/patron_self_registration2.jpg[Patron Self-Registration form]
+
+*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 *Delete* a pending patron account or *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, right-click and select *Load Patron* or 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.
+
+
+
+*Library Settings*
+
+Three new Library Settings have been created to manage patron self-registration:
+
+* *OPAC: Allow Patron Self-Registration* must be set to ‘True’ to enable use of this feature.
+
+* *OPAC: Patron Self-Reg. Expire Interval* allows each library to set the amount of time after which pending patron accounts should be deleted.
+
+* *OPAC: Patron Self-Reg. Display Timeout* allows each library to set the amount of time after which the patron self-registration screen will timeout in the OPAC. The default is 5 minutes.
+
+Several existing Library Settings can be used to determine if a field should be required or hidden in the self-registration form:
+
+* *GUI: Require day_phone field on patron registration*
+
+* *GUI: Show day_phone on patron registration*
+
+* *GUI: Require dob (date of birth) field on patron registration*
+
+* *GUI: Show dob field on patron registration*
+
+* *GUI: Require email field on patron registration*
+
+* *GUI: Show email field on patron registration*
+
+* *GUI: Require State field on patron registration*
+
+* *GUI: Show State field on patron registration*
+
+* *GUI: Require county field on patron registration*
+
+* *GUI: Show county field on patron registration* [New Setting]
+
+Several existing Library Settings can be used to verify values in certain fields and provide examples for data format on the registration form:
+
+* *Global: Patron username format*
+
+* *GUI: Regex for phone fields on patron registration* OR *GUI: Regex for day_phone field on patron registration*
+
+* *GUI: Regex for email field on patron registration*
+
+* *GUI: Regex for post_code field on patron registration*
+
+* *GUI: Example for email field on patron registration*
+
+* *GUI: Example for post_code field on patron registration*
+
+* *GUI: Example for day_phone field on patron registration* OR *GUI: Example for phone fields on patron registration*
+
+
+
+[[updating_patron_information]]
+Updating Patron Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, updating]
+
+Retrieve the patron record as described in the section
+<<circulation_searching_patrons,Searching Patrons>>.
+
+Select _Edit_ from the options that display at the top of the patron record.
+
+image::media/circulation_patron_records-9.png[Patron edit with summary display]
+
+Edit information as required. When finished, select _Save_. If you attempt to
+close out of the patron account before the information is received, an alert
+will display.
+
+image::media/circulation_patron_records-10.png[circulation_patron_records 10]
+
+Select _OK_ to continue or _Cancel_ to return to the editing form.
+
+After selecting _Save_, the page will refresh. The edited information will be
+reflected in the patron summary pane.
+
+[TIP]
+=======
+* You can resize the patron summary pane, or collapse and expand it using
+the button on the right border of the 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.
+=======
+
+Renewing Library Cards
+~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[library cards, renewing]
+
+Expired patron accounts display with a black box around the patron’s name, a
+note that the patron is expired, and – when initially retrieved – an alert
+stating that the ``Patron account is EXPIRED.''
+
+image::media/circulation_patron_records-11.png[circulation_patron_records 11]
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,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.
+
+image::media/circulation_patron_records-12.png[circulation_patron_records 12]
+
+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.
+
+Lost Library Cards
+~~~~~~~~~~~~~~~~~~
+
+indexterm:[library cards, replacing]
+
+Retrieve the patron record as described in the section
+<<circulation_searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Next to the _Barcode_ field, select the _Replace Barcode_ button.
+
+image::media/circulation_patron_records-13.png[circulation_patron_records 13]
+
+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
+<<circulation_searching_patrons,Searching Patrons>>. Open the patron record in
+edit mode as described in the section <<updating_patron_information,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.
+
+image::media/circulation_patron_records-14.png[circulation_patron_records 14]
+
+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.
+
+Resetting Patron's Password
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, passwords]
+
+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 <<circulation_searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Select the _Reset Password_ button next to the _Password_ field.
+
+image::media/circulation_patron_records-15.png[circulation_patron_records 15]
+
+NOTE: 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.
+
+
+[TIP]
+=======================
+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:
+
+[source, sql]
+------------------------------------------------------------------------------
+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.
+
+[source, sql]
+------------------------------------------------------------------------------
+UPDATE actor.usr SET passwd = <password> WHERE id=<id of row to be updated>;
+------------------------------------------------------------------------------
+
+The new password will automatically be hashed.
+
+=======================
+
+Barring a Patron
+~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, barring]
+
+A patron may be barred from circulation activities. To bar a patron, retrieve
+the patron record as described in the section
+<<circulation_searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Check the box for _Barred_ in the patron account.
+
+image::media/circulation_patron_records-16.png[circulation_patron_records 16]
+
+_Save_ the user. The screen will refresh.
+
+The patron account will now display an alert stating that the patron account
+is *BARRED*.
+
+Additionally a red box and note will indicate the patron’s barred status.
+
+image::media/circulation_patron_records-17.png[circulation_patron_records 17]
+
+NOTE: Barring a patron from one library bars that patron from all consortium
+member libraries.
+
+To unbar a patron, uncheck the Barred checkbox.
+
+Barred vs. Blocked
+~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, barring]
+
+*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.
+
+indexterm:[patrons, blocking]
+
+*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.
+
+
+Staff-Generated Messages
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[staff_generated_messages]]
+indexterm:[patrons, 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, and create a clickable (See Notes) message beneath the patron name on the patron record screen. These notes can be viewable by staff only or shared with the patron. Staff initials can be required. (See the section <<circulation_patron_notes,Patron Notes>> for more.)
+
+*Patron Alerts*: This type of alert is added via _Edit_ button in the patron record. It creates a non-blocking alert message which displays when the patron is retrieved. It also creates a clickable (Alert) message beneath the patron name on the patron record screen. There is currently no way to require staff initials for this type of alert. (See the section <<circulation_patron_alerts,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,Staff-Generated Penalties/Messages>> for more.)
+
+*Patron Message Center*: 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 the section <<patron_message_center>> for more.)
+
+Patron Alerts
+~~~~~~~~~~~~~~
+
+[[circulation_patron_alerts]]
+indexterm:[patrons, Alerts]
+
+When an account has an alert on it, a Stop sign is displayed when the record is
+retrieved.
+
+image::media/circulation_patron_records-18.png[circulation_patron_records 18]
+
+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_.
+
+image::media/circulation_patron_records-19.png[circulation_patron_records 19]
+
+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 <<circulation_searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Enter the alert text in the Alert Message field.
+
+image::media/circulation_patron_records-20.png[circulation_patron_records 20]
+
+_Save_ the record. The screen will refresh and the alert will display.
+
+Additionally, the patron name will be highlighted in yellow and a note will
+indicate that there is an alert on the account.
+
+image::media/circulation_patron_records-21.png[circulation_patron_records 21]
+
+To remove the alert, retrieve the patron record as described in the section
+<<circulation_searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,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.
+
+Patron Notes
+~~~~~~~~~~~~
+
+[[circulation_patron_notes]]
+indexterm:[patrons, notes]
+
+When a patron account contains a note, a _See Notes_ message appears beneath the
+patron’s name in the patron summary pane.
+
+image::media/circulation_patron_records-22.png[circulation_patron_records 22]
+
+Notes are strictly communicative and may be made visible to the patron via their
+account on the OPAC. These notes appear in the <<_patron_message_center,
+Patron Message Center>>.
+
+image::media/circulation_patron_records-23.png[circulation_patron_records 23]
+
+To insert or remove a note, retrieve the patron record as described in the
+section <<circulation_searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Use the Other menu to navigate to _Notes_.
+
+image::media/circulation_patron_records-24.png[circulation_patron_records 24]
+
+Select the _Add New Note_ button. An _Add Note_ window displays.
+
+[TIP]
+================================================
+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,Library Settings Editor>> section.
+================================================
+
+Enter note information.
+
+Select the check box for _Patron Visible_ to display the note in the OPAC.
+
+image::media/circulation_patron_records-25.png[circulation_patron_records 25]
+
+Select _Add Note_ to save the note to the patron account.
+
+To delete a note, go to _Other -> Notes_ and use the _Delete This Note_ button
+under each note.
+
+image::media/circulation_patron_records-26.png[circulation_patron_records 26]
+
+An alert will display. Click _Yes_ to delete the note or No to retain the note.
+A confirmation box will display; click _OK_.
+
+
+Staff-Generated Penalties/Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[staff_generated_penalties]]
+To access this feature, use the _Messages_ button in the patron record.
+
+image::media/staff-penalties-1.jpg[Messages screen]
+
+Add a Message
+^^^^^^^^^^^^^
+
+Click *Apply Standing Penalty/Message* to begin the process of adding a message to the patron.
+
+image::media/staff-penalties-2.jpg[Apply Penalty Dialog Box]
+
+There are three options: Notes, Alerts, Blocks
+
+* *Note*: This will create a non-blocking, non-alerting note visible to staff. Staff will be alerted to the message by the light-blue framing around the patron name, and 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 <<circulation_patron_notes,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 generate a dark-blue frame around the patron name. 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 *Apply*
+
+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.
+
+image::media/staff-penalties-3.jpg[Messages on a record]
+
+Modify a Message
+^^^^^^^^^^^^^^^^
+
+Messages can be edited by staff after they are created.
+
+image::media/staff-penalties-4.jpg[Actions menu]
+
+Click to select the message to be modified, then click _Actions for these Penalties/Messages_ -> _Modify Penalty/Message_. This menu can also be accessed by right-clicking in the message area.
+
+image::media/staff-penalties-5.jpg[Modify penalty dialog box]
+
+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 *Modify* to submit the alterations.
+
+image::media/staff-penalties-6.jpg[Modified message in the list]
+
+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.
+
+image::media/staff-penalties-4.jpg[Actions menu]
+
+Click to select the message to be archived, then click _Actions for these Penalties/Messages_ -> _Archive Penalty/Message_. This menu can also be accessed by right-clicking in the message area.
+
+image::media/staff-penalties-7.jpg[Archived messages]
+
+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*.
+
+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.
+
+image::media/staff-penalties-4.jpg[Actions menu]
+
+Click to select the message to be removed, then click _Actions for these Penalties/Messages_ -> _Remove Penalty/Message_. This menu can also be accessed by right-clicking in the message area.
+
+Patron Message Center
+~~~~~~~~~~~~~~~~~~~~~
+
+[[patron_message_center]]
+
+Creating a Patron Message in the Patron Account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Retrieve a patron account in the staff client.
+2. Within the account, go to *Other -> Notes*.
+3. In the Notes interface, click on *Add New Note*. A new window will pop up that allows you to create a note on the patron account.
+
+image::media/message_center1.PNG[Message Center 1]
+
+4. Check the box next to *Patron Visible?* This will make the message appear in the patron's OPAC account.
+5. Enter a subject for the message in the *Title* field.
+6. Enter the body of the message in the *Note* field.
+7. Enter *Initials* if staff are required to add initials to notes.
+8. Click, *Add Note*. The note will now appear as a Patron Visible note in the staff client and as a Message in the patron's OPAC Account.
+
+image::media/message_center2.PNG[Message Center 2]
+
+9.The patron visible note will also create a message in the patron account in the staff client in *Other -> Message Center*. See *Managing Patron Messages in the Staff Client* below.
+
+Creating a Patron Message using Action Triggers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Messages can be automatically added to a patron's OPAC account by an Action Trigger event. For example, when a hold is cancelled by a library staff member, a message can be added to the patron's OPAC account to inform them of the cancellation.
+
+Action Trigger Messages are set up in *Admin -> Local Administration -> Notifications/Action Triggers*. There are several new fields in the Trigger Event Definition that allow the configuration of Patron Messages:
+
+* Message Library Path: identifies the sending library for the message. This is the patron's home library (usr.home_ou) in the stock Hold Cancellation message.
+* Message Template: contains the content of the message.
+* Message Title: appears as the subject line in the OPAC message.
+* Message User Path: determines how to identify the user the message is sent to.
+
+NOTE: If you want to send patrons a notification email and an OPAC message when their hold is cancelled, use two separate Action Triggers: one for the email notification and one for the message.
+
+Managing Patron Messages in the Staff Client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Patron messages can be viewed and managed in the staff client within the patron account.
+
+. Retrieve a patron account in the staff client.
+. Within the account, go to *Other -> Message Center*.
+. Double click on a message to view the full title and content as well as the date and time the message was created and the date and time that the message was read. Staff can also see if a patron has deleted the message from their OPAC account (Deleted?) and can manually delete a message by marking it as Deleted.
+
+NOTE: When a message is marked deleted, the message will remain in Other -> Message Center as a record that the patron received it.
+
+NOTE: Deleting a patron visible note in Other -> Notes will not delete the patron message from the Other -> Message Center.
+
+image::media/message_center9.PNG[Message Center 9]
+
+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.
+
+image::media/message_center11.PNG[Message Center 11]
+
+Patrons will see a list of the messages from the library by clicking on the *Messages* tab.
+
+image::media/message_center10.PNG[Message Center 10]
+
+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.
+
+image::media/message_center12.PNG[Message Center 12]
+
+NOTE: Patron deleted messages will still appear in the patron's account in the staff client under Other -> Message Center.
+
+Merging Patron Records
+~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, merging]
+
+When patron records are erroneously duplicated, they may be merged into one
+record. As described in the section <<circulation_searching_patrons,Searching
+Patrons>>, search for the term(s) shared by the two records.
+
+Select the two records to merge by pressing down the CTRL key and clicking each
+record.
+
+Click the _Merge Patrons_ button next to the _Search Form_ and _Retrieve Patron_
+buttons on the top of the screen.
+
+image::media/circulation_patron_records-27.png[circulation_patron_records 27]
+
+A Record Merging window will display. Compare the two records.
+
+Select the record you want to keep by checking the radio button
+_Lead Record_ next to the appropriate record.
+
+image::media/circulation_patron_records-28.png[circulation_patron_records 28]
+
+After making your selection, click the _Merge_ button. The screen will refresh.
+Only one of the two patron names will display.
+
+NOTE: Once two records have been merged, the notes, bills, holds and outstanding
+items under the non-lead record are brought to the lead record. Staff-inserted
+alert messages are not transferred from the non-lead record; lead record alerts
+are retained.
+
+Patron records may also be merged from the _Patron Group_ screen Retrieve one of
+the two patron records you want to merge.
+
+Go to _Other -> Group Member Details_.
+
+image::media/circulation_patron_records-29.png[circulation_patron_records 29]
+
+The patron records are displayed as group members. If both patron records are
+not already displayed on this screen, click _Choose an Action -> Move another
+patron to this patron group_.
+
+image::media/circulation_patron_records-30.png[circulation_patron_records 30]
+
+At the prompt, scan or type the patron's barcode.
+
+Click _OK_.
+
+Confirm the move by clicking the _Move_ button on top of the screen.
+
+image::media/circulation_patron_records-31.png[circulation_patron_records 31]
+
+Click _OK_ on the confirmation pop-up window.
+
+Both records are displayed as group members.
+
+Select both records by pressing *CTRL* key and clicking each record.
+
+Click _Choose an Action -> Merge Selected Patrons_. The merging records window
+pops up.
+
+Choose the lead record and continue to merge records as described in the above.
+
+NOTE: The merged record will still show under group members. Both members point
+to the same patron record.
+
+[[bills_and_payments]]
+Bills and Payments
+~~~~~~~~~~~~~~~~~~
+
+When a patron account has bills attached to it, a note displays under the patron
+name in the patron summary panel.
+
+image::media/circulation_patron_bills-1.png[circulation_patron_bills 1]
+
+To view more information about the patron’s bills, or to make payments on or
+edit the bills, click on the Bills button from the patron account screen.
+
+image::media/circulation_patron_bills-2.png[circulation_patron_bills 2]
+
+The Bills Interface
+^^^^^^^^^^^^^^^^^^^
+All current bills are itemized in the grid in the bills interface. Click on a
+column header to sort bills in this grid. Most columns sort alphabetically, but
+the "Total Billed" and *Total Paid* columns sort numerically.
+
+Colors distinguish bills for items that are attached to checked out, lost and
+long overdue circulations. These colors are accompanied by helpful indicators
+that define the meaning of the colors for staff.
+
+By default, circulations that are still checked out appear in bright red. The
+default indicator reads, "Red Items are still Checked out.
+
+Lost circulations will appear in dark red. The default indicator reads,
+“Dark Red Items are Lost.”
+
+When the 6 Month Overdue Mark Long-Overdue trigger event definition is enabled,
+Long Overdue circulations will appear in orange, by default. The default
+indicator reads, “Orange Items are Long Overdue.”
+
+image::media/Billed_Transaction_Color.jpg[Billed Transaction Color]
+
+Both the color distinctions and indicators are customizable. To customize, a
+change to circ.css (for the color) and lang.dtd (for the indicator) are
+required.
+
+
+[[circ_vs_grocery]]
+*Circulation bills*: system-generated (overdue fines, lost
+item cost, processing fees, etc.).
+
+* Overdue fines are added daily once an item is overdue.
+* When an item is marked as lost or long overdue, bills may be automatically
+generated to cover the item's cost and a processing fee, according to library
+policy.
+
+*Grocery bills*: staff-applied to patron accounts.
+
+* One default grocery bill, Misc, exists in an unmodified Evergreen
+installation.
+* Additional grocery bills may be configured through the Admin settings. *Admin*
+ -> *Server Administration* -> *Billing Types*.
+
+To view more information about a bill, highlight the bill and right-click or use
+the _Actions for Selected Transactions_ menu to select _Full Details_.
+
+image::media/circulation_patron_bills-3.png[circulation_patron_bills 3]
+
+A window will display additional information about the bill, including a record
+of any payments that have been made on the bill.
+
+image::media/circulation_patron_bills-4.png[circulation_patron_bills 4]
+
+From the _Full Details_ screen, portions of the bill may be voided (e.g. an
+erroneous daily overdue charge) by using the _Void selected billings_ button.
+Notes may be added to payments or line items by using the _Edit note_ button.
+
+image::media/circulation_patron_bills-5.png[circulation_patron_bills 5]
+
+[[making_payments]]
+Making Payments
+^^^^^^^^^^^^^^^
+
+To collect payments, retrieve the patron record. Navigate to the _Bills_ screen
+as described in <<bills_and_payments,Bills and Payments>>.
+
+When bills are paid, the money applied starts at the top of the list of bills.
+To pay specific bills, uncheck the bills that you do not wish to pay at this
+time. The amount displayed in _Total Checked:_ will change to reflect the
+appropriate amount.
+
+image::media/circulation_patron_bills-6.png[circulation_patron_bills 6]
+
+[TIP]
+By default, Evergreen checks all bills when the bills screen loads.
+Evergreen sites can change this default by enabling the _Uncheck bills by
+default in the patron billing interface_ setting in the Library Settings
+Editor (*Admin* -> *Local Administration* -> *Library Settings Editor*). Note
+the presence of the _Uncheck All_ and _Check All_ options below the list of
+bills.
+
+image::media/circulation_patron_bills-7.png[circulation_patron_bills 7]
+
+When you are ready to make a payment, select a payment type from the dropdown
+menu in the _Pay Bill_ portion of the screen.
+
+image::media/circulation_patron_bills-8.png[circulation_patron_bills 8]
+
+Enter the amount of payment in the _Payment received_ field.
+
+If you would like to add a note to the payment, check the box for
+_Annotate Payment_.
+
+Click _Apply Payment!_ to make the payment.
+
+If you have selected _Annotate Payment_, a box will display for the annotation.
+
+The screen will refresh to display the updated bill information for the patron.
+If change is due, the bottom portion of the screen, _Change Due Upon Payment:_
+will briefly reflect the amount due to the patron.
+
+TIP: if you need more time to review the amount due, click outside the _Payment
+Received_ box before selecting _Apply Payment!_ This will cause the screen to
+refresh and display the amount due.
+
+[TIP]
+================================================
+* Items marked with red are still checked out. Items marked with dark red are
+lost. Items marked with orange are still checked out and long overdue.
+* It is possible for a patron to pay a bill while the item is still out and
+accruing fines.
+* When Check is selected as the payment type, it is not necessary to select
+_Annotate Payment_, as a box for the check number and a note displays
+automatically.
+* If a patron pays the entire bill for a lost item and the library has enabled
+the _Use Lost and Paid copy status_ setting in the Library Settings Editor
+(*Admin* -> *Local Administration* -> *Library Settings Editor*), the copy's
+status will automatically change from _Lost_ to _Lost and Paid_.
+================================================
+
+Patron Credits
+^^^^^^^^^^^^^^
+It is possible to convert change due to a patron credit by selecting the
+_Convert Change to Patron Credit_ checkbox and to later apply that credit to a
+bill by selecting the _Patron Credit_ payment type.
+
+By default, the payment type *Patron Credit* is enabled in the staff client.
+Within the Bills interface of a patron’s account, the Patron Credit payment
+type, the Credit Available, and the option to Convert Change to Patron Credit
+are exposed by default in the staff client.
+
+image::media/Default_Patron_Billing_Screen.jpg[Default Patron Billing Screen]
+
+The Library Setting, *Disable Patron Credit*, allows staff to disable the Patron
+Credit payment type and to hide patron credit payment actions within the billing
+interface of a patron’s account. If a library doesn't use patron credits, the
+library will want to enable this setting to prevent accidental selection of the
+checkbox that converts change to patron credit.
+
+When the Library Setting, *Disable Patron Credit*, is set to *True*,
+the patron credit payment type will be disabled.
+Patron Credit will not be an option within the payment type dropdown menu.
+The Convert Change to Patron Credit and the summary of Credit Available will be
+hidden from the patron billing interface in the staff client.
+
+image::media/Disabled_Patron_Credit_Patron_Billing_Screen.jpg[Disabled Patron Credit Patron Billing Screen]
+
+To set the Library Setting:
+
+. Click *Admin* -> *Local Administration* -> *Library Settings Editor*
+
+. Search for *Disable Patron Credit*
+
+. Click *Edit*
+
+. Set the value to *True*
+
+. Click *Update Setting*
+
+image::media/Disable_Patron_Credit_Library_Setting.jpg[Disable Patron Credit Library Setting]
+
+NOTE: After applying changes to this library setting, it is necessary to restart
+the staff client to see the changes take effect.
+
+
+Void vs. Forgive vs. Adjustment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are guidelines for using void, forgive, and adjust when clearing
+bills off a patron record.
+
+* Use forgive when staff is waiving a portion/all of a bill. A forgive_payment
+payment type will be used to credit the bill. The history of the bill will be
+retained.
+
+* Use void when the bill should not be on the patron record and when the goal
+is to remove the entire bill. Once voided, there will be no history of the bill
+available from the staff client. If the bill was partially paid before voiding,
+a negative balance will be produced.
+
+* Use adjust to zero when the bill should not be on the patron record and when
+the goal is to remove the balance of the bill. An account_adjustment payment
+type will be used to adjust the bill's balance. The history of the bill will be
+retained and available from the Bill History interface of the staff client.
+
+
+Forgiving Bills
+^^^^^^^^^^^^^^^
+
+Choose forgive as the payment type as described in the section
+<<making_payments,Making Payments>>.
+
+Enter the amount to be forgiven. Choose _Annotate Payment_ as required by local
+policy.
+
+Apply Payment. Annotate, if prompted.
+
+The screen will refresh to display the payment.
+
+
+Voiding Bills
+^^^^^^^^^^^^^
+
+Bills under one transaction are grouped in one bill line. Bills may be voided in
+part or in whole.
+
+*To void the full billing amount:*
+
+Select the bill(s) to be voided from the list in the patron account.
+
+Right click or use the _Actions for Selected Transactions_ menu to select _Void
+All Billings_.
+
+image::media/circulation_patron_bills-10.png[circulation_patron_bills 10]
+
+Confirm the action.
+
+*To void a partial amount:*
+
+Select a billing and choose Full Details for the transaction, as described in
+the section <circ_vs_grocery,Circulation vs. Grocery Bills>>
+
+The bill details screen displays.
+
+Select the specific bill to void.
+
+Void Selected Billings and confirm the action.
+
+image::media/circulation_patron_bills-11.png[circulation_patron_bills 11]
+
+Adjusting Bills to Zero
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In the Bills interface, select the bill to adjust.
+
+Right click or use the _Actions for Selected Transactions_ menu to select
+_Adjust to Zero_.
+
+image::media/adjust_to_zero_action.png[adjust_to_zero_action.png]
+
+Confirm the action.
+
+Adding New ``Grocery'' Bills
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A grocery bill can be added as a new bill or to an existing bill.
+
+*To add a as a new bill:*
+
+. Retrieve the patron record.
+. Navigate to the Bills screen.
+. Click the_Bill Patron_ button above the list of current bills.
++
+image::media/circulation_patron_bills-12.png[circulation_patron_bills 12]
++
+.Choose appropriate _Billing Type_ from the drop down menu. (``Grocery'' is the
+only available transaction type.) . Enter the Amount and Note (as required).
+.
+_Submit this Bill_ and confirm this action.
+
+image::media/circulation_patron_bills-13.png[circulation_patron_bills 13]
+
+*To add bill to an existing bill line:*
+
+. Retrieve the patron record.
+. Navigate to the Bills screen.
+. Highlight the desired bill.
+. Use the _Actions for Selected Transactions_ to select _Add Billing_.
+Confirm this action.
+. Follow steps 4 through 6 above. There is no confirmation message
+after clicking _Submit this Bill_.
+. The _Money Summary_ will adjust accordingly.
+
+Negative Balances on Patron Accounts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a library has not enabled Prohibit Negative Balance settings via the library
+settings editor, certain workflows and settings can create a negative balance on
+a patron's account. See...for information on settings that affect negative
+balances.
+
+[[removing_negative_balances]]
+
+*Removing negative balances from a patron account*
+
+A negative balance can be cleared either by refunding a bill or by adjusting the
+bill to zero.
+
+To refund the bill:
+
+1) Select the billing with the negative balance.
+
+2) Choose **Actions for Selected Transactions** --> **Refund**.
+
+3) Click Yes.
+
+4) Click Apply Payment.
+
+The refunded amount will be deducted from the cash_payment total in the
+workstations Cash Report.
+
+To clear the negative balance without affecting the Cash Report:
+
+1) Right click on the billing with the negative balance.
+
+2) Select **Adjust to zero**.
+
+3) Click Yes.
+
+
+Bill History
+^^^^^^^^^^^^
+
+*To view a patron’s bill history:*
+
+. Retrieve the patron record.
+. From the _Bills_ screen, click _History_.
+. A _Bill History_ screen with two tabs will display. One for _Transactions_
+and one for _Payments_.
++
+image::media/circulation_patron_bills-14.png[circulation_patron_bills 14]
++
+. For more information about a specific billing, select the bill and click _Full
+Details_. A screen detailing item information, billings, and payments will
+display.
+
+image::media/circulation_patron_bills-15.png[circulation_patron_bills 15]
+
+Items may be deleted from the catalog even if a charge for that item is still
+attached to the patron's record. The charge will remain on the patron's account
+after the deletion.
+
+++ /dev/null
-Circulation - Patron Record
----------------------------
-
-[[circulation_searching_patrons]]
-Searching Patrons
-~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, searching for]
-
-To search for a patron, select the Patron Search option from the toolbar,
-_Search -> Search for Patrons_ from the menu bar, or *F4*.
-
-The Patron Search screen will display. The orientation of the search pane may
-be vertical or horizontal, depending on your library’s configuration. It will
-contain options to search on the following fields:
-
-* Last Name
-* First Name
-* Middle Name
-* Alias
-* Address 1
-* Address 2
-* City
-* Zip
-* Phone
-* Email
-* State
-* Barcode
-* OPAC Login ID
-
-Use the options above the search fields to include patrons marked ``inactive''
-in your search results or to limit results to patrons in a specific library
-branch or in a specific permission group.
-
-image::media/circulation_patron_records-1.png[circulation_patron_records 1]
-
-.Tips for searching
-[TIP]
-===================
-* Search one field or combine fields for more precise results.
-* Truncate search terms for more search results.
-===================
-
-Once you have located the desired patron, highlight the entry for this patron in
-the results screen. A summary for this patron will display in place of the
-search fields.
-
-image::media/circulation_patron_records-2.png[circulation_patron_records 2]
-
-Use the _Retrieve Patron_ button to retrieve the patron for circulation or
-editing.
-
-image::media/circulation_patron_records-3.png[circulation_patron_records 3]
-
-The _Search Form_ button may be used to resume searching for patrons.
-
-Registering New Patrons
-~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, registering]
-
-To register a new patron, select _Patron Registration_ from the toolbar,
-_Circulation -> Register Patron_ from the menu bar, or *shift + F1*. The Patron
-Registration form will display.
-
-image::media/circulation_patron_records-4.png[Patron registration form]
-
-Mandatory fields display in yellow.
-
-image::media/circulation_patron_records-5.png[circulation_patron_records 5]
-
-The _Show Only Required Fields_ and _Show Suggested Fields_ may be used to limit
-the options on this page.
-
-image::media/circulation_patron_records-6.png[circulation_patron_records 6]
-
-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_.
-
-image::media/circulation_patron_records-7.png[circulation_patron_records 7]
-
-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.
-
-image::media/circulation_patron_records-8.png[circulation_patron_records 8]
-
-[TIP]
-============================================================================
-* 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.
-============================================================================
-
-New Patron Duplicate Search
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-As a new patron is being registered Evergreen checks some of the information entered against existing patrons to catch duplicate registrations.
-
-The fields that are checked are patron name (_First Name_ and _Last Name_), _Email_, _Daytime Phone_, _Evening Phone_, and _Other Phone_. Both active and inactive patrons are checked.
-
-When a match is found a link will appear indicating how many duplicate patrons there are and what information they match on.
-
-image::media/patron-reg-duplicate-search-1.png[patron registration]
-
-To view the duplicate matches click on the link. This performs a patron search in a new tab.
-
-WARNING: This search only includes inactive patrons if the _Include inactive patrons?_ check box is checked.
-
-image::media/patron-reg-duplicate-search-2.png[patron search]
-
-
-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.”
-
-image::media/patron_self_registration2.jpg[Patron Self-Registration form]
-
-*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 *Delete* a pending patron account or *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, right-click and select *Load Patron* or 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.
-
-
-
-*Library Settings*
-
-Three new Library Settings have been created to manage patron self-registration:
-
-* *OPAC: Allow Patron Self-Registration* must be set to ‘True’ to enable use of this feature.
-
-* *OPAC: Patron Self-Reg. Expire Interval* allows each library to set the amount of time after which pending patron accounts should be deleted.
-
-* *OPAC: Patron Self-Reg. Display Timeout* allows each library to set the amount of time after which the patron self-registration screen will timeout in the OPAC. The default is 5 minutes.
-
-Several existing Library Settings can be used to determine if a field should be required or hidden in the self-registration form:
-
-* *GUI: Require day_phone field on patron registration*
-
-* *GUI: Show day_phone on patron registration*
-
-* *GUI: Require dob (date of birth) field on patron registration*
-
-* *GUI: Show dob field on patron registration*
-
-* *GUI: Require email field on patron registration*
-
-* *GUI: Show email field on patron registration*
-
-* *GUI: Require State field on patron registration*
-
-* *GUI: Show State field on patron registration*
-
-* *GUI: Require county field on patron registration*
-
-* *GUI: Show county field on patron registration* [New Setting]
-
-Several existing Library Settings can be used to verify values in certain fields and provide examples for data format on the registration form:
-
-* *Global: Patron username format*
-
-* *GUI: Regex for phone fields on patron registration* OR *GUI: Regex for day_phone field on patron registration*
-
-* *GUI: Regex for email field on patron registration*
-
-* *GUI: Regex for post_code field on patron registration*
-
-* *GUI: Example for email field on patron registration*
-
-* *GUI: Example for post_code field on patron registration*
-
-* *GUI: Example for day_phone field on patron registration* OR *GUI: Example for phone fields on patron registration*
-
-
-
-[[updating_patron_information]]
-Updating Patron Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, updating]
-
-Retrieve the patron record as described in the section
-<<circulation_searching_patrons,Searching Patrons>>.
-
-Select _Edit_ from the options that display at the top of the patron record.
-
-image::media/circulation_patron_records-9.png[Patron edit with summary display]
-
-Edit information as required. When finished, select _Save_. If you attempt to
-close out of the patron account before the information is received, an alert
-will display.
-
-image::media/circulation_patron_records-10.png[circulation_patron_records 10]
-
-Select _OK_ to continue or _Cancel_ to return to the editing form.
-
-After selecting _Save_, the page will refresh. The edited information will be
-reflected in the patron summary pane.
-
-[TIP]
-=======
-* You can resize the patron summary pane, or collapse and expand it using
-the button on the right border of the 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.
-=======
-
-Renewing Library Cards
-~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[library cards, renewing]
-
-Expired patron accounts display with a black box around the patron’s name, a
-note that the patron is expired, and – when initially retrieved – an alert
-stating that the ``Patron account is EXPIRED.''
-
-image::media/circulation_patron_records-11.png[circulation_patron_records 11]
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,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.
-
-image::media/circulation_patron_records-12.png[circulation_patron_records 12]
-
-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.
-
-Lost Library Cards
-~~~~~~~~~~~~~~~~~~
-
-indexterm:[library cards, replacing]
-
-Retrieve the patron record as described in the section
-<<circulation_searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Next to the _Barcode_ field, select the _Replace Barcode_ button.
-
-image::media/circulation_patron_records-13.png[circulation_patron_records 13]
-
-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
-<<circulation_searching_patrons,Searching Patrons>>. Open the patron record in
-edit mode as described in the section <<updating_patron_information,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.
-
-image::media/circulation_patron_records-14.png[circulation_patron_records 14]
-
-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.
-
-Resetting Patron's Password
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, passwords]
-
-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 <<circulation_searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Select the _Reset Password_ button next to the _Password_ field.
-
-image::media/circulation_patron_records-15.png[circulation_patron_records 15]
-
-NOTE: 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.
-
-
-[TIP]
-=======================
-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:
-
-[source, sql]
-------------------------------------------------------------------------------
-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.
-
-[source, sql]
-------------------------------------------------------------------------------
-UPDATE actor.usr SET passwd = <password> WHERE id=<id of row to be updated>;
-------------------------------------------------------------------------------
-
-The new password will automatically be hashed.
-
-=======================
-
-Barring a Patron
-~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, barring]
-
-A patron may be barred from circulation activities. To bar a patron, retrieve
-the patron record as described in the section
-<<circulation_searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Check the box for _Barred_ in the patron account.
-
-image::media/circulation_patron_records-16.png[circulation_patron_records 16]
-
-_Save_ the user. The screen will refresh.
-
-The patron account will now display an alert stating that the patron account
-is *BARRED*.
-
-Additionally a red box and note will indicate the patron’s barred status.
-
-image::media/circulation_patron_records-17.png[circulation_patron_records 17]
-
-NOTE: Barring a patron from one library bars that patron from all consortium
-member libraries.
-
-To unbar a patron, uncheck the Barred checkbox.
-
-Barred vs. Blocked
-~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, barring]
-
-*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.
-
-indexterm:[patrons, blocking]
-
-*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.
-
-
-Staff-Generated Messages
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-[[staff_generated_messages]]
-indexterm:[patrons, 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, and create a clickable (See Notes) message beneath the patron name on the patron record screen. These notes can be viewable by staff only or shared with the patron. Staff initials can be required. (See the section <<circulation_patron_notes,Patron Notes>> for more.)
-
-*Patron Alerts*: This type of alert is added via _Edit_ button in the patron record. It creates a non-blocking alert message which displays when the patron is retrieved. It also creates a clickable (Alert) message beneath the patron name on the patron record screen. There is currently no way to require staff initials for this type of alert. (See the section <<circulation_patron_alerts,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,Staff-Generated Penalties/Messages>> for more.)
-
-*Patron Message Center*: 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 the section <<patron_message_center>> for more.)
-
-Patron Alerts
-~~~~~~~~~~~~~~
-
-[[circulation_patron_alerts]]
-indexterm:[patrons, Alerts]
-
-When an account has an alert on it, a Stop sign is displayed when the record is
-retrieved.
-
-image::media/circulation_patron_records-18.png[circulation_patron_records 18]
-
-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_.
-
-image::media/circulation_patron_records-19.png[circulation_patron_records 19]
-
-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 <<circulation_searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Enter the alert text in the Alert Message field.
-
-image::media/circulation_patron_records-20.png[circulation_patron_records 20]
-
-_Save_ the record. The screen will refresh and the alert will display.
-
-Additionally, the patron name will be highlighted in yellow and a note will
-indicate that there is an alert on the account.
-
-image::media/circulation_patron_records-21.png[circulation_patron_records 21]
-
-To remove the alert, retrieve the patron record as described in the section
-<<circulation_searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,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.
-
-Patron Notes
-~~~~~~~~~~~~
-
-[[circulation_patron_notes]]
-indexterm:[patrons, notes]
-
-When a patron account contains a note, a _See Notes_ message appears beneath the
-patron’s name in the patron summary pane.
-
-image::media/circulation_patron_records-22.png[circulation_patron_records 22]
-
-Notes are strictly communicative and may be made visible to the patron via their
-account on the OPAC. These notes appear in the <<_patron_message_center,
-Patron Message Center>>.
-
-image::media/circulation_patron_records-23.png[circulation_patron_records 23]
-
-To insert or remove a note, retrieve the patron record as described in the
-section <<circulation_searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Use the Other menu to navigate to _Notes_.
-
-image::media/circulation_patron_records-24.png[circulation_patron_records 24]
-
-Select the _Add New Note_ button. An _Add Note_ window displays.
-
-[TIP]
-================================================
-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,Library Settings Editor>> section.
-================================================
-
-Enter note information.
-
-Select the check box for _Patron Visible_ to display the note in the OPAC.
-
-image::media/circulation_patron_records-25.png[circulation_patron_records 25]
-
-Select _Add Note_ to save the note to the patron account.
-
-To delete a note, go to _Other -> Notes_ and use the _Delete This Note_ button
-under each note.
-
-image::media/circulation_patron_records-26.png[circulation_patron_records 26]
-
-An alert will display. Click _Yes_ to delete the note or No to retain the note.
-A confirmation box will display; click _OK_.
-
-
-Staff-Generated Penalties/Messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-[[staff_generated_penalties]]
-To access this feature, use the _Messages_ button in the patron record.
-
-image::media/staff-penalties-1.jpg[Messages screen]
-
-Add a Message
-^^^^^^^^^^^^^
-
-Click *Apply Standing Penalty/Message* to begin the process of adding a message to the patron.
-
-image::media/staff-penalties-2.jpg[Apply Penalty Dialog Box]
-
-There are three options: Notes, Alerts, Blocks
-
-* *Note*: This will create a non-blocking, non-alerting note visible to staff. Staff will be alerted to the message by the light-blue framing around the patron name, and 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 <<circulation_patron_notes,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 generate a dark-blue frame around the patron name. 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 *Apply*
-
-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.
-
-image::media/staff-penalties-3.jpg[Messages on a record]
-
-Modify a Message
-^^^^^^^^^^^^^^^^
-
-Messages can be edited by staff after they are created.
-
-image::media/staff-penalties-4.jpg[Actions menu]
-
-Click to select the message to be modified, then click _Actions for these Penalties/Messages_ -> _Modify Penalty/Message_. This menu can also be accessed by right-clicking in the message area.
-
-image::media/staff-penalties-5.jpg[Modify penalty dialog box]
-
-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 *Modify* to submit the alterations.
-
-image::media/staff-penalties-6.jpg[Modified message in the list]
-
-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.
-
-image::media/staff-penalties-4.jpg[Actions menu]
-
-Click to select the message to be archived, then click _Actions for these Penalties/Messages_ -> _Archive Penalty/Message_. This menu can also be accessed by right-clicking in the message area.
-
-image::media/staff-penalties-7.jpg[Archived messages]
-
-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*.
-
-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.
-
-image::media/staff-penalties-4.jpg[Actions menu]
-
-Click to select the message to be removed, then click _Actions for these Penalties/Messages_ -> _Remove Penalty/Message_. This menu can also be accessed by right-clicking in the message area.
-
-Patron Message Center
-~~~~~~~~~~~~~~~~~~~~~
-
-[[patron_message_center]]
-
-Creating a Patron Message in the Patron Account
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-1. Retrieve a patron account in the staff client.
-2. Within the account, go to *Other -> Notes*.
-3. In the Notes interface, click on *Add New Note*. A new window will pop up that allows you to create a note on the patron account.
-
-image::media/message_center1.PNG[Message Center 1]
-
-4. Check the box next to *Patron Visible?* This will make the message appear in the patron's OPAC account.
-5. Enter a subject for the message in the *Title* field.
-6. Enter the body of the message in the *Note* field.
-7. Enter *Initials* if staff are required to add initials to notes.
-8. Click, *Add Note*. The note will now appear as a Patron Visible note in the staff client and as a Message in the patron's OPAC Account.
-
-image::media/message_center2.PNG[Message Center 2]
-
-9.The patron visible note will also create a message in the patron account in the staff client in *Other -> Message Center*. See *Managing Patron Messages in the Staff Client* below.
-
-Creating a Patron Message using Action Triggers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Messages can be automatically added to a patron's OPAC account by an Action Trigger event. For example, when a hold is cancelled by a library staff member, a message can be added to the patron's OPAC account to inform them of the cancellation.
-
-Action Trigger Messages are set up in *Admin -> Local Administration -> Notifications/Action Triggers*. There are several new fields in the Trigger Event Definition that allow the configuration of Patron Messages:
-
-* Message Library Path: identifies the sending library for the message. This is the patron's home library (usr.home_ou) in the stock Hold Cancellation message.
-* Message Template: contains the content of the message.
-* Message Title: appears as the subject line in the OPAC message.
-* Message User Path: determines how to identify the user the message is sent to.
-
-NOTE: If you want to send patrons a notification email and an OPAC message when their hold is cancelled, use two separate Action Triggers: one for the email notification and one for the message.
-
-Managing Patron Messages in the Staff Client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Patron messages can be viewed and managed in the staff client within the patron account.
-
-. Retrieve a patron account in the staff client.
-. Within the account, go to *Other -> Message Center*.
-. Double click on a message to view the full title and content as well as the date and time the message was created and the date and time that the message was read. Staff can also see if a patron has deleted the message from their OPAC account (Deleted?) and can manually delete a message by marking it as Deleted.
-
-NOTE: When a message is marked deleted, the message will remain in Other -> Message Center as a record that the patron received it.
-
-NOTE: Deleting a patron visible note in Other -> Notes will not delete the patron message from the Other -> Message Center.
-
-image::media/message_center9.PNG[Message Center 9]
-
-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.
-
-image::media/message_center11.PNG[Message Center 11]
-
-Patrons will see a list of the messages from the library by clicking on the *Messages* tab.
-
-image::media/message_center10.PNG[Message Center 10]
-
-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.
-
-image::media/message_center12.PNG[Message Center 12]
-
-NOTE: Patron deleted messages will still appear in the patron's account in the staff client under Other -> Message Center.
-
-Merging Patron Records
-~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, merging]
-
-When patron records are erroneously duplicated, they may be merged into one
-record. As described in the section <<circulation_searching_patrons,Searching
-Patrons>>, search for the term(s) shared by the two records.
-
-Select the two records to merge by pressing down the CTRL key and clicking each
-record.
-
-Click the _Merge Patrons_ button next to the _Search Form_ and _Retrieve Patron_
-buttons on the top of the screen.
-
-image::media/circulation_patron_records-27.png[circulation_patron_records 27]
-
-A Record Merging window will display. Compare the two records.
-
-Select the record you want to keep by checking the radio button
-_Lead Record_ next to the appropriate record.
-
-image::media/circulation_patron_records-28.png[circulation_patron_records 28]
-
-After making your selection, click the _Merge_ button. The screen will refresh.
-Only one of the two patron names will display.
-
-NOTE: Once two records have been merged, the notes, bills, holds and outstanding
-items under the non-lead record are brought to the lead record. Staff-inserted
-alert messages are not transferred from the non-lead record; lead record alerts
-are retained.
-
-Patron records may also be merged from the _Patron Group_ screen Retrieve one of
-the two patron records you want to merge.
-
-Go to _Other -> Group Member Details_.
-
-image::media/circulation_patron_records-29.png[circulation_patron_records 29]
-
-The patron records are displayed as group members. If both patron records are
-not already displayed on this screen, click _Choose an Action -> Move another
-patron to this patron group_.
-
-image::media/circulation_patron_records-30.png[circulation_patron_records 30]
-
-At the prompt, scan or type the patron's barcode.
-
-Click _OK_.
-
-Confirm the move by clicking the _Move_ button on top of the screen.
-
-image::media/circulation_patron_records-31.png[circulation_patron_records 31]
-
-Click _OK_ on the confirmation pop-up window.
-
-Both records are displayed as group members.
-
-Select both records by pressing *CTRL* key and clicking each record.
-
-Click _Choose an Action -> Merge Selected Patrons_. The merging records window
-pops up.
-
-Choose the lead record and continue to merge records as described in the above.
-
-NOTE: The merged record will still show under group members. Both members point
-to the same patron record.
-
-[[bills_and_payments]]
-Bills and Payments
-~~~~~~~~~~~~~~~~~~
-
-When a patron account has bills attached to it, a note displays under the patron
-name in the patron summary panel.
-
-image::media/circulation_patron_bills-1.png[circulation_patron_bills 1]
-
-To view more information about the patron’s bills, or to make payments on or
-edit the bills, click on the Bills button from the patron account screen.
-
-image::media/circulation_patron_bills-2.png[circulation_patron_bills 2]
-
-The Bills Interface
-^^^^^^^^^^^^^^^^^^^
-All current bills are itemized in the grid in the bills interface. Click on a
-column header to sort bills in this grid. Most columns sort alphabetically, but
-the "Total Billed" and *Total Paid* columns sort numerically.
-
-Colors distinguish bills for items that are attached to checked out, lost and
-long overdue circulations. These colors are accompanied by helpful indicators
-that define the meaning of the colors for staff.
-
-By default, circulations that are still checked out appear in bright red. The
-default indicator reads, "Red Items are still Checked out.
-
-Lost circulations will appear in dark red. The default indicator reads,
-“Dark Red Items are Lost.”
-
-When the 6 Month Overdue Mark Long-Overdue trigger event definition is enabled,
-Long Overdue circulations will appear in orange, by default. The default
-indicator reads, “Orange Items are Long Overdue.”
-
-image::media/Billed_Transaction_Color.jpg[Billed Transaction Color]
-
-Both the color distinctions and indicators are customizable. To customize, a
-change to circ.css (for the color) and lang.dtd (for the indicator) are
-required.
-
-
-[[circ_vs_grocery]]
-*Circulation bills*: system-generated (overdue fines, lost
-item cost, processing fees, etc.).
-
-* Overdue fines are added daily once an item is overdue.
-* When an item is marked as lost or long overdue, bills may be automatically
-generated to cover the item's cost and a processing fee, according to library
-policy.
-
-*Grocery bills*: staff-applied to patron accounts.
-
-* One default grocery bill, Misc, exists in an unmodified Evergreen
-installation.
-* Additional grocery bills may be configured through the Admin settings. *Admin*
- -> *Server Administration* -> *Billing Types*.
-
-To view more information about a bill, highlight the bill and right-click or use
-the _Actions for Selected Transactions_ menu to select _Full Details_.
-
-image::media/circulation_patron_bills-3.png[circulation_patron_bills 3]
-
-A window will display additional information about the bill, including a record
-of any payments that have been made on the bill.
-
-image::media/circulation_patron_bills-4.png[circulation_patron_bills 4]
-
-From the _Full Details_ screen, portions of the bill may be voided (e.g. an
-erroneous daily overdue charge) by using the _Void selected billings_ button.
-Notes may be added to payments or line items by using the _Edit note_ button.
-
-image::media/circulation_patron_bills-5.png[circulation_patron_bills 5]
-
-[[making_payments]]
-Making Payments
-^^^^^^^^^^^^^^^
-
-To collect payments, retrieve the patron record. Navigate to the _Bills_ screen
-as described in <<bills_and_payments,Bills and Payments>>.
-
-When bills are paid, the money applied starts at the top of the list of bills.
-To pay specific bills, uncheck the bills that you do not wish to pay at this
-time. The amount displayed in _Total Checked:_ will change to reflect the
-appropriate amount.
-
-image::media/circulation_patron_bills-6.png[circulation_patron_bills 6]
-
-[TIP]
-By default, Evergreen checks all bills when the bills screen loads.
-Evergreen sites can change this default by enabling the _Uncheck bills by
-default in the patron billing interface_ setting in the Library Settings
-Editor (*Admin* -> *Local Administration* -> *Library Settings Editor*). Note
-the presence of the _Uncheck All_ and _Check All_ options below the list of
-bills.
-
-image::media/circulation_patron_bills-7.png[circulation_patron_bills 7]
-
-When you are ready to make a payment, select a payment type from the dropdown
-menu in the _Pay Bill_ portion of the screen.
-
-image::media/circulation_patron_bills-8.png[circulation_patron_bills 8]
-
-Enter the amount of payment in the _Payment received_ field.
-
-If you would like to add a note to the payment, check the box for
-_Annotate Payment_.
-
-Click _Apply Payment!_ to make the payment.
-
-If you have selected _Annotate Payment_, a box will display for the annotation.
-
-The screen will refresh to display the updated bill information for the patron.
-If change is due, the bottom portion of the screen, _Change Due Upon Payment:_
-will briefly reflect the amount due to the patron.
-
-TIP: if you need more time to review the amount due, click outside the _Payment
-Received_ box before selecting _Apply Payment!_ This will cause the screen to
-refresh and display the amount due.
-
-[TIP]
-================================================
-* Items marked with red are still checked out. Items marked with dark red are
-lost. Items marked with orange are still checked out and long overdue.
-* It is possible for a patron to pay a bill while the item is still out and
-accruing fines.
-* When Check is selected as the payment type, it is not necessary to select
-_Annotate Payment_, as a box for the check number and a note displays
-automatically.
-* If a patron pays the entire bill for a lost item and the library has enabled
-the _Use Lost and Paid copy status_ setting in the Library Settings Editor
-(*Admin* -> *Local Administration* -> *Library Settings Editor*), the copy's
-status will automatically change from _Lost_ to _Lost and Paid_.
-================================================
-
-Patron Credits
-^^^^^^^^^^^^^^
-It is possible to convert change due to a patron credit by selecting the
-_Convert Change to Patron Credit_ checkbox and to later apply that credit to a
-bill by selecting the _Patron Credit_ payment type.
-
-By default, the payment type *Patron Credit* is enabled in the staff client.
-Within the Bills interface of a patron’s account, the Patron Credit payment
-type, the Credit Available, and the option to Convert Change to Patron Credit
-are exposed by default in the staff client.
-
-image::media/Default_Patron_Billing_Screen.jpg[Default Patron Billing Screen]
-
-The Library Setting, *Disable Patron Credit*, allows staff to disable the Patron
-Credit payment type and to hide patron credit payment actions within the billing
-interface of a patron’s account. If a library doesn't use patron credits, the
-library will want to enable this setting to prevent accidental selection of the
-checkbox that converts change to patron credit.
-
-When the Library Setting, *Disable Patron Credit*, is set to *True*,
-the patron credit payment type will be disabled.
-Patron Credit will not be an option within the payment type dropdown menu.
-The Convert Change to Patron Credit and the summary of Credit Available will be
-hidden from the patron billing interface in the staff client.
-
-image::media/Disabled_Patron_Credit_Patron_Billing_Screen.jpg[Disabled Patron Credit Patron Billing Screen]
-
-To set the Library Setting:
-
-. Click *Admin* -> *Local Administration* -> *Library Settings Editor*
-
-. Search for *Disable Patron Credit*
-
-. Click *Edit*
-
-. Set the value to *True*
-
-. Click *Update Setting*
-
-image::media/Disable_Patron_Credit_Library_Setting.jpg[Disable Patron Credit Library Setting]
-
-NOTE: After applying changes to this library setting, it is necessary to restart
-the staff client to see the changes take effect.
-
-
-Void vs. Forgive vs. Adjustment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following are guidelines for using void, forgive, and adjust when clearing
-bills off a patron record.
-
-* Use forgive when staff is waiving a portion/all of a bill. A forgive_payment
-payment type will be used to credit the bill. The history of the bill will be
-retained.
-
-* Use void when the bill should not be on the patron record and when the goal
-is to remove the entire bill. Once voided, there will be no history of the bill
-available from the staff client. If the bill was partially paid before voiding,
-a negative balance will be produced.
-
-* Use adjust to zero when the bill should not be on the patron record and when
-the goal is to remove the balance of the bill. An account_adjustment payment
-type will be used to adjust the bill's balance. The history of the bill will be
-retained and available from the Bill History interface of the staff client.
-
-
-Forgiving Bills
-^^^^^^^^^^^^^^^
-
-Choose forgive as the payment type as described in the section
-<<making_payments,Making Payments>>.
-
-Enter the amount to be forgiven. Choose _Annotate Payment_ as required by local
-policy.
-
-Apply Payment. Annotate, if prompted.
-
-The screen will refresh to display the payment.
-
-
-Voiding Bills
-^^^^^^^^^^^^^
-
-Bills under one transaction are grouped in one bill line. Bills may be voided in
-part or in whole.
-
-*To void the full billing amount:*
-
-Select the bill(s) to be voided from the list in the patron account.
-
-Right click or use the _Actions for Selected Transactions_ menu to select _Void
-All Billings_.
-
-image::media/circulation_patron_bills-10.png[circulation_patron_bills 10]
-
-Confirm the action.
-
-*To void a partial amount:*
-
-Select a billing and choose Full Details for the transaction, as described in
-the section <circ_vs_grocery,Circulation vs. Grocery Bills>>
-
-The bill details screen displays.
-
-Select the specific bill to void.
-
-Void Selected Billings and confirm the action.
-
-image::media/circulation_patron_bills-11.png[circulation_patron_bills 11]
-
-Adjusting Bills to Zero
-^^^^^^^^^^^^^^^^^^^^^^^
-
-In the Bills interface, select the bill to adjust.
-
-Right click or use the _Actions for Selected Transactions_ menu to select
-_Adjust to Zero_.
-
-image::media/adjust_to_zero_action.png[adjust_to_zero_action.png]
-
-Confirm the action.
-
-Adding New ``Grocery'' Bills
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A grocery bill can be added as a new bill or to an existing bill.
-
-*To add a as a new bill:*
-
-. Retrieve the patron record.
-. Navigate to the Bills screen.
-. Click the_Bill Patron_ button above the list of current bills.
-+
-image::media/circulation_patron_bills-12.png[circulation_patron_bills 12]
-+
-.Choose appropriate _Billing Type_ from the drop down menu. (``Grocery'' is the
-only available transaction type.) . Enter the Amount and Note (as required).
-.
-_Submit this Bill_ and confirm this action.
-
-image::media/circulation_patron_bills-13.png[circulation_patron_bills 13]
-
-*To add bill to an existing bill line:*
-
-. Retrieve the patron record.
-. Navigate to the Bills screen.
-. Highlight the desired bill.
-. Use the _Actions for Selected Transactions_ to select _Add Billing_.
-Confirm this action.
-. Follow steps 4 through 6 above. There is no confirmation message
-after clicking _Submit this Bill_.
-. The _Money Summary_ will adjust accordingly.
-
-Negative Balances on Patron Accounts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If a library has not enabled Prohibit Negative Balance settings via the library
-settings editor, certain workflows and settings can create a negative balance on
-a patron's account. See...for information on settings that affect negative
-balances.
-
-[[removing_negative_balances]]
-
-*Removing negative balances from a patron account*
-
-A negative balance can be cleared either by refunding a bill or by adjusting the
-bill to zero.
-
-To refund the bill:
-
-1) Select the billing with the negative balance.
-
-2) Choose **Actions for Selected Transactions** --> **Refund**.
-
-3) Click Yes.
-
-4) Click Apply Payment.
-
-The refunded amount will be deducted from the cash_payment total in the
-workstations Cash Report.
-
-To clear the negative balance without affecting the Cash Report:
-
-1) Right click on the billing with the negative balance.
-
-2) Select **Adjust to zero**.
-
-3) Click Yes.
-
-
-Bill History
-^^^^^^^^^^^^
-
-*To view a patron’s bill history:*
-
-. Retrieve the patron record.
-. From the _Bills_ screen, click _History_.
-. A _Bill History_ screen with two tabs will display. One for _Transactions_
-and one for _Payments_.
-+
-image::media/circulation_patron_bills-14.png[circulation_patron_bills 14]
-+
-. For more information about a specific billing, select the bill and click _Full
-Details_. A screen detailing item information, billings, and payments will
-display.
-
-image::media/circulation_patron_bills-15.png[circulation_patron_bills 15]
-
-Items may be deleted from the catalog even if a charge for that item is still
-attached to the patron's record. The charge will remain on the patron's account
-after the deletion.
-
--- /dev/null
+Circulation - Patron Record
+---------------------------
+
+[[searching_patrons]]
+Searching Patrons
+~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, searching for]
+
+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
+
+image::media/circulation_patron_records-1a_web_client.png[circulation_patron_records 1a]
+
+
+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.
+
+
+image::media/circulation_patron_records-1b_web_client.png[circulation_patron_records 1b]
+
+.Tips for searching
+[TIP]
+===================
+* Search one field or combine fields for more precise results.
+* Truncate search terms for more search results.
+===================
+
+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.
+
+image::media/circulation_patron_records-2_web_client.png[circulation_patron_records 2]
+
+The _Patron Search_ button on the upper right may be used to resume searching for patrons.
+
+Registering New Patrons
+~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, registering]
+
+To register a new patron, select _Circulation -> Register Patron_ from the menu bar. The Patron
+Registration form will display.
+
+image::media/circulation_patron_records-4.png[Patron registration form]
+
+Mandatory fields display in yellow.
+
+image::media/circulation_patron_records-5.png[circulation_patron_records 5]
+
+The _Show Only Required Fields_ and _Show Suggested Fields_ may be used to limit
+the options on this page.
+
+image::media/circulation_patron_records-6.png[circulation_patron_records 6]
+
+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_.
+
+image::media/circulation_patron_records-7.png[circulation_patron_records 7]
+
+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.
+
+image::media/circulation_patron_records-8.png[circulation_patron_records 8]
+
+[TIP]
+============================================================================
+* 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.
+============================================================================
+
+
+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.”
+
+image::media/patron_self_registration2.jpg[Patron Self-Registration form]
+
+*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.
+
+
+[[updating_patron_information]]
+Updating Patron Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, updating]
+
+Retrieve the patron record as described in the section
+<<searching_patrons,Searching Patrons>>.
+
+Click on _Edit_ from the options that display at the top of the patron record.
+
+image::media/circulation_patron_records-9_web_client.png[Patron edit with summary display]
+
+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.
+
+[TIP]
+=======
+* 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.
+=======
+
+
+Renewing Library Cards
+~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[library cards, renewing]
+
+Expired patron accounts when initially retrieved – an alert
+stating that the ``Patron account is EXPIRED.''
+
+image::media/circulation_patron_records-11_web_client.png[circulation_patron_records 11]
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,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.
+
+image::media/circulation_patron_records-12.png[circulation_patron_records 12]
+
+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.
+
+
+Lost Library Cards
+~~~~~~~~~~~~~~~~~~
+
+indexterm:[library cards, replacing]
+
+Retrieve the patron record as described in the section
+<<searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Next to the _Barcode_ field, select the _Replace Barcode_ button.
+
+image::media/circulation_patron_records-13.png[circulation_patron_records 13]
+
+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,Searching Patrons>>. Open the patron record in
+edit mode as described in the section <<updating_patron_information,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.
+
+image::media/circulation_patron_records-14.png[circulation_patron_records 14]
+
+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.
+
+Resetting Patron's Password
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, passwords]
+
+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,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Select the _Reset Password_ button next to the _Password_ field.
+
+image::media/circulation_patron_records-15.png[circulation_patron_records 15]
+
+NOTE: 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.
+
+
+[TIP]
+=======================
+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:
+
+[source, sql]
+------------------------------------------------------------------------------
+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.
+
+[source, sql]
+------------------------------------------------------------------------------
+UPDATE actor.usr SET passwd = <password> WHERE id=<id of row to be updated>;
+------------------------------------------------------------------------------
+
+The new password will automatically be hashed.
+
+=======================
+
+
+Barring a Patron
+~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, barring]
+
+A patron may be barred from circulation activities. To bar a patron, retrieve
+the patron record as described in the section
+<<searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Check the box for _Barred_ in the patron account.
+
+image::media/circulation_patron_records-16.png[circulation_patron_records 16]
+
+_Save_ the user. The screen will refresh.
+
+NOTE: Barring a patron from one library bars that patron from all consortium
+member libraries.
+
+To unbar a patron, uncheck the Barred checkbox.
+
+
+Barred vs. Blocked
+~~~~~~~~~~~~~~~~~~
+
+indexterm:[patrons, barring]
+
+*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.
+
+indexterm:[patrons, blocking]
+
+*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.
+
+
+Staff-Generated Messages
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[staff_generated_messages]]
+indexterm:[patrons, 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 <<circulation_patron_notes,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 <<circulation_patron_alerts,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_web_client,Staff-Generated Penalties/Messages>> for more.)
+
+Patron Alerts
+~~~~~~~~~~~~~~
+
+[[circulation_patron_alerts]]
+indexterm:[patrons, Alerts]
+
+When an account has an alert on it, a Stop sign is displayed when the record is
+retrieved.
+
+image::media/circulation_patron_records-18_web_client.png[circulation_patron_records 18]
+
+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_.
+
+image::media/circulation_patron_records-19_web_client.png[circulation_patron_records 19]
+
+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,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Enter the alert text in the Alert Message field.
+
+image::media/circulation_patron_records-20.png[circulation_patron_records 20]
+
+_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,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,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.
+
+Patron Notes
+~~~~~~~~~~~~
+
+[[circulation_patron_notes]]
+indexterm:[patrons, 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.
+
+image::media/circulation_patron_records-23_web_client.png[circulation_patron_records 23]
+
+To insert or remove a note, retrieve the patron record as described in the
+section <<searching_patrons,Searching Patrons>>.
+
+Open the patron record in edit mode as described in the section
+<<updating_patron_information,Updating Patron Information>>.
+
+Use the Other menu to navigate to _Notes_.
+
+image::media/circulation_patron_records-24_web_client.png[circulation_patron_records 24]
+
+Select the _Add New Note_ button. A _Create a new note_ window displays.
+
+[TIP]
+================================================
+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,Library Settings Editor>> section.
+================================================
+
+Enter note information.
+
+Select the check box for _Patron Visible_ to display the note in the OPAC.
+
+image::media/circulation_patron_records-25_web_client.png[circulation_patron_records 25]
+
+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.
+
+image::media/circulation_patron_records-26_web_client.png[circulation_patron_records 26]
+
+Staff-Generated Penalties/Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[staff_generated_penalties_web_client]]
+To access this feature, use the _Messages_ button in the patron record.
+
+image::media/staff-penalties-1_web_client.png[Messages screen]
+
+Add a Message
+^^^^^^^^^^^^^
+
+Click *Apply Penalty/Message* to begin the process of adding a message to the patron.
+
+image::media/staff-penalties-2_web_client.png[Apply Penalty Dialog Box]
+
+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 <<circulation_patron_notes,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.
+
+image::media/staff-penalties-3_web_client.png[[Messages on a record]
+
+Modify a Message
+^^^^^^^^^^^^^^^^
+
+Messages can be edited by staff after they are created.
+
+image::media/staff-penalties-4_web_client.png[[Actions menu]
+
+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.
+
+image::media/staff-penalties-5_web_client.png[Modify penalty dialog box]
+
+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.
+
+image::media/staff-penalties-6_web_client.png[Modified message in the list]
+
+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.
+
+image::media/staff-penalties-4_web_client.png[[Actions menu]
+
+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.
+
+image::media/staff-penalties-7_web_client.png[Archived messages]
+
+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*.
+
+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.
+
+image::media/staff-penalties-4_web_client.png[[Actions menu]
+
+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.
+
+
+++ /dev/null
-Circulation - Patron Record
----------------------------
-
-[[searching_patrons]]
-Searching Patrons
-~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, searching for]
-
-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
-
-image::media/circulation_patron_records-1a_web_client.png[circulation_patron_records 1a]
-
-
-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.
-
-
-image::media/circulation_patron_records-1b_web_client.png[circulation_patron_records 1b]
-
-.Tips for searching
-[TIP]
-===================
-* Search one field or combine fields for more precise results.
-* Truncate search terms for more search results.
-===================
-
-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.
-
-image::media/circulation_patron_records-2_web_client.png[circulation_patron_records 2]
-
-The _Patron Search_ button on the upper right may be used to resume searching for patrons.
-
-Registering New Patrons
-~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, registering]
-
-To register a new patron, select _Circulation -> Register Patron_ from the menu bar. The Patron
-Registration form will display.
-
-image::media/circulation_patron_records-4.png[Patron registration form]
-
-Mandatory fields display in yellow.
-
-image::media/circulation_patron_records-5.png[circulation_patron_records 5]
-
-The _Show Only Required Fields_ and _Show Suggested Fields_ may be used to limit
-the options on this page.
-
-image::media/circulation_patron_records-6.png[circulation_patron_records 6]
-
-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_.
-
-image::media/circulation_patron_records-7.png[circulation_patron_records 7]
-
-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.
-
-image::media/circulation_patron_records-8.png[circulation_patron_records 8]
-
-[TIP]
-============================================================================
-* 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.
-============================================================================
-
-
-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.”
-
-image::media/patron_self_registration2.jpg[Patron Self-Registration form]
-
-*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.
-
-
-[[updating_patron_information]]
-Updating Patron Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, updating]
-
-Retrieve the patron record as described in the section
-<<searching_patrons,Searching Patrons>>.
-
-Click on _Edit_ from the options that display at the top of the patron record.
-
-image::media/circulation_patron_records-9_web_client.png[Patron edit with summary display]
-
-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.
-
-[TIP]
-=======
-* 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.
-=======
-
-
-Renewing Library Cards
-~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[library cards, renewing]
-
-Expired patron accounts when initially retrieved – an alert
-stating that the ``Patron account is EXPIRED.''
-
-image::media/circulation_patron_records-11_web_client.png[circulation_patron_records 11]
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,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.
-
-image::media/circulation_patron_records-12.png[circulation_patron_records 12]
-
-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.
-
-
-Lost Library Cards
-~~~~~~~~~~~~~~~~~~
-
-indexterm:[library cards, replacing]
-
-Retrieve the patron record as described in the section
-<<searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Next to the _Barcode_ field, select the _Replace Barcode_ button.
-
-image::media/circulation_patron_records-13.png[circulation_patron_records 13]
-
-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,Searching Patrons>>. Open the patron record in
-edit mode as described in the section <<updating_patron_information,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.
-
-image::media/circulation_patron_records-14.png[circulation_patron_records 14]
-
-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.
-
-Resetting Patron's Password
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, passwords]
-
-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,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Select the _Reset Password_ button next to the _Password_ field.
-
-image::media/circulation_patron_records-15.png[circulation_patron_records 15]
-
-NOTE: 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.
-
-
-[TIP]
-=======================
-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:
-
-[source, sql]
-------------------------------------------------------------------------------
-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.
-
-[source, sql]
-------------------------------------------------------------------------------
-UPDATE actor.usr SET passwd = <password> WHERE id=<id of row to be updated>;
-------------------------------------------------------------------------------
-
-The new password will automatically be hashed.
-
-=======================
-
-
-Barring a Patron
-~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, barring]
-
-A patron may be barred from circulation activities. To bar a patron, retrieve
-the patron record as described in the section
-<<searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Check the box for _Barred_ in the patron account.
-
-image::media/circulation_patron_records-16.png[circulation_patron_records 16]
-
-_Save_ the user. The screen will refresh.
-
-NOTE: Barring a patron from one library bars that patron from all consortium
-member libraries.
-
-To unbar a patron, uncheck the Barred checkbox.
-
-
-Barred vs. Blocked
-~~~~~~~~~~~~~~~~~~
-
-indexterm:[patrons, barring]
-
-*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.
-
-indexterm:[patrons, blocking]
-
-*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.
-
-
-Staff-Generated Messages
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-[[staff_generated_messages]]
-indexterm:[patrons, 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 <<circulation_patron_notes,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 <<circulation_patron_alerts,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_web_client,Staff-Generated Penalties/Messages>> for more.)
-
-Patron Alerts
-~~~~~~~~~~~~~~
-
-[[circulation_patron_alerts]]
-indexterm:[patrons, Alerts]
-
-When an account has an alert on it, a Stop sign is displayed when the record is
-retrieved.
-
-image::media/circulation_patron_records-18_web_client.png[circulation_patron_records 18]
-
-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_.
-
-image::media/circulation_patron_records-19_web_client.png[circulation_patron_records 19]
-
-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,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Enter the alert text in the Alert Message field.
-
-image::media/circulation_patron_records-20.png[circulation_patron_records 20]
-
-_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,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,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.
-
-Patron Notes
-~~~~~~~~~~~~
-
-[[circulation_patron_notes]]
-indexterm:[patrons, 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.
-
-image::media/circulation_patron_records-23_web_client.png[circulation_patron_records 23]
-
-To insert or remove a note, retrieve the patron record as described in the
-section <<searching_patrons,Searching Patrons>>.
-
-Open the patron record in edit mode as described in the section
-<<updating_patron_information,Updating Patron Information>>.
-
-Use the Other menu to navigate to _Notes_.
-
-image::media/circulation_patron_records-24_web_client.png[circulation_patron_records 24]
-
-Select the _Add New Note_ button. A _Create a new note_ window displays.
-
-[TIP]
-================================================
-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,Library Settings Editor>> section.
-================================================
-
-Enter note information.
-
-Select the check box for _Patron Visible_ to display the note in the OPAC.
-
-image::media/circulation_patron_records-25_web_client.png[circulation_patron_records 25]
-
-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.
-
-image::media/circulation_patron_records-26_web_client.png[circulation_patron_records 26]
-
-Staff-Generated Penalties/Messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-[[staff_generated_penalties_web_client]]
-To access this feature, use the _Messages_ button in the patron record.
-
-image::media/staff-penalties-1_web_client.png[Messages screen]
-
-Add a Message
-^^^^^^^^^^^^^
-
-Click *Apply Penalty/Message* to begin the process of adding a message to the patron.
-
-image::media/staff-penalties-2_web_client.png[Apply Penalty Dialog Box]
-
-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 <<circulation_patron_notes,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.
-
-image::media/staff-penalties-3_web_client.png[[Messages on a record]
-
-Modify a Message
-^^^^^^^^^^^^^^^^
-
-Messages can be edited by staff after they are created.
-
-image::media/staff-penalties-4_web_client.png[[Actions menu]
-
-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.
-
-image::media/staff-penalties-5_web_client.png[Modify penalty dialog box]
-
-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.
-
-image::media/staff-penalties-6_web_client.png[Modified message in the list]
-
-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.
-
-image::media/staff-penalties-4_web_client.png[[Actions menu]
-
-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.
-
-image::media/staff-penalties-7_web_client.png[Archived messages]
-
-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*.
-
-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.
-
-image::media/staff-penalties-4_web_client.png[[Actions menu]
-
-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.
-
-
--- /dev/null
+
+Holds Management
+----------------
+
+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_.
+
+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)
+|===============================
+
+
+Title Level Hold
+~~~~~~~~~~~~~~~~
+
+[TIP]
+====================
+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.
++
+image::media/holds_title_searchresults.png[Search Results with Place Hold link]
++
+. 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_.
++
+image::media/holds_title_options.png[Place Holds screen with Basic Options]
++
+. A confirmation screen appears with the message "Hold was successfully placed".
++
+image::media/holds_title_success.png[Place Holds confirmation screen]
+
+*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.
+
+image::media/holds_title_options_adv.png[Place Hold screen with Advanced Options]
+
+See also the section on placing <<_tpac_metarecord_search_and_metarecord_level_holds,
+Metarecord Holds>>.
+
+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_.
++
+image::media/holds_title_options.png[Place Holds screen with Basic Options]
++
+[TIP]
+===============
+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.
+===============
+
+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.
+
+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.
+
+image::media/place-another-hold-1.png[place-another-hold-1]
+
+This feature can be useful for book groups or new items where a list of waiting patrons needs to be transferred into the system.
+
+
+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.
+
+[TIP]
+==============
+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.
+==============
+
+
+Actions for Selected Holds
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+. Retrieve the patron record and go to the _Holds_ screen.
+. Highlight the hold record, then select _Actions for Selected Holds_.
++
+image::media/holds-managing-1.png[holds-managing-1]
++
+. 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_.
++
+image::media/holds-managing-2.png[holds-managing-2]
++
+[NOTE]
+=============
+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.
++
+[NOTE]
+===============
+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.
++
+image::media/holds-managing-4.png[holds-managing-4]
++
+
+.. 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.
++
+image::media/holds-managing-5.png[holds-managing-5]
++
+
+.. 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.
++
+image::media/holds-managing-6.png[holds-managing-6]
++
+
+.. 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_.
++
+image::media/holds-managing-7.png[holds-managing-7]
++
+[NOTE]
+==============
+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.
++
+image::media/holds-managing-8.png[holds-managing-8]
+
+
+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_.
++
+image::media/holds-managing-9.png[holds-managing-9]
++
+. Select the hold you want to transfer. Click _Actions for Selected Holds_ -> _Transfer to Marked Title_.
++
+image::media/holds-managing-10.png[holds-managing-10]
+
+Cancelled Holds
+^^^^^^^^^^^^^^^
+
+. Cancelled holds can be displayed. Click the _Show Cancelled Holds_ button on the _Holds_ screen.
++
+image::media/holds-managing-11.png[holds-managing-11]
++
+. You can un-cancel holds.
++
+image::media/holds-managing-12.png[holds-managing-12]
++
+Based on your library’s setting, hold request time can be reset when a hold is un-cancelled.
+
+
+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.
++
+image::media/holds-managing-13.png[holds-managing-13]
++
+. You may add a note to a hold in the _Detail View_.
++
+image::media/holds-managing-14.png[holds-managing-14]
++
+. Notes can be printed on the hold slip if the _Print on slip?_ checkbox is selected. Key in the message then click _Add Note_.
++
+image::media/holds-managing-15.png[holds-managing-15]
+
+
+Displaying Queue Position
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using the Column Picker, you can display _Queue Position_ and _Total number of Holds_.
+
+image::media/holds-managing-16.png[holds-managing-16]
+
+
+Managing Holds in Title Records
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+. Retrieve and display the title record in the catalog.
+. Click _Actions for this Record_ -> _View Holds_.
++
+image::media/holds-managing-17.png[holds-managing-17]
++
+. 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.
++
+image::media/holds-managing-18.png[holds-managing-18]
++
+. 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,Actions for Selected Holds>> section.
++
+image::media/holds-managing-19.png[holds-managing-19]
++
+. You can retrieve the hold requestor’s account by selecting _Retrieve Patron_ on the above dropdown menu.
+
+
+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.
+
+
+Pulling & Capturing Holds
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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_.
++
+image::media/holds-pull-1.png[holds-pull-1]
++
+. 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.
++
+image::media/holds-pull-2.png[holds-pull-2]
++
+[NOTE]
+===========
+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.
++
+image::media/holds-pull-3.png[holds-pull-3]
++
+. 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.
++
+image::media/holds-pull-4.png[holds-pull-4]
++
+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.
+
+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_.
++
+image::media/holds-pull-5.png[holds-pull-5]
++
+image::media/holds-pull-5a.png[holds-pull-5a]
++
+. Scan or type barcode and click _Submit_.
++
+image::media/holds-pull-6.png[holds-pull-6]
++
+. 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.)
++
+image::media/holds-pull-7.png[holds-pull-7]
++
+. 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.)
++
+image::media/holds-pull-8.png[holds-pull-8]
++
+[TIP]
+===============
+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.
+===============
+
+
+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_.
++
+image::media/holds-pull-9.png[holds-pull-9]
++
+. Evergreen will update the status of the item and will immediately retarget the hold.
+
+
+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.
++
+image::media/holds-notifications-1.png[holds-notifications-1]
++
+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.
++
+image::media/holds-notifications-2.png[holds-notifications-2]
++
+. 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.
++
+image::media/holds-notifications-3.png[holds-notifications-3]
++
+
+. 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.
+
+[NOTE]
+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.
+
+
+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_.
++
+image::media/holds-clearing-1.png[holds-clearing-1]
++
+. 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.
++
+image::media/holds-clearing-2.png[holds-clearing-2]
++
+. 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_.
++
+image::media/holds-clearing-3.png[holds-clearing-3]
++
+. 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.
++
+image::media/holds-clearing-4.png[holds-clearing-4]
++
+. Bring items down from the hold shelf and check them in.
+
+[IMPORTANT]
+=============
+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_.
+
+[NOTE]
+===========
+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.
+===========
+
+
+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.
+
+image::media/custom_hold_pickup_location1.jpg[Custom Hold Pickup Location]
+
+
+If configured, patrons will see the option to opt-in to the alternate location in the _Account Preferences_ section of their OPAC Account.
+
+image::media/custom_hold_pickup_location2.jpg[OPAC Account]
+
+
+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.
+
+image::media/Display_Hold_Types_on_Pull_Lists1.jpg[Display_Hold_Types_on_Pull_Lists1]
+++ /dev/null
-
-Holds Management
-----------------
-
-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_.
-
-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)
-|===============================
-
-
-Title Level Hold
-~~~~~~~~~~~~~~~~
-
-[TIP]
-====================
-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.
-+
-image::media/holds_title_searchresults.png[Search Results with Place Hold link]
-+
-. 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_.
-+
-image::media/holds_title_options.png[Place Holds screen with Basic Options]
-+
-. A confirmation screen appears with the message "Hold was successfully placed".
-+
-image::media/holds_title_success.png[Place Holds confirmation screen]
-
-*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.
-
-image::media/holds_title_options_adv.png[Place Hold screen with Advanced Options]
-
-See also the section on placing <<_tpac_metarecord_search_and_metarecord_level_holds,
-Metarecord Holds>>.
-
-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_.
-+
-image::media/holds_title_options.png[Place Holds screen with Basic Options]
-+
-[TIP]
-===============
-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.
-===============
-
-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.
-
-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.
-
-image::media/place-another-hold-1.png[place-another-hold-1]
-
-This feature can be useful for book groups or new items where a list of waiting patrons needs to be transferred into the system.
-
-
-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.
-
-[TIP]
-==============
-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.
-==============
-
-
-Actions for Selected Holds
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-. Retrieve the patron record and go to the _Holds_ screen.
-. Highlight the hold record, then select _Actions for Selected Holds_.
-+
-image::media/holds-managing-1.png[holds-managing-1]
-+
-. 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_.
-+
-image::media/holds-managing-2.png[holds-managing-2]
-+
-[NOTE]
-=============
-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.
-+
-[NOTE]
-===============
-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.
-+
-image::media/holds-managing-4.png[holds-managing-4]
-+
-
-.. 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.
-+
-image::media/holds-managing-5.png[holds-managing-5]
-+
-
-.. 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.
-+
-image::media/holds-managing-6.png[holds-managing-6]
-+
-
-.. 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_.
-+
-image::media/holds-managing-7.png[holds-managing-7]
-+
-[NOTE]
-==============
-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.
-+
-image::media/holds-managing-8.png[holds-managing-8]
-
-
-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_.
-+
-image::media/holds-managing-9.png[holds-managing-9]
-+
-. Select the hold you want to transfer. Click _Actions for Selected Holds_ -> _Transfer to Marked Title_.
-+
-image::media/holds-managing-10.png[holds-managing-10]
-
-Cancelled Holds
-^^^^^^^^^^^^^^^
-
-. Cancelled holds can be displayed. Click the _Show Cancelled Holds_ button on the _Holds_ screen.
-+
-image::media/holds-managing-11.png[holds-managing-11]
-+
-. You can un-cancel holds.
-+
-image::media/holds-managing-12.png[holds-managing-12]
-+
-Based on your library’s setting, hold request time can be reset when a hold is un-cancelled.
-
-
-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.
-+
-image::media/holds-managing-13.png[holds-managing-13]
-+
-. You may add a note to a hold in the _Detail View_.
-+
-image::media/holds-managing-14.png[holds-managing-14]
-+
-. Notes can be printed on the hold slip if the _Print on slip?_ checkbox is selected. Key in the message then click _Add Note_.
-+
-image::media/holds-managing-15.png[holds-managing-15]
-
-
-Displaying Queue Position
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Using the Column Picker, you can display _Queue Position_ and _Total number of Holds_.
-
-image::media/holds-managing-16.png[holds-managing-16]
-
-
-Managing Holds in Title Records
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-. Retrieve and display the title record in the catalog.
-. Click _Actions for this Record_ -> _View Holds_.
-+
-image::media/holds-managing-17.png[holds-managing-17]
-+
-. 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.
-+
-image::media/holds-managing-18.png[holds-managing-18]
-+
-. 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,Actions for Selected Holds>> section.
-+
-image::media/holds-managing-19.png[holds-managing-19]
-+
-. You can retrieve the hold requestor’s account by selecting _Retrieve Patron_ on the above dropdown menu.
-
-
-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.
-
-
-Pulling & Capturing Holds
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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_.
-+
-image::media/holds-pull-1.png[holds-pull-1]
-+
-. 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.
-+
-image::media/holds-pull-2.png[holds-pull-2]
-+
-[NOTE]
-===========
-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.
-+
-image::media/holds-pull-3.png[holds-pull-3]
-+
-. 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.
-+
-image::media/holds-pull-4.png[holds-pull-4]
-+
-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.
-
-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_.
-+
-image::media/holds-pull-5.png[holds-pull-5]
-+
-image::media/holds-pull-5a.png[holds-pull-5a]
-+
-. Scan or type barcode and click _Submit_.
-+
-image::media/holds-pull-6.png[holds-pull-6]
-+
-. 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.)
-+
-image::media/holds-pull-7.png[holds-pull-7]
-+
-. 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.)
-+
-image::media/holds-pull-8.png[holds-pull-8]
-+
-[TIP]
-===============
-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.
-===============
-
-
-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_.
-+
-image::media/holds-pull-9.png[holds-pull-9]
-+
-. Evergreen will update the status of the item and will immediately retarget the hold.
-
-
-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.
-+
-image::media/holds-notifications-1.png[holds-notifications-1]
-+
-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.
-+
-image::media/holds-notifications-2.png[holds-notifications-2]
-+
-. 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.
-+
-image::media/holds-notifications-3.png[holds-notifications-3]
-+
-
-. 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.
-
-[NOTE]
-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.
-
-
-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_.
-+
-image::media/holds-clearing-1.png[holds-clearing-1]
-+
-. 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.
-+
-image::media/holds-clearing-2.png[holds-clearing-2]
-+
-. 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_.
-+
-image::media/holds-clearing-3.png[holds-clearing-3]
-+
-. 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.
-+
-image::media/holds-clearing-4.png[holds-clearing-4]
-+
-. Bring items down from the hold shelf and check them in.
-
-[IMPORTANT]
-=============
-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_.
-
-[NOTE]
-===========
-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.
-===========
-
-
-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.
-
-image::media/custom_hold_pickup_location1.jpg[Custom Hold Pickup Location]
-
-
-If configured, patrons will see the option to opt-in to the alternate location in the _Account Preferences_ section of their OPAC Account.
-
-image::media/custom_hold_pickup_location2.jpg[OPAC Account]
-
-
-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.
-
-image::media/Display_Hold_Types_on_Pull_Lists1.jpg[Display_Hold_Types_on_Pull_Lists1]
--- /dev/null
+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.
+
+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.
+
+Checking Out Items
+------------------
+anchor:standalone_check_out[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.
+
+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.
++
+NOTE: 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*.
+
+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*.
+
+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*.
+
+NOTE: Without access to Evergreen database, items on holds or with special
+status will not be captured in offline mode.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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).
+++ /dev/null
-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.
-
-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.
-
-Checking Out Items
-------------------
-anchor:standalone_check_out[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.
-
-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.
-+
-NOTE: 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*.
-
-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*.
-
-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*.
-
-NOTE: Without access to Evergreen database, items on holds or with special
-status will not be captured in offline mode.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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).
--- /dev/null
+RFID Product Integration
+========================
+
+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.
+
+NOTE: 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.
+
+NOTE: 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.
+
+NOTE: 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.
+
+++ /dev/null
-RFID Product Integration
-========================
-
-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.
-
-NOTE: 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.
-
-NOTE: 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.
-
-NOTE: 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.
-
--- /dev/null
+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.
+
+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.
+
+image::media/self-check-admin-login.png[Self Check Admin Login]
+
+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.
+
+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):
++
+[source, bash]
+------------------------------------------------------------------------------
+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.
+
+Basic Check Out
+---------------
+
+. Patron scans their barcode.
++
+image::media/self_check_check_out_1.png[self check]
++
+. _Optional_ Patron enters their account password.
++
+image::media/self_check_check_out_2.png[self check]
++
+. Patron scans the barcodes for their items
+_OR_
+Patron places items, one at a time, on the RFID pad.
++
+image::media/self_check_check_out_3.png[self check]
++
+. Items will be listed below with a check out confirmation message.
++
+image::media/self_check_check_out_4.png[self check]
++
+. If a check out fails a message will advise patrons.
++
+image::media/self_check_error_1.png[self check]
++
+. Patron clicks *Logout* to print a checkout receipt and logout.
+_OR_
+Patron clicks *Logout (No Receipt)* to logout with no receipt.
++
+image::media/self_check_check_out_5.png[self check]
++
+[NOTE]
+==========
+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.
+
+image::media/self_check_check_out_6.png[self check]
+==========
+
+View Items Out
+--------------
+
+. Patrons are able to view the items they currently have checked out by clicking *View Items Out*
++
+image::media/self_check_view_items_out_1.png[self check]
++
+. 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.
+
+image::media/self_check_view_items_out_2.png[self check]
+
+
+View Holds
+----------
+
+. Patrons are able to view their current holds by clicking *View Holds*
++
+image::media/self_check_view_holds_1.png[self check]
++
+. 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.
++
+image::media/self_check_view_holds_2.png[self check]
+
+View Fines
+----------
+
+. Patrons are able to view the fines they currently owe by clicking *View Details*
++
+image::media/self_check_view_fines_1.png[self check]
++
+. Current fines owed by the patron display.
+
+image::media/self_check_view_fines_2.png[self check]
+++ /dev/null
-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.
-
-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.
-
-image::media/self-check-admin-login.png[Self Check Admin Login]
-
-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.
-
-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):
-+
-[source, bash]
-------------------------------------------------------------------------------
-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.
-
-Basic Check Out
----------------
-
-. Patron scans their barcode.
-+
-image::media/self_check_check_out_1.png[self check]
-+
-. _Optional_ Patron enters their account password.
-+
-image::media/self_check_check_out_2.png[self check]
-+
-. Patron scans the barcodes for their items
-_OR_
-Patron places items, one at a time, on the RFID pad.
-+
-image::media/self_check_check_out_3.png[self check]
-+
-. Items will be listed below with a check out confirmation message.
-+
-image::media/self_check_check_out_4.png[self check]
-+
-. If a check out fails a message will advise patrons.
-+
-image::media/self_check_error_1.png[self check]
-+
-. Patron clicks *Logout* to print a checkout receipt and logout.
-_OR_
-Patron clicks *Logout (No Receipt)* to logout with no receipt.
-+
-image::media/self_check_check_out_5.png[self check]
-+
-[NOTE]
-==========
-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.
-
-image::media/self_check_check_out_6.png[self check]
-==========
-
-View Items Out
---------------
-
-. Patrons are able to view the items they currently have checked out by clicking *View Items Out*
-+
-image::media/self_check_view_items_out_1.png[self check]
-+
-. 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.
-
-image::media/self_check_view_items_out_2.png[self check]
-
-
-View Holds
-----------
-
-. Patrons are able to view their current holds by clicking *View Holds*
-+
-image::media/self_check_view_holds_1.png[self check]
-+
-. 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.
-+
-image::media/self_check_view_holds_2.png[self check]
-
-View Fines
-----------
-
-. Patrons are able to view the fines they currently owe by clicking *View Details*
-+
-image::media/self_check_view_fines_1.png[self check]
-+
-. Current fines owed by the patron display.
-
-image::media/self_check_view_fines_2.png[self check]
--- /dev/null
+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.
+
+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.
+
+image::media/Triggered_Events_and_Notices1.jpg[Triggered_Events_and_Notices1]
+
+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.
+
+image::media/Triggered_Events_and_Notices2.jpg[Triggered_Events_and_Notices2]
+
+Sort
+~~~~
+
+You can sort your results by clicking the column name.
+
+image::media/Triggered_Events_and_Notices3.jpg[Triggered_Events_and_Notices3]
+
+
+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*.
+
+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*.
+
+++ /dev/null
-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.
-
-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.
-
-image::media/Triggered_Events_and_Notices1.jpg[Triggered_Events_and_Notices1]
-
-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.
-
-image::media/Triggered_Events_and_Notices2.jpg[Triggered_Events_and_Notices2]
-
-Sort
-~~~~
-
-You can sort your results by clicking the column name.
-
-image::media/Triggered_Events_and_Notices3.jpg[Triggered_Events_and_Notices3]
-
-
-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*.
-
-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*.
-
--- /dev/null
+Using Supercat
+==============
+
+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.
+
+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:
+
+[source,xml]
+----------------------------------------------------------------------------
+<?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>
+----------------------------------------------------------------------------
+
+Records
+-------
+
+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.
+
+[source,xml]
+----------------------------------------------------------------------------
+<?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>
+----------------------------------------------------------------------------
+
+[NOTE]
+============================================================================
+atom-full is currently the only format that includes holdings and availability
+data for a given bibliographic record.
+============================================================================
+
+
+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.
+
+[source,xml]
+----------------------------------------------------------------------------
+<?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>
+----------------------------------------------------------------------------
+
+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
+
+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
+
+
+++ /dev/null
-Using Supercat
-==============
-
-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.
-
-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:
-
-[source,xml]
-----------------------------------------------------------------------------
-<?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>
-----------------------------------------------------------------------------
-
-Records
--------
-
-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.
-
-[source,xml]
-----------------------------------------------------------------------------
-<?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>
-----------------------------------------------------------------------------
-
-[NOTE]
-============================================================================
-atom-full is currently the only format that includes holdings and availability
-data for a given bibliographic record.
-============================================================================
-
-
-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.
-
-[source,xml]
-----------------------------------------------------------------------------
-<?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>
-----------------------------------------------------------------------------
-
-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
-
-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
-
-
--- /dev/null
+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.
+
+
+++ /dev/null
-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.
-
-
--- /dev/null
+= Easing gently into OpenSRF =
+
+== Abstract ==
+The Evergreen open-source library system serves library consortia composed of
+hundreds of branches with millions of patrons - for example,
+http://www.georgialibraries.org/statelibrarian/bythenumbers.pdf[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.
+
+== 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 http://evergreen-ils.org/blog/?p=56[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.
+
+=== 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:
+
+ * http://tools.ietf.org/html/rfc3920[Extensible Messaging and Presence
+Protocol] (XMPP, sometimes referred to as Jabber) - provides the base messaging
+infrastructure between OpenSRF clients and servers
+ * http://json.org[JavaScript Object Notation] (JSON) - serializes the content
+of each XMPP message in a standardized and concise format
+ * http://memcached.org[memcached] - provides the caching service
+ * http://tools.ietf.org/html/rfc5424[syslog] - the standard UNIX logging
+service
+
+Unfortunately, the
+http://evergreen-ils.org/dokuwiki/doku.php?id=osrf-devel:primer[OpenSRF
+reference documentation], although augmented by the
+http://evergreen-ils.org/dokuwiki/doku.php?id=osrf-devel:primer[OpenSRF
+glossary], blog posts like http://evergreen-ils.org/blog/?p=36[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.
+
+=== OpenSRF communication flows over XMPP ===
+
+The XMPP messaging service underpins OpenSRF, requiring an XMPP server such
+as http://www.ejabberd.im/[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`.
+
+[id="OpenSRFOverHTTP"]
+=== 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
+http://www.open-ils.org/dokuwiki/doku.php?id=opensrf_over_http[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
+[source,bash]
+--------------------------------------------------------------------------------
+# curl request broken up over multiple lines for legibility
+curl -H "X-OpenSRF-service: opensrf.simple-text" \ # <1>
+ --data 'osrf-msg=[ \ # <2>
+ {"__c":"osrfMessage","__p":{"threadTrace":0,"locale":"en-CA", \ # <3>
+ "type":"REQUEST","payload": {"__c":"osrfMethod","__p": \
+ {"method":"opensrf.simple-text.reverse","params":["foobar"]} \
+ }} \
+ }]' \
+http://localhost/osrf-http-translator \ # <4>
+--------------------------------------------------------------------------------
+
+<1> The `X-OpenSRF-service` header identifies the OpenSRF service of interest.
+
+<2> The POST request consists of a single parameter, the `osrf-msg` value,
+which contains a JSON array.
+
+<3> 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"`
+
+<4> 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.
+
+[id="httpResults"]
+.Results from an HTTP POST request to an OpenSRF method via the OpenSRF HTTP Translator
+[source,bash]
+--------------------------------------------------------------------------------
+# HTTP response broken up over multiple lines for legibility
+[{"__c":"osrfMessage","__p": \ # <1>
+ {"threadTrace":0, "payload": \ # <2>
+ {"__c":"osrfResult","__p": \ # <3>
+ {"status":"OK","content":"raboof","statusCode":200} \ # <4>
+ },"type":"RESULT","locale":"en-CA" \ # <5>
+ }
+},
+{"__c":"osrfMessage","__p": \ # <6>
+ {"threadTrace":0,"payload": \ # <7>
+ {"__c":"osrfConnectStatus","__p": \ # <8>
+ {"status":"Request Complete","statusCode":205} \ # <9>
+ },"type":"STATUS","locale":"en-CA" \ # <10>
+ }
+}]
+--------------------------------------------------------------------------------
+
+<1> 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":`).
+
+<2> The OpenSRF message identifier (`"threadTrace":0`) confirms that this
+message is in response to the request matching the same identifier.
+
+<3> The message includes a payload JSON object (`"payload":`) with an OpenSRF
+result for the request (`"__c":"osrfResult"`).
+
+<4> 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`).
+
+<5> The message also includes the message type (`"type":"RESULT"`) and the
+message locale (`"locale":"en-CA"`).
+
+<6> The second message in the set of results from the response.
+
+<7> Again, the message identifier confirms that this message is in response to
+a particular request.
+
+<8> 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.
+
+<9> 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).
+
+<10> The message also includes the message type (`"type":"RESULT"`) and the
+message locale (`"locale":"en-CA"`).
+
+
+[TIP]
+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.
+
+=== 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
+image:media/REQUEST.png[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
+image:media/CONNECT.png[CONNECT, REQUEST, and DISCONNECT flow in a stateful connection]
+
+== 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`
+http://git.evergreen-ils.org/?p=OpenSRF.git;a=blob_plain;f=src/perl/lib/OpenSRF/Application/Demo/SimpleText.pm[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:
+
+ 1. Include the base OpenSRF support libraries
+ 2. Write the code for each of your OpenSRF methods as separate procedures
+ 3. Register each method
+ 4. 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:
+
+[source,perl]
+--------------------------------------------------------------------------------
+#!/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.
+
+[id="serviceRegistration"]
+=== 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/`):
+
+[source,xml]
+--------------------------------------------------------------------------------
+<apps>
+ <opensrf.simple-text> <!-- <1> -->
+ <keepalive>3</keepalive> <!-- <2> -->
+ <stateless>1</stateless> <!-- <3> -->
+ <language>perl</language> <!-- <4> -->
+ <implementation>OpenSRF::Application::Demo::SimpleText</implementation> <!-- <5> -->
+ <max_requests>100</max_requests> <!-- <6> -->
+ <unix_config>
+ <max_requests>1000</max_requests> <!-- <7> -->
+ <unix_log>opensrf.simple-text_unix.log</unix_log> <!-- <8> -->
+ <unix_sock>opensrf.simple-text_unix.sock</unix_sock> <!-- <9> -->
+ <unix_pid>opensrf.simple-text_unix.pid</unix_pid> <!-- <10> -->
+ <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>
+--------------------------------------------------------------------------------
+
+<1> The element name is the name that the OpenSRF control scripts use to refer
+to the service.
+
+<2> Specifies the interval (in seconds) between checks to determine if the
+service is still running.
+
+<3> 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.
+
+<4> Specifies the programming language in which the service is implemented
+
+<5> Specifies the name of the library or module in which the service is implemented
+
+<6> (C implementations): Specifies the maximum number of requests a process
+serves before it is killed and replaced by a new process.
+
+<7> (Perl implementations): Specifies the maximum number of requests a process
+serves before it is killed and replaced by a new process.
+
+<8> The name of the log file for language-specific log messages such as syntax
+warnings.
+
+<9> The name of the UNIX socket used for inter-process communications.
+
+<10> 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 minimum 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`
+[source,xml]
+--------------------------------------------------------------------------------
+<router> <!-- <1> -->
+ <!-- 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> <!-- <2> -->
+ <services>
+ <service>opensrf.math</service>
+ <service>opensrf.simple-text</service> <!-- <3> -->
+ </services>
+</router>
+--------------------------------------------------------------------------------
+
+<1> This section of the `opensrf_core.xml` file is located at XPath
+`/config/opensrf/routers/`.
+
+<2> `public.localhost` is the canonical public router domain in the OpenSRF
+installation instructions.
+
+<3> 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.
+
+=== 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:
+
+==== 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:
+
+[source,sh]
+--------------------------------------------------------------------------------
+$ srfsh
+srfsh # request opensrf.simple-text opensrf.simple-text.reverse "foobar"
+
+Received Data: "raboof"
+
+=------------------------------------
+Request Completed Successfully
+Request Time in seconds: 0.016718
+=------------------------------------
+--------------------------------------------------------------------------------
+
+[id="opensrfIntrospection"]
+==== 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.
+
+[NOTE]
+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.
+
+[source,sh]
+--------------------------------------------------------------------------------
+srfsh# introspect opensrf.simple-text "opensrf.simple-text.reverse"
+--> opensrf.simple-text
+
+Received Data: {
+ "__c":"opensrf.simple-text",
+ "__p":{
+ "api_level":1,
+ "stream":0, \ # <1>
+ "object_hint":"OpenSRF_Application_Demo_SimpleText",
+ "remote":0,
+ "package":"OpenSRF::Application::Demo::SimpleText", \ # <2>
+ "api_name":"opensrf.simple-text.reverse", \ # <3>
+ "server_class":"opensrf.simple-text",
+ "signature":{ \ # <4>
+ "params":[ \ # <5>
+ {
+ "desc":"The string to reverse",
+ "name":"text",
+ "type":"string"
+ }
+ ],
+ "desc":"Returns the input string in reverse order\n", \ # <6>
+ "return":{ \ # <7>
+ "desc":"Returns the input string in reverse order",
+ "type":"string"
+ }
+ },
+ "method":"text_reverse", \ # <8>
+ "argc":1 \ # <9>
+ }
+}
+--------------------------------------------------------------------------------
+
+<1> `stream` denotes whether the method supports streaming responses or not.
+
+<2> `package` identifies which package or library implements the method.
+
+<3> `api_name` identifies the name of the OpenSRF method.
+
+<4> `signature` is a hash that describes the parameters for the method.
+
+<5> `params` is an array of hashes describing each parameter in the method;
+each parameter has a description (`desc`), name (`name`), and type (`type`).
+
+<6> `desc` is a string that describes the method itself.
+
+<7> `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`).
+
+<8> `method` identifies the name of the function or method in the source
+implementation.
+
+<9> `argc` is an integer describing the minimum number of arguments that
+must be passed to this method.
+
+==== 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.
+
+[source,perl]
+--------------------------------------------------------------------------------
+#/usr/bin/perl
+use strict;
+use OpenSRF::AppSession;
+use OpenSRF::System;
+
+OpenSRF::System->bootstrap_client(config_file => '/openils/conf/opensrf_core.xml'); # <1>
+
+my $session = OpenSRF::AppSession->create("opensrf.simple-text"); # <2>
+
+print "substring: Accepts a string and a number as input, returns a string\n";
+my $result = $session->request("opensrf.simple-text.substring", "foobar", 3); # <3>
+my $request = $result->gather(); # <4>
+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", " "); # <5>
+my $output = "Split: [";
+my $element;
+while ($element = $request->recv()) { # <6>
+ $output .= $element->content . ", "; # <7>
+}
+$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); # <8>
+$request = $result->gather(); # <9>
+print "Length: " . $result->{'length'} . "\n";
+print "Word count: " . $result->{'word_count'} . "\n";
+
+$session->disconnect(); # <10>
+--------------------------------------------------------------------------------
+
+<1> 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.
+
+<2> 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.
+
+<3> 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.
+
+<4> 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.
+
+<5> 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.
+
+<6> 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.
+
+<7> 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 <<httpResults,the HTTP results example>>.
+
+<8> This `request()` call passes an array to the
+`opensrf.simple-text.statistics` method defined by the `opensrf.simple-text`
+OpenSRF service.
+
+<9> The result object returns a hash reference via `gather()`. The hash
+contains the `length` and `word_count` keys we defined in the method.
+
+<10> The `OpenSRF::AppSession->disconnect()` method closes the XMPP client
+connection and cleans up resources associated with the session.
+
+=== 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
+[source,perl]
+--------------------------------------------------------------------------------
+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.
+
+=== 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"
+[source,xml]
+--------------------------------------------------------------------------------
+<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"> <!-- <1> -->
+ <fields oils_persist:primary="usr" oils_persist:sequence=""> <!-- <2> -->
+ <field name="balance_owed" reporter:datatype="money" /> <!-- <3> -->
+ <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"/> <!-- <4> -->
+ </links>
+ <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"> <!-- <5> -->
+ <actions>
+ <retrieve permission="VIEW_USER"> <!-- <6> -->
+ <context link="usr" field="home_ou"/> <!-- <7> -->
+ </retrieve>
+ </actions>
+ </permacrud>
+</class>
+--------------------------------------------------------------------------------
+
+<1> 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.
+
+<2> 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.
+
+<3> 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.
+
+<4> 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.
+
+<5> The `<permacrud>` element defines the permissions that must have been
+granted to a user to operate on instances of this class.
+
+<6> 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.
+
+<7> 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.
+
+=== 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
+[source,perl]
+--------------------------------------------------------------------------------
+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) { # <1>
+ $conn->respond($string);
+ }
+ return undef;
+}
+
+__PACKAGE__->register_method(
+ method => 'text_split',
+ api_name => 'opensrf.simple-text.split',
+ stream => 1 # <2>
+);
+--------------------------------------------------------------------------------
+
+<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.
+
+<2> Registering the method as a streaming method instructs OpenSRF to also
+register an atomic variant (`opensrf.simple-text.split.atomic`).
+
+=== 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:
+
+[source,perl]
+--------------------------------------------------------------------------------
+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!
+
+=== 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.
+
+[source,perl]
+--------------------------------------------------------------------------------
+use OpenSRF::Utils::Cache; # <1>
+sub test_cache {
+ my $self = shift;
+ my $conn = shift;
+ my $test_key = shift;
+ my $cache = OpenSRF::Utils::Cache->new('global'); # <2>
+ my $cache_key = "opensrf.simple-text.test_cache.$test_key"; # <3>
+ my $result = $cache->get_cache($cache_key) || undef; # <4>
+ if ($result) {
+ $logger->info("Resolver found a cache hit");
+ return $result;
+ }
+ sleep 10; # <5>
+ my $cache_timeout = 300; # <6>
+ $cache->put_cache($cache_key, "here", $cache_timeout); # <7>
+ return "There was no cache hit.";
+}
+--------------------------------------------------------------------------------
+
+This example:
+
+<1> Imports the OpenSRF::Utils::Cache module
+
+<2> Creates a cache object
+
+<3> Creates a unique cache key based on the OpenSRF method name and
+request input value
+
+<4> Checks to see if the cache key already exists; if so, it immediately
+returns that value
+
+<5> 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
+
+<6> Sets a value for the lifetime of the cache key in seconds
+
+<7> 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
+
+=== 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.
+
+=== 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 <<serviceRegistration>> --, 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
+http://www.w3.org/TR/xpath/[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.
+
+== 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.
+
+=== 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.
+
+=== 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"):
+[source,xml]
+--------------------------------------------------------------------------------
+<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")
+[source,xml]
+--------------------------------------------------------------------------------
+<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 <<OpenSRFOverHTTP,OpenSRF over
+HTTP examples>> that we previously dissected.
+
+=== 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 <<opensrfIntrospection,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
+
+== 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.
+
+== Evergreen after one year: reflections on OpenSRF ==
+
+http://projectconifer.ca[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.
+
+=== 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.
+
+=== 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
+http://git.evergreen-ils.org/?p=working/random.git;a=shortlog;h=refs/heads/collab/berick/constrictor[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.
+
+== 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.
+
+== Appendix: Python client ==
+
+Following is a Python client that makes the same OpenSRF calls as the Perl
+client:
+
+[source, python]
+--------------------------------------------------------------------------------
+include::python_client.py[]
+--------------------------------------------------------------------------------
+
+NOTE: 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.
+
+// vim: set syntax=asciidoc:
+++ /dev/null
-= Easing gently into OpenSRF =
-
-== Abstract ==
-The Evergreen open-source library system serves library consortia composed of
-hundreds of branches with millions of patrons - for example,
-http://www.georgialibraries.org/statelibrarian/bythenumbers.pdf[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.
-
-== 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 http://evergreen-ils.org/blog/?p=56[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.
-
-=== 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:
-
- * http://tools.ietf.org/html/rfc3920[Extensible Messaging and Presence
-Protocol] (XMPP, sometimes referred to as Jabber) - provides the base messaging
-infrastructure between OpenSRF clients and servers
- * http://json.org[JavaScript Object Notation] (JSON) - serializes the content
-of each XMPP message in a standardized and concise format
- * http://memcached.org[memcached] - provides the caching service
- * http://tools.ietf.org/html/rfc5424[syslog] - the standard UNIX logging
-service
-
-Unfortunately, the
-http://evergreen-ils.org/dokuwiki/doku.php?id=osrf-devel:primer[OpenSRF
-reference documentation], although augmented by the
-http://evergreen-ils.org/dokuwiki/doku.php?id=osrf-devel:primer[OpenSRF
-glossary], blog posts like http://evergreen-ils.org/blog/?p=36[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.
-
-=== OpenSRF communication flows over XMPP ===
-
-The XMPP messaging service underpins OpenSRF, requiring an XMPP server such
-as http://www.ejabberd.im/[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`.
-
-[id="OpenSRFOverHTTP"]
-=== 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
-http://www.open-ils.org/dokuwiki/doku.php?id=opensrf_over_http[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
-[source,bash]
---------------------------------------------------------------------------------
-# curl request broken up over multiple lines for legibility
-curl -H "X-OpenSRF-service: opensrf.simple-text" \ # <1>
- --data 'osrf-msg=[ \ # <2>
- {"__c":"osrfMessage","__p":{"threadTrace":0,"locale":"en-CA", \ # <3>
- "type":"REQUEST","payload": {"__c":"osrfMethod","__p": \
- {"method":"opensrf.simple-text.reverse","params":["foobar"]} \
- }} \
- }]' \
-http://localhost/osrf-http-translator \ # <4>
---------------------------------------------------------------------------------
-
-<1> The `X-OpenSRF-service` header identifies the OpenSRF service of interest.
-
-<2> The POST request consists of a single parameter, the `osrf-msg` value,
-which contains a JSON array.
-
-<3> 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"`
-
-<4> 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.
-
-[id="httpResults"]
-.Results from an HTTP POST request to an OpenSRF method via the OpenSRF HTTP Translator
-[source,bash]
---------------------------------------------------------------------------------
-# HTTP response broken up over multiple lines for legibility
-[{"__c":"osrfMessage","__p": \ # <1>
- {"threadTrace":0, "payload": \ # <2>
- {"__c":"osrfResult","__p": \ # <3>
- {"status":"OK","content":"raboof","statusCode":200} \ # <4>
- },"type":"RESULT","locale":"en-CA" \ # <5>
- }
-},
-{"__c":"osrfMessage","__p": \ # <6>
- {"threadTrace":0,"payload": \ # <7>
- {"__c":"osrfConnectStatus","__p": \ # <8>
- {"status":"Request Complete","statusCode":205} \ # <9>
- },"type":"STATUS","locale":"en-CA" \ # <10>
- }
-}]
---------------------------------------------------------------------------------
-
-<1> 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":`).
-
-<2> The OpenSRF message identifier (`"threadTrace":0`) confirms that this
-message is in response to the request matching the same identifier.
-
-<3> The message includes a payload JSON object (`"payload":`) with an OpenSRF
-result for the request (`"__c":"osrfResult"`).
-
-<4> 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`).
-
-<5> The message also includes the message type (`"type":"RESULT"`) and the
-message locale (`"locale":"en-CA"`).
-
-<6> The second message in the set of results from the response.
-
-<7> Again, the message identifier confirms that this message is in response to
-a particular request.
-
-<8> 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.
-
-<9> 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).
-
-<10> The message also includes the message type (`"type":"RESULT"`) and the
-message locale (`"locale":"en-CA"`).
-
-
-[TIP]
-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.
-
-=== 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
-image:media/REQUEST.png[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
-image:media/CONNECT.png[CONNECT, REQUEST, and DISCONNECT flow in a stateful connection]
-
-== 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`
-http://git.evergreen-ils.org/?p=OpenSRF.git;a=blob_plain;f=src/perl/lib/OpenSRF/Application/Demo/SimpleText.pm[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:
-
- 1. Include the base OpenSRF support libraries
- 2. Write the code for each of your OpenSRF methods as separate procedures
- 3. Register each method
- 4. 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:
-
-[source,perl]
---------------------------------------------------------------------------------
-#!/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.
-
-[id="serviceRegistration"]
-=== 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/`):
-
-[source,xml]
---------------------------------------------------------------------------------
-<apps>
- <opensrf.simple-text> <!-- <1> -->
- <keepalive>3</keepalive> <!-- <2> -->
- <stateless>1</stateless> <!-- <3> -->
- <language>perl</language> <!-- <4> -->
- <implementation>OpenSRF::Application::Demo::SimpleText</implementation> <!-- <5> -->
- <max_requests>100</max_requests> <!-- <6> -->
- <unix_config>
- <max_requests>1000</max_requests> <!-- <7> -->
- <unix_log>opensrf.simple-text_unix.log</unix_log> <!-- <8> -->
- <unix_sock>opensrf.simple-text_unix.sock</unix_sock> <!-- <9> -->
- <unix_pid>opensrf.simple-text_unix.pid</unix_pid> <!-- <10> -->
- <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>
---------------------------------------------------------------------------------
-
-<1> The element name is the name that the OpenSRF control scripts use to refer
-to the service.
-
-<2> Specifies the interval (in seconds) between checks to determine if the
-service is still running.
-
-<3> 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.
-
-<4> Specifies the programming language in which the service is implemented
-
-<5> Specifies the name of the library or module in which the service is implemented
-
-<6> (C implementations): Specifies the maximum number of requests a process
-serves before it is killed and replaced by a new process.
-
-<7> (Perl implementations): Specifies the maximum number of requests a process
-serves before it is killed and replaced by a new process.
-
-<8> The name of the log file for language-specific log messages such as syntax
-warnings.
-
-<9> The name of the UNIX socket used for inter-process communications.
-
-<10> 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 minimum 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`
-[source,xml]
---------------------------------------------------------------------------------
-<router> <!-- <1> -->
- <!-- 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> <!-- <2> -->
- <services>
- <service>opensrf.math</service>
- <service>opensrf.simple-text</service> <!-- <3> -->
- </services>
-</router>
---------------------------------------------------------------------------------
-
-<1> This section of the `opensrf_core.xml` file is located at XPath
-`/config/opensrf/routers/`.
-
-<2> `public.localhost` is the canonical public router domain in the OpenSRF
-installation instructions.
-
-<3> 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.
-
-=== 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:
-
-==== 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:
-
-[source,sh]
---------------------------------------------------------------------------------
-$ srfsh
-srfsh # request opensrf.simple-text opensrf.simple-text.reverse "foobar"
-
-Received Data: "raboof"
-
-=------------------------------------
-Request Completed Successfully
-Request Time in seconds: 0.016718
-=------------------------------------
---------------------------------------------------------------------------------
-
-[id="opensrfIntrospection"]
-==== 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.
-
-[NOTE]
-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.
-
-[source,sh]
---------------------------------------------------------------------------------
-srfsh# introspect opensrf.simple-text "opensrf.simple-text.reverse"
---> opensrf.simple-text
-
-Received Data: {
- "__c":"opensrf.simple-text",
- "__p":{
- "api_level":1,
- "stream":0, \ # <1>
- "object_hint":"OpenSRF_Application_Demo_SimpleText",
- "remote":0,
- "package":"OpenSRF::Application::Demo::SimpleText", \ # <2>
- "api_name":"opensrf.simple-text.reverse", \ # <3>
- "server_class":"opensrf.simple-text",
- "signature":{ \ # <4>
- "params":[ \ # <5>
- {
- "desc":"The string to reverse",
- "name":"text",
- "type":"string"
- }
- ],
- "desc":"Returns the input string in reverse order\n", \ # <6>
- "return":{ \ # <7>
- "desc":"Returns the input string in reverse order",
- "type":"string"
- }
- },
- "method":"text_reverse", \ # <8>
- "argc":1 \ # <9>
- }
-}
---------------------------------------------------------------------------------
-
-<1> `stream` denotes whether the method supports streaming responses or not.
-
-<2> `package` identifies which package or library implements the method.
-
-<3> `api_name` identifies the name of the OpenSRF method.
-
-<4> `signature` is a hash that describes the parameters for the method.
-
-<5> `params` is an array of hashes describing each parameter in the method;
-each parameter has a description (`desc`), name (`name`), and type (`type`).
-
-<6> `desc` is a string that describes the method itself.
-
-<7> `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`).
-
-<8> `method` identifies the name of the function or method in the source
-implementation.
-
-<9> `argc` is an integer describing the minimum number of arguments that
-must be passed to this method.
-
-==== 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.
-
-[source,perl]
---------------------------------------------------------------------------------
-#/usr/bin/perl
-use strict;
-use OpenSRF::AppSession;
-use OpenSRF::System;
-
-OpenSRF::System->bootstrap_client(config_file => '/openils/conf/opensrf_core.xml'); # <1>
-
-my $session = OpenSRF::AppSession->create("opensrf.simple-text"); # <2>
-
-print "substring: Accepts a string and a number as input, returns a string\n";
-my $result = $session->request("opensrf.simple-text.substring", "foobar", 3); # <3>
-my $request = $result->gather(); # <4>
-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", " "); # <5>
-my $output = "Split: [";
-my $element;
-while ($element = $request->recv()) { # <6>
- $output .= $element->content . ", "; # <7>
-}
-$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); # <8>
-$request = $result->gather(); # <9>
-print "Length: " . $result->{'length'} . "\n";
-print "Word count: " . $result->{'word_count'} . "\n";
-
-$session->disconnect(); # <10>
---------------------------------------------------------------------------------
-
-<1> 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.
-
-<2> 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.
-
-<3> 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.
-
-<4> 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.
-
-<5> 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.
-
-<6> 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.
-
-<7> 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 <<httpResults,the HTTP results example>>.
-
-<8> This `request()` call passes an array to the
-`opensrf.simple-text.statistics` method defined by the `opensrf.simple-text`
-OpenSRF service.
-
-<9> The result object returns a hash reference via `gather()`. The hash
-contains the `length` and `word_count` keys we defined in the method.
-
-<10> The `OpenSRF::AppSession->disconnect()` method closes the XMPP client
-connection and cleans up resources associated with the session.
-
-=== 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
-[source,perl]
---------------------------------------------------------------------------------
-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.
-
-=== 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"
-[source,xml]
---------------------------------------------------------------------------------
-<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"> <!-- <1> -->
- <fields oils_persist:primary="usr" oils_persist:sequence=""> <!-- <2> -->
- <field name="balance_owed" reporter:datatype="money" /> <!-- <3> -->
- <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"/> <!-- <4> -->
- </links>
- <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"> <!-- <5> -->
- <actions>
- <retrieve permission="VIEW_USER"> <!-- <6> -->
- <context link="usr" field="home_ou"/> <!-- <7> -->
- </retrieve>
- </actions>
- </permacrud>
-</class>
---------------------------------------------------------------------------------
-
-<1> 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.
-
-<2> 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.
-
-<3> 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.
-
-<4> 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.
-
-<5> The `<permacrud>` element defines the permissions that must have been
-granted to a user to operate on instances of this class.
-
-<6> 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.
-
-<7> 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.
-
-=== 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
-[source,perl]
---------------------------------------------------------------------------------
-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) { # <1>
- $conn->respond($string);
- }
- return undef;
-}
-
-__PACKAGE__->register_method(
- method => 'text_split',
- api_name => 'opensrf.simple-text.split',
- stream => 1 # <2>
-);
---------------------------------------------------------------------------------
-
-<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.
-
-<2> Registering the method as a streaming method instructs OpenSRF to also
-register an atomic variant (`opensrf.simple-text.split.atomic`).
-
-=== 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:
-
-[source,perl]
---------------------------------------------------------------------------------
-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!
-
-=== 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.
-
-[source,perl]
---------------------------------------------------------------------------------
-use OpenSRF::Utils::Cache; # <1>
-sub test_cache {
- my $self = shift;
- my $conn = shift;
- my $test_key = shift;
- my $cache = OpenSRF::Utils::Cache->new('global'); # <2>
- my $cache_key = "opensrf.simple-text.test_cache.$test_key"; # <3>
- my $result = $cache->get_cache($cache_key) || undef; # <4>
- if ($result) {
- $logger->info("Resolver found a cache hit");
- return $result;
- }
- sleep 10; # <5>
- my $cache_timeout = 300; # <6>
- $cache->put_cache($cache_key, "here", $cache_timeout); # <7>
- return "There was no cache hit.";
-}
---------------------------------------------------------------------------------
-
-This example:
-
-<1> Imports the OpenSRF::Utils::Cache module
-
-<2> Creates a cache object
-
-<3> Creates a unique cache key based on the OpenSRF method name and
-request input value
-
-<4> Checks to see if the cache key already exists; if so, it immediately
-returns that value
-
-<5> 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
-
-<6> Sets a value for the lifetime of the cache key in seconds
-
-<7> 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
-
-=== 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.
-
-=== 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 <<serviceRegistration>> --, 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
-http://www.w3.org/TR/xpath/[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.
-
-== 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.
-
-=== 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.
-
-=== 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"):
-[source,xml]
---------------------------------------------------------------------------------
-<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")
-[source,xml]
---------------------------------------------------------------------------------
-<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 <<OpenSRFOverHTTP,OpenSRF over
-HTTP examples>> that we previously dissected.
-
-=== 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 <<opensrfIntrospection,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
-
-== 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.
-
-== Evergreen after one year: reflections on OpenSRF ==
-
-http://projectconifer.ca[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.
-
-=== 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.
-
-=== 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
-http://git.evergreen-ils.org/?p=working/random.git;a=shortlog;h=refs/heads/collab/berick/constrictor[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.
-
-== 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.
-
-== Appendix: Python client ==
-
-Following is a Python client that makes the same OpenSRF calls as the Perl
-client:
-
-[source, python]
---------------------------------------------------------------------------------
-include::python_client.py[]
---------------------------------------------------------------------------------
-
-NOTE: 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.
-
-// vim: set syntax=asciidoc:
--- /dev/null
+Developing with pgTAP tests
+===========================
+
+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:
++
+[source,sql]
+------------------------------------------------------------------------------
+CREATE EXTENSION pgtap;
+------------------------------------------------------------------------------
+
+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`
+
+
+++ /dev/null
-Developing with pgTAP tests
-===========================
-
-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:
-+
-[source,sql]
-------------------------------------------------------------------------------
-CREATE EXTENSION pgtap;
-------------------------------------------------------------------------------
-
-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`
-
-
--- /dev/null
+== 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
+http://evergreen-ils.org/communicate/[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.
+
+ * <<_processing_action_triggers,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)
+ * <<_creating_the_evergreen_database,eg_db_config>>
+ -- Creates database and schema, updates config files, sets Evergreen
+ administrator username and password
+ * fine_generator.pl
+ * hold_targeter.pl
+ * <<_importing_authority_records_from_command_line,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,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
+
+
+anchor:_marc_export[]
+
+=== marc_export: Exporting Bibliographic Records into MARC files
+
+indexterm:[marc_export]
+
+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.
+
+[NOTE]
+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:
++
+[source,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
+----
+
+[NOTE]
+====================
+`marc_export` was updated in Evergreen 2.6 and now does not output progress
+as it executes.
+====================
+
+[NOTE]
+====================
+You can use the `--since` option to export records modified after a
+certain date and time.
+====================
+
+[NOTE]
+====================
+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`.
+====================
+
+[NOTE]
+====================
+For more information, run marc_export with the -h option:
+
+ ./marc_export -h
+====================
+
+
+
+=== Importing Authority Records from Command Line
+
+indexterm:[marc2are.pl]
+indexterm:[pg_loader.pl]
+
+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,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
+----
++
+[NOTE]
+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
+----
++
+[TIP]
+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
+----
+
+
+++ /dev/null
-== 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
-http://evergreen-ils.org/communicate/[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.
-
- * <<_processing_action_triggers,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)
- * <<_creating_the_evergreen_database,eg_db_config>>
- -- Creates database and schema, updates config files, sets Evergreen
- administrator username and password
- * fine_generator.pl
- * hold_targeter.pl
- * <<_importing_authority_records_from_command_line,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,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
-
-
-anchor:_marc_export[]
-
-=== marc_export: Exporting Bibliographic Records into MARC files
-
-indexterm:[marc_export]
-
-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.
-
-[NOTE]
-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:
-+
-[source,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
-----
-
-[NOTE]
-====================
-`marc_export` was updated in Evergreen 2.6 and now does not output progress
-as it executes.
-====================
-
-[NOTE]
-====================
-You can use the `--since` option to export records modified after a
-certain date and time.
-====================
-
-[NOTE]
-====================
-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`.
-====================
-
-[NOTE]
-====================
-For more information, run marc_export with the -h option:
-
- ./marc_export -h
-====================
-
-
-
-=== Importing Authority Records from Command Line
-
-indexterm:[marc2are.pl]
-indexterm:[pg_loader.pl]
-
-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,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
-----
-+
-[NOTE]
-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
-----
-+
-[TIP]
-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
-----
-
-
--- /dev/null
+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.
+
+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
+
+* https://bitbucket.org/izi/polib/wiki/Home[polib]
+* http://translate.sourceforge.net[translate-toolkit]
+* http://pypi.python.org/pypi/python-Levenshtein/[levenshtein]
+* http://pypi.python.org/pypi/setuptools[setuptools]
+* http://pypi.python.org/pypi/simplejson/[simplejson]
+* http://lxml.de/[lxml]
+
+Updating the translations
+-------------------------
+
+. Check out the latest translations from Launchpad by branching the Bazaar
+repository:
++
+[source,bash]
+------------------------------------------------------------------------------
+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:
++
+[source,bash]
+------------------------------------------------------------------------------
+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.
+++ /dev/null
-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.
-
-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
-
-* https://bitbucket.org/izi/polib/wiki/Home[polib]
-* http://translate.sourceforge.net[translate-toolkit]
-* http://pypi.python.org/pypi/python-Levenshtein/[levenshtein]
-* http://pypi.python.org/pypi/setuptools[setuptools]
-* http://pypi.python.org/pypi/simplejson/[simplejson]
-* http://lxml.de/[lxml]
-
-Updating the translations
--------------------------
-
-. Check out the latest translations from Launchpad by branching the Bazaar
-repository:
-+
-[source,bash]
-------------------------------------------------------------------------------
-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:
-+
-[source,bash]
-------------------------------------------------------------------------------
-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.
--- /dev/null
+Setting Up EDI Acquisitions
+---------------------------
+
+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.
+
+Installation
+~~~~~~~~~~~~
+
+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.
+
+[NOTE]
+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
+
+1. As the *opensrf* user, copy the EDI Translator code found in
+ Open-ILS/src/edi_translator to somewhere accessible
+ (for example, /openils/var/edi):
++
+[source, bash]
+--------------------------------------------------
+cp -r Open-ILS/src/edi_translator /openils/var/edi
+--------------------------------------------------
+2. Navigate to where you have saved the code to begin next step:
++
+[source, bash]
+-------------------
+cd /openils/var/edi
+-------------------
+3. 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)
++
+[source, bash]
+-----------
+./install.sh
+-----------
+4. 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:
++
+[source, bash]
+-----------------
+./edi_webrick.bash
+-----------------
+5. 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:
++
+[source, bash]
+------------------------------------------------------------------------------------------
+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):
++
+[source, bash]
+-----------------------
+kill -INT $(pgrep ruby)
+-----------------------
+
+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.
+
+1. As the *opensrf* user, copy edi_pusher.pl and edi_fetcher.pl from
+ Open-ILS/src/support-scripts into /openils/bin:
++
+[source, bash]
+--------------------------------------------------
+cp Open-ILS/src/support-scripts/edi_pusher.pl /openils/bin
+cp Open-ILS/src/support-scripts/edi_fetcher.pl /openils/bin
+--------------------------------------------------
+2. 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:
++
+[source, bash]
+-----------------------------------------------------------------------
+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.
+
+[NOTE]
+You may choose to run the EDI scripts more or less frequently based on the
+necessary response times from your vendors.
+
+Configuration
+~~~~~~~~~~~~~
+
+Configuring Providers
+^^^^^^^^^^^^^^^^^^^^^
+
+Look in Admin > Server Administration > Acquisitions > Providers
+
+[options="header"]
+|======================================================================================
+|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
+|======================================================================================
+
+Configuring EDI Accounts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Look in Admin > Server Administration > Acquisitions > EDI Accounts
+
+[options="header"]
+|===============================================================================================================
+|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.
+|===============================================================================================================
+
+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.
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+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:
+
+[source, bash]
+----------------------------------------------------------------------------------------------------------------------------------------------
+"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:
+
+[source, bash]
+------------------------------------------------------------------------------------------------------------------------------------------
+"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 -%]
+],
+------------------------------------------------------------------------------------------------------------------------------------------
+
+++ /dev/null
-Setting Up EDI Acquisitions
----------------------------
-
-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.
-
-Installation
-~~~~~~~~~~~~
-
-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.
-
-[NOTE]
-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
-
-1. As the *opensrf* user, copy the EDI Translator code found in
- Open-ILS/src/edi_translator to somewhere accessible
- (for example, /openils/var/edi):
-+
-[source, bash]
---------------------------------------------------
-cp -r Open-ILS/src/edi_translator /openils/var/edi
---------------------------------------------------
-2. Navigate to where you have saved the code to begin next step:
-+
-[source, bash]
--------------------
-cd /openils/var/edi
--------------------
-3. 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)
-+
-[source, bash]
------------
-./install.sh
------------
-4. 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:
-+
-[source, bash]
------------------
-./edi_webrick.bash
------------------
-5. 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:
-+
-[source, bash]
-------------------------------------------------------------------------------------------
-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):
-+
-[source, bash]
------------------------
-kill -INT $(pgrep ruby)
------------------------
-
-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.
-
-1. As the *opensrf* user, copy edi_pusher.pl and edi_fetcher.pl from
- Open-ILS/src/support-scripts into /openils/bin:
-+
-[source, bash]
---------------------------------------------------
-cp Open-ILS/src/support-scripts/edi_pusher.pl /openils/bin
-cp Open-ILS/src/support-scripts/edi_fetcher.pl /openils/bin
---------------------------------------------------
-2. 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:
-+
-[source, bash]
------------------------------------------------------------------------
-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.
-
-[NOTE]
-You may choose to run the EDI scripts more or less frequently based on the
-necessary response times from your vendors.
-
-Configuration
-~~~~~~~~~~~~~
-
-Configuring Providers
-^^^^^^^^^^^^^^^^^^^^^
-
-Look in Admin > Server Administration > Acquisitions > Providers
-
-[options="header"]
-|======================================================================================
-|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
-|======================================================================================
-
-Configuring EDI Accounts
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Look in Admin > Server Administration > Acquisitions > EDI Accounts
-
-[options="header"]
-|===============================================================================================================
-|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.
-|===============================================================================================================
-
-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.
-
-Troubleshooting
-~~~~~~~~~~~~~~~
-
-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:
-
-[source, bash]
-----------------------------------------------------------------------------------------------------------------------------------------------
-"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:
-
-[source, bash]
-------------------------------------------------------------------------------------------------------------------------------------------
-"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 -%]
-],
-------------------------------------------------------------------------------------------------------------------------------------------
-
--- /dev/null
+Installing the Evergreen server
+===============================
+:toc:
+:numbered:
+
+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.
+
+Preamble: developer instructions
+--------------------------------
+
+[NOTE]
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+autoreconf -i
+------------------------------------------------------------------------------
+
+Installing prerequisites
+------------------------
+
+ * **PostgreSQL**: Version 9.4 is recommended.
+ The minimum supported version is 9.3.
+ * **Linux**: Evergreen 2.8 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.
+
+1. 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/
+2. 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.
++
+3. 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:
++
+[source, bash]
+------------------------------------------------------------------------------
+make -f Open-ILS/src/extras/Makefile.install <osname>
+------------------------------------------------------------------------------
++
+4. Add the libdbi-libdbd libraries to the system dynamic library path by
+ issuing the following commands as the *root* Linux account:
++
+[NOTE]
+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
+[source, bash]
+------------------------------------------------------------------------------
+echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
+ldconfig
+------------------------------------------------------------------------------
+
+5. 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.
++
+[source, bash]
+------------------------------------------------------------------------------
+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.
++
+[source, bash]
+------------------------------------------------------------------------------
+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.
++
+[source, bash]
+------------------------------------------------------------------------------
+make -f Open-ILS/src/extras/Makefile.install <osname>-packager
+------------------------------------------------------------------------------
+
+Optional: Extra steps for web staff client
+------------------------------------------
+
+[NOTE]
+Skip this entire section if you are using an official release tarball downloaded
+from http://evergreen-ils.org/downloads
+
+Install dependencies for web staff client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[NOTE]
+You may skip this section if 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 files for web staff client>>.
+
+1. Install the long-term stability (LTS) release of
+https://nodejs.org[Node.js]. Add the Node.js `/bin` directory to your
+environment variable `PATH`.
++
+2. Install Grunt CLI
++
+[source,sh]
+------------------------------------------------------------------------------
+% sudo npm install -g grunt-cli
+------------------------------------------------------------------------------
+
+[[install_files_for_web_staff_client]]
+Install files for web staff client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Building, Testing, Minification: The remaining steps all take place within
+ the staff JS web root:
++
+[source,sh]
+------------------------------------------------------------------------------
+cd $EVERGREEN_ROOT/Open-ILS/web/js/ui/default/staff/
+------------------------------------------------------------------------------
++
+2. Install Project-local Dependencies. npm inspects the 'package.json' file
+ for dependencies and fetches them from the Node package network.
++
+[source,sh]
+------------------------------------------------------------------------------
+npm install # fetch JS dependencies
+------------------------------------------------------------------------------
++
+3. Run the build script.
++
+[source,sh]
+------------------------------------------------------------------------------
+# build, run tests, concat+minify
+grunt all
+------------------------------------------------------------------------------
+
+
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+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`.
+
+Installation instructions
+-------------------------
+
+1. 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.
++
+[source, bash]
+------------------------------------------------------------------------------
+make STAFF_CLIENT_STAMP_ID=rel_name install
+------------------------------------------------------------------------------
++
+2. 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':
++
+[source, bash]
+------------------------------------------------------------------------------
+cd /openils/var/web/xul
+ln -sf rel_name/server server
+------------------------------------------------------------------------------
+
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+chown -R opensrf:opensrf /openils
+------------------------------------------------------------------------------
+
+Additional Instructions for Developers
+--------------------------------------
+
+[NOTE]
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+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/.
+------------------------------------------------------------------------------
+
+
+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
+[source,bash]
+------------------------------------------------------------------------------
+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
+[source,bash]
+------------------------------------------------------------------------------------
+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:
++
+[source,bash]
+------------------------------------------------------------------------------
+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.
+ a. 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`.
+ a. Change `KeepAliveTimeout` to `1`.
+ b. 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`)
+[source,bash]
+------------------------------------------------------------------------------
+<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`)
+[source,bash]
+------------------------------------------------------------------------------
+<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:
++
+[source,bash]
+------------------------------------------------------------------------------
+a2dismod mpm_event
+a2enmod mpm_prefork
+------------------------------------------------------------------------------
++
+. (Debian Wheezy): As the *root* Linux account, enable the Evergreen site:
++
+[source,bash]
+------------------------------------------------------------------------------
+a2dissite default # OPTIONAL: disable the default site (the "It Works" page)
+a2ensite eg.conf
+------------------------------------------------------------------------------
++
+(Ubuntu Trusty, Ubuntu Xenial, Debian Jessie):
++
+[source,bash]
+------------------------------------------------------------------------------
+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:
++
+[source,bash]
+------------------------------------------------------------------------------
+chown opensrf /var/lock/apache2
+------------------------------------------------------------------------------
+
+Learn more about additional Apache options in the following sections:
+
+ * <<_apache_rewrite_tricks,Apache Rewrite Tricks>>
+ * <<_apache_access_handler_perl_module,Apache Access Handler Perl Module>>
+
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+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.
+
+[NOTE]
+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,Creating the Evergreen
+database>>, sets the database connection information in `opensrf.xml` for you.
+
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+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,Notifications / Action Triggers>>.
+
+Creating the Evergreen database
+-------------------------------
+
+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.
+
+[source, bash]
+------------------------------------------------------------------------------
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+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
+
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+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.
+
+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.
+
+Creating the database on a remote server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+In a production instance of Evergreen, your PostgreSQL server should be
+installed on a dedicated server.
+
+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`.
+
+Starting Evergreen
+------------------
+1. As the *root* Linux account, start the `memcached` and `ejabberd` services
+(if they aren't already running):
++
+[source, bash]
+------------------------------------------------------------------------------
+/etc/init.d/ejabberd start
+/etc/init.d/memcached start
+------------------------------------------------------------------------------
++
+2. 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.
++
+[source, bash]
+------------------------------------------------------------------------------
+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:
++
+[source, bash]
+------------------------------------------------------------------------------
+export PATH=$PATH:/openils/bin
+------------------------------------------------------------------------------
++
+3. 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.
+):
++
+[source, bash]
+------------------------------------------------------------------------------
+autogen.sh
+------------------------------------------------------------------------------
++
+4. As the *root* Linux account, restart the Apache Web server:
++
+[source, bash]
+------------------------------------------------------------------------------
+/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.
+
+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:
+
+[source, bash]
+------------------------------------------------------------------------------
+/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
+ ------------------------------------
+[[install-troubleshooting-1]]
+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 http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[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
+ http://evergreen-ils.org/communicate/mailing-lists/[Evergreen development
+mailing list] for assistance before making any drastic changes to your system
+ configuration.
+
+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.
+
+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.
+++ /dev/null
-Installing the Evergreen server
-===============================
-:toc:
-:numbered:
-
-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.
-
-Preamble: developer instructions
---------------------------------
-
-[NOTE]
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-autoreconf -i
-------------------------------------------------------------------------------
-
-Installing prerequisites
-------------------------
-
- * **PostgreSQL**: Version 9.4 is recommended.
- The minimum supported version is 9.3.
- * **Linux**: Evergreen 2.8 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.
-
-1. 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/
-2. 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.
-+
-3. 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:
-+
-[source, bash]
-------------------------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install <osname>
-------------------------------------------------------------------------------
-+
-4. Add the libdbi-libdbd libraries to the system dynamic library path by
- issuing the following commands as the *root* Linux account:
-+
-[NOTE]
-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
-[source, bash]
-------------------------------------------------------------------------------
-echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
-ldconfig
-------------------------------------------------------------------------------
-
-5. 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.
-+
-[source, bash]
-------------------------------------------------------------------------------
-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.
-+
-[source, bash]
-------------------------------------------------------------------------------
-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.
-+
-[source, bash]
-------------------------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install <osname>-packager
-------------------------------------------------------------------------------
-
-Optional: Extra steps for web staff client
-------------------------------------------
-
-[NOTE]
-Skip this entire section if you are using an official release tarball downloaded
-from http://evergreen-ils.org/downloads
-
-Install dependencies for web staff client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-[NOTE]
-You may skip this section if 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 files for web staff client>>.
-
-1. Install the long-term stability (LTS) release of
-https://nodejs.org[Node.js]. Add the Node.js `/bin` directory to your
-environment variable `PATH`.
-+
-2. Install Grunt CLI
-+
-[source,sh]
-------------------------------------------------------------------------------
-% sudo npm install -g grunt-cli
-------------------------------------------------------------------------------
-
-[[install_files_for_web_staff_client]]
-Install files for web staff client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Building, Testing, Minification: The remaining steps all take place within
- the staff JS web root:
-+
-[source,sh]
-------------------------------------------------------------------------------
-cd $EVERGREEN_ROOT/Open-ILS/web/js/ui/default/staff/
-------------------------------------------------------------------------------
-+
-2. Install Project-local Dependencies. npm inspects the 'package.json' file
- for dependencies and fetches them from the Node package network.
-+
-[source,sh]
-------------------------------------------------------------------------------
-npm install # fetch JS dependencies
-------------------------------------------------------------------------------
-+
-3. Run the build script.
-+
-[source,sh]
-------------------------------------------------------------------------------
-# build, run tests, concat+minify
-grunt all
-------------------------------------------------------------------------------
-
-
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-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`.
-
-Installation instructions
--------------------------
-
-1. 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.
-+
-[source, bash]
-------------------------------------------------------------------------------
-make STAFF_CLIENT_STAMP_ID=rel_name install
-------------------------------------------------------------------------------
-+
-2. 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':
-+
-[source, bash]
-------------------------------------------------------------------------------
-cd /openils/var/web/xul
-ln -sf rel_name/server server
-------------------------------------------------------------------------------
-
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-chown -R opensrf:opensrf /openils
-------------------------------------------------------------------------------
-
-Additional Instructions for Developers
---------------------------------------
-
-[NOTE]
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-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/.
-------------------------------------------------------------------------------
-
-
-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
-[source,bash]
-------------------------------------------------------------------------------
-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
-[source,bash]
-------------------------------------------------------------------------------------
-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:
-+
-[source,bash]
-------------------------------------------------------------------------------
-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.
- a. 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`.
- a. Change `KeepAliveTimeout` to `1`.
- b. 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`)
-[source,bash]
-------------------------------------------------------------------------------
-<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`)
-[source,bash]
-------------------------------------------------------------------------------
-<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:
-+
-[source,bash]
-------------------------------------------------------------------------------
-a2dismod mpm_event
-a2enmod mpm_prefork
-------------------------------------------------------------------------------
-+
-. (Debian Wheezy): As the *root* Linux account, enable the Evergreen site:
-+
-[source,bash]
-------------------------------------------------------------------------------
-a2dissite default # OPTIONAL: disable the default site (the "It Works" page)
-a2ensite eg.conf
-------------------------------------------------------------------------------
-+
-(Ubuntu Trusty, Ubuntu Xenial, Debian Jessie):
-+
-[source,bash]
-------------------------------------------------------------------------------
-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:
-+
-[source,bash]
-------------------------------------------------------------------------------
-chown opensrf /var/lock/apache2
-------------------------------------------------------------------------------
-
-Learn more about additional Apache options in the following sections:
-
- * <<_apache_rewrite_tricks,Apache Rewrite Tricks>>
- * <<_apache_access_handler_perl_module,Apache Access Handler Perl Module>>
-
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-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.
-
-[NOTE]
-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,Creating the Evergreen
-database>>, sets the database connection information in `opensrf.xml` for you.
-
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-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,Notifications / Action Triggers>>.
-
-Creating the Evergreen database
--------------------------------
-
-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.
-
-[source, bash]
-------------------------------------------------------------------------------
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-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
-
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-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.
-
-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.
-
-Creating the database on a remote server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In a production instance of Evergreen, your PostgreSQL server should be
-installed on a dedicated server.
-
-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`.
-
-Starting Evergreen
-------------------
-1. As the *root* Linux account, start the `memcached` and `ejabberd` services
-(if they aren't already running):
-+
-[source, bash]
-------------------------------------------------------------------------------
-/etc/init.d/ejabberd start
-/etc/init.d/memcached start
-------------------------------------------------------------------------------
-+
-2. 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.
-+
-[source, bash]
-------------------------------------------------------------------------------
-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:
-+
-[source, bash]
-------------------------------------------------------------------------------
-export PATH=$PATH:/openils/bin
-------------------------------------------------------------------------------
-+
-3. 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.
-):
-+
-[source, bash]
-------------------------------------------------------------------------------
-autogen.sh
-------------------------------------------------------------------------------
-+
-4. As the *root* Linux account, restart the Apache Web server:
-+
-[source, bash]
-------------------------------------------------------------------------------
-/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.
-
-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:
-
-[source, bash]
-------------------------------------------------------------------------------
-/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
- ------------------------------------
-[[install-troubleshooting-1]]
-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 http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[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
- http://evergreen-ils.org/communicate/mailing-lists/[Evergreen development
-mailing list] for assistance before making any drastic changes to your system
- configuration.
-
-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.
-
-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.
--- /dev/null
+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.
+
+Software Prerequisites
+~~~~~~~~~~~~~~~~~~~~~~
+
+ * **PostgreSQL**: Version 9.4 is recommended.
+ The minimum supported version is 9.3.
+ * **Linux**: Evergreen 2.12.0 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.
+
+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:
++
+[source, bash]
+-----------------------------
+osrf_control --localhost --stop-all
+-----------------------------
++
+ .. Back up the /openils directory.
+. Upgrade OpenSRF. Download and install the latest version of OpenSRF from
+the https://evergreen-ils.org/opensrf-downloads/[OpenSRF download page].
+. As the *opensrf* user, download and extract Evergreen 2.12.0:
++
+[source, bash]
+-----------------------------------------------
+wget https://evergreen-ils.org/downloads/Evergreen-ILS-2.12.0.tar.gz
+tar xzf Evergreen-ILS-2.12.0.tar.gz
+-----------------------------------------------
++
+[NOTE]
+For the latest edition of Evergreen, check the https://evergreen-ils.org/egdownloads/[Evergreen download page] and adjust upgrading instructions accordingly.
+
+. As the *root* user, install the prerequisites:
++
+[source, bash]
+---------------------------------------------
+cd /home/opensrf/Evergreen-ILS-2.12.0
+---------------------------------------------
++
+On the next command, replace `[distribution]` with one of these values for your
+distribution of Debian or Ubuntu:
++
+indexterm:[Linux, Debian]
+indexterm:[Linux, Ubuntu]
++
+ * `debian-jessie` for Debian Jessie (8.0) (See https://bugs.launchpad.net/evergreen/+bug/1342227[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 https://bugs.launchpad.net/evergreen/+bug/1342227[Bug 134222] if you want to use EDI)
+
++
+[source, bash]
+------------------------------------------------------------
+make -f Open-ILS/src/extras/Makefile.install [distribution]
+------------------------------------------------------------
++
+. As the *opensrf* user, configure and compile Evergreen:
++
+[source, bash]
+------------------------------------------------------------
+cd /home/opensrf/Evergreen-ILS-2.12.0
+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:
++
+[source, bash]
+------------------------------------------------------------
+cd /home/opensrf/Evergreen-ILS-2.12.0
+make STAFF_CLIENT_STAMP_ID=rel_2_12_rc install
+------------------------------------------------------------
++
+. As the *root* user, change all files to be owned by the opensrf user and group:
++
+[source, bash]
+------------------------------------------------------------
+chown -R opensrf:opensrf /openils
+------------------------------------------------------------
++
+. As the *opensrf* user, update the server symlink in /openils/var/web/xul/:
++
+[source, bash]
+-----------------------------------------------------------
+cd /openils/var/web/xul/
+rm server
+ln -sf rel_2_12_rc/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.
++
+[source, bash]
+----------------------------------------------------------
+cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
+cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
+----------------------------------------------------------
++
+[CAUTION]
+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:
++
+[source, bash]
+-------------------------------------------------------------------------
+cd /home/opensrf/Evergreen-ILS-2.12.0
+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:
++
+indexterm:[Apache]
++
+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:
++
+[CAUTION]
+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_.
++
+[source, bash]
+----------------------------------------------------------
+cp /home/opensrf/Evergreen-ILS-2.12.0/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.
++
+[source, bash]
+----------------------------------------------------------
+cp /home/opensrf/Evergreen-ILS-2.12.0/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.
++
+[source, bash]
+----------------------------------------------------------
+cp /home/opensrf/Evergreen-ILS-2.12.0/Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/eg.conf
+----------------------------------------------------------
+
+Upgrade the Evergreen database schema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[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.
+
+[NOTE]
+=============
+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)
+
+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.0), 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
+
+=============
+
+[CAUTION]
+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 https://evergreen-ils.org/communicate/mailing-lists/[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.
+
+[source, bash]
+----------------------------------------------------------
+cd /home/opensrf/Evergreen-ILS-2.12.0/Open-ILS/src/sql/Pg
+psql -U evergreen -h localhost -f version-upgrade/2.11.3-2.12.0-upgrade-db.sql evergreen
+----------------------------------------------------------
+
+[TIP]
+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.
+
+Restart Evergreen and Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+. As the *root* user, restart memcached to clear out all old user sessions.
++
+[source, bash]
+--------------------------------------------------------------
+service memcached restart
+--------------------------------------------------------------
++
+. As the *opensrf* user, start all Evergreen and OpenSRF services:
++
+[source, bash]
+--------------------------------------------------------------
+osrf_control --localhost --start-all
+--------------------------------------------------------------
++
+. As the *opensrf* user, run autogen to refresh the static organizational data files:
++
+[source, bash]
+--------------------------------------------------------------
+cd /openils/bin
+./autogen.sh
+--------------------------------------------------------------
++
+. Start srfsh and try logging in using your Evergreen username and password:
++
+[source, bash]
+--------------------------------------------------------------
+/openils/bin/srfsh
+srfsh% login username password
+--------------------------------------------------------------
++
+You should see a result like:
++
+[source, bash]
+------------------------------------------------------
+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 <<install-troubleshooting-1,troubleshooting>>.
++
+. As the *root* user, start the Apache web server.
++
+If you encounter errors, refer to the <<install-troubleshooting-1,troubleshooting>> section
+of this documentation for tips on finding solutions and seeking further assistance
+from the Evergreen community.
+
+Review Release Notes
+~~~~~~~~~~~~~~~~~~~~
+
+Review the <<_evergreen_2_12_0_release_notes,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.
+++ /dev/null
-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.
-
-Software Prerequisites
-~~~~~~~~~~~~~~~~~~~~~~
-
- * **PostgreSQL**: Version 9.4 is recommended.
- The minimum supported version is 9.3.
- * **Linux**: Evergreen 2.12.0 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.
-
-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:
-+
-[source, bash]
------------------------------
-osrf_control --localhost --stop-all
------------------------------
-+
- .. Back up the /openils directory.
-. Upgrade OpenSRF. Download and install the latest version of OpenSRF from
-the https://evergreen-ils.org/opensrf-downloads/[OpenSRF download page].
-. As the *opensrf* user, download and extract Evergreen 2.12.0:
-+
-[source, bash]
------------------------------------------------
-wget https://evergreen-ils.org/downloads/Evergreen-ILS-2.12.0.tar.gz
-tar xzf Evergreen-ILS-2.12.0.tar.gz
------------------------------------------------
-+
-[NOTE]
-For the latest edition of Evergreen, check the https://evergreen-ils.org/egdownloads/[Evergreen download page] and adjust upgrading instructions accordingly.
-
-. As the *root* user, install the prerequisites:
-+
-[source, bash]
----------------------------------------------
-cd /home/opensrf/Evergreen-ILS-2.12.0
----------------------------------------------
-+
-On the next command, replace `[distribution]` with one of these values for your
-distribution of Debian or Ubuntu:
-+
-indexterm:[Linux, Debian]
-indexterm:[Linux, Ubuntu]
-+
- * `debian-jessie` for Debian Jessie (8.0) (See https://bugs.launchpad.net/evergreen/+bug/1342227[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 https://bugs.launchpad.net/evergreen/+bug/1342227[Bug 134222] if you want to use EDI)
-
-+
-[source, bash]
-------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install [distribution]
-------------------------------------------------------------
-+
-. As the *opensrf* user, configure and compile Evergreen:
-+
-[source, bash]
-------------------------------------------------------------
-cd /home/opensrf/Evergreen-ILS-2.12.0
-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:
-+
-[source, bash]
-------------------------------------------------------------
-cd /home/opensrf/Evergreen-ILS-2.12.0
-make STAFF_CLIENT_STAMP_ID=rel_2_12_rc install
-------------------------------------------------------------
-+
-. As the *root* user, change all files to be owned by the opensrf user and group:
-+
-[source, bash]
-------------------------------------------------------------
-chown -R opensrf:opensrf /openils
-------------------------------------------------------------
-+
-. As the *opensrf* user, update the server symlink in /openils/var/web/xul/:
-+
-[source, bash]
------------------------------------------------------------
-cd /openils/var/web/xul/
-rm server
-ln -sf rel_2_12_rc/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.
-+
-[source, bash]
-----------------------------------------------------------
-cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
-cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
-----------------------------------------------------------
-+
-[CAUTION]
-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:
-+
-[source, bash]
--------------------------------------------------------------------------
-cd /home/opensrf/Evergreen-ILS-2.12.0
-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:
-+
-indexterm:[Apache]
-+
-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:
-+
-[CAUTION]
-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_.
-+
-[source, bash]
-----------------------------------------------------------
-cp /home/opensrf/Evergreen-ILS-2.12.0/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.
-+
-[source, bash]
-----------------------------------------------------------
-cp /home/opensrf/Evergreen-ILS-2.12.0/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.
-+
-[source, bash]
-----------------------------------------------------------
-cp /home/opensrf/Evergreen-ILS-2.12.0/Open-ILS/examples/apache/eg.conf /etc/apache2/sites-available/eg.conf
-----------------------------------------------------------
-
-Upgrade the Evergreen database schema
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[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.
-
-[NOTE]
-=============
-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)
-
-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.0), 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
-
-=============
-
-[CAUTION]
-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 https://evergreen-ils.org/communicate/mailing-lists/[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.
-
-[source, bash]
-----------------------------------------------------------
-cd /home/opensrf/Evergreen-ILS-2.12.0/Open-ILS/src/sql/Pg
-psql -U evergreen -h localhost -f version-upgrade/2.11.3-2.12.0-upgrade-db.sql evergreen
-----------------------------------------------------------
-
-[TIP]
-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.
-
-Restart Evergreen and Test
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-. As the *root* user, restart memcached to clear out all old user sessions.
-+
-[source, bash]
---------------------------------------------------------------
-service memcached restart
---------------------------------------------------------------
-+
-. As the *opensrf* user, start all Evergreen and OpenSRF services:
-+
-[source, bash]
---------------------------------------------------------------
-osrf_control --localhost --start-all
---------------------------------------------------------------
-+
-. As the *opensrf* user, run autogen to refresh the static organizational data files:
-+
-[source, bash]
---------------------------------------------------------------
-cd /openils/bin
-./autogen.sh
---------------------------------------------------------------
-+
-. Start srfsh and try logging in using your Evergreen username and password:
-+
-[source, bash]
---------------------------------------------------------------
-/openils/bin/srfsh
-srfsh% login username password
---------------------------------------------------------------
-+
-You should see a result like:
-+
-[source, bash]
-------------------------------------------------------
-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 <<install-troubleshooting-1,troubleshooting>>.
-+
-. As the *root* user, start the Apache web server.
-+
-If you encounter errors, refer to the <<install-troubleshooting-1,troubleshooting>> section
-of this documentation for tips on finding solutions and seeking further assistance
-from the Evergreen community.
-
-Review Release Notes
-~~~~~~~~~~~~~~~~~~~~
-
-Review the <<_evergreen_2_12_0_release_notes,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.
--- /dev/null
+Installing the Staff Client
+---------------------------
+
+Installing on Windows
+~~~~~~~~~~~~~~~~~~~~~
+
+anchor:installing_staff_client_on_Windows[]
+
+indexterm:[staff client, installation, Windows]
+
+Official Evergreen releases have corresponding Windows based staff clients ready
+to use.
+
+. Download the staff client from http://www.open-ils.org/downloads.php.
++
+[NOTE]
+===============
+The version of your staff client will
+need to match the version of your Evergreen server. If you are unsure about the
+version of your Evergreen server, contact your system administrator.
+===============
++
+. Click on the downloaded Evergreen setup file.
+. Click _Next_ to begin installation:
++
+image::media/staff_client_installation_0.png[]
++
+. Click _Next_ to accept
+destination folder.
++
+image::media/staff_client_installation_1.png[]
++
+. Click _Install_.
++
+image::media/staff_client_installation_2.png[]
++
+. A pop-up should appear indicating that Evergreen has been installed.
+Click _Finish_ to complete the installation.
+
+image::media/staff_client_installation_3.png[]
+
+When you login to Evergreen from the workstation for the first time, you will
+also need to <<register_workstation,register your workstation>>.
+
+Installing on Linux
+~~~~~~~~~~~~~~~~~~~
+
+indexterm:[staff client, installation, Linux]
+
+. On the Evergreen *server*, navigate to the `staff_client` directory inside
+ the Evergreen source:
++
+[source, bash]
+--------
+cd /path/to/Evergreen/Open-ILS/xul/staff_client
+--------
++
+. As the *root* user, build release versions of staff clients for both
+ 32-bit and 64-bit Linux systems:
++
+[source, bash]
+--------
+make rigrelease rebuild linux32-updates-client linux64-updates-client
+make install
+--------
++
+This builds and copies two staff client tarballs for Linux to the `updates`
+directory on the Web server.
++
+. As the *root* user, reset the ownership of the Evergreen install directory
+ to the *opensrf* user. For example, if your install directory is `/openils`:
++
+[source, bash]
+--------
+chown -R opensrf:opensrf /openils
+--------
++
+. On your staff client workstation, download the 32-bit or 64-bit version of
+ the staff client from your Web server at
+ http://hostname/updates/manualupdate.html (where _hostname_ represents the
+ hostname of your Web server).
+. On your staff client workstation, create a directory with the name of your
+ staff client and version.
+. Extract the tar files into that directory.
+. Within the directory, click on the `evergreen` file to start the program.
++
+Or, you can run the program from a terminal (command line). For example, if the
+staff client files were extracted to a directory called `evergreen_client` in
+your home directory, you can run it with:
++
+[source, bash]
+--------
+~/evergreen_client/evergreen
+--------
+
+Registering a Workstation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+anchor:register_workstation[]
+
+
+indexterm:[staff client, registering a workstation]
+
+Before you can connect to Evergreen from your staff client, you will need to
+register your workstation when you try to login.
+
+[NOTE]
+===============
+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, a red box will appear around your workstation
+information on the right side of the screen.
++
+image::media/staff_client_installation_4.png[]
++
+. Create a unique workstation name or use the default computer name provided.
+. Click _Register_
+. You will now be able to log into the system.
+
+Removing Staff Client Preferences
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+indexterm:[staff client, removing user preferences]
+indexterm:[staff client, removing user settings]
+
+Windows
+^^^^^^^
+
+When you uninstall the Evergreen staff client code from your system, the staff
+client preferences and cached data are not removed from your system. This can
+be a problem if, for example, you have registered your workstation with the
+wrong library; or if you have chosen a display language (locale) that is broken
+and will not let you start up the client again
+
+On Windows, you can uninstall the Evergreen staff client code using the
+Add/Remove Programs menu.
+
+To remove the staff client preferences and cached data entirely on Windows,
+there are two directories that you must delete completely (where _<profile>_
+represents your user profile name):
+
+* *C:\Documents and Settings\<profile>\Application Data\OpenILS*
+* *C:\Documents and Settings\<profile>\Local Settings\Application Data\OpenILS*
+
+You might need to change the preferences in Windows Explorer to display hidden
+files (Tools -> Folder Options… -> View).
+
+Linux
+^^^^^
+
+To remove the staff client preferences and cached data from your user account
+on Linux, there is one directory that you must delete completely:
+
+[source, bash]
+----------
+rm -fr ~/.openils
+----------
+
+++ /dev/null
-Installing the Staff Client
----------------------------
-
-Installing on Windows
-~~~~~~~~~~~~~~~~~~~~~
-
-anchor:installing_staff_client_on_Windows[]
-
-indexterm:[staff client, installation, Windows]
-
-Official Evergreen releases have corresponding Windows based staff clients ready
-to use.
-
-. Download the staff client from http://www.open-ils.org/downloads.php.
-+
-[NOTE]
-===============
-The version of your staff client will
-need to match the version of your Evergreen server. If you are unsure about the
-version of your Evergreen server, contact your system administrator.
-===============
-+
-. Click on the downloaded Evergreen setup file.
-. Click _Next_ to begin installation:
-+
-image::media/staff_client_installation_0.png[]
-+
-. Click _Next_ to accept
-destination folder.
-+
-image::media/staff_client_installation_1.png[]
-+
-. Click _Install_.
-+
-image::media/staff_client_installation_2.png[]
-+
-. A pop-up should appear indicating that Evergreen has been installed.
-Click _Finish_ to complete the installation.
-
-image::media/staff_client_installation_3.png[]
-
-When you login to Evergreen from the workstation for the first time, you will
-also need to <<register_workstation,register your workstation>>.
-
-Installing on Linux
-~~~~~~~~~~~~~~~~~~~
-
-indexterm:[staff client, installation, Linux]
-
-. On the Evergreen *server*, navigate to the `staff_client` directory inside
- the Evergreen source:
-+
-[source, bash]
---------
-cd /path/to/Evergreen/Open-ILS/xul/staff_client
---------
-+
-. As the *root* user, build release versions of staff clients for both
- 32-bit and 64-bit Linux systems:
-+
-[source, bash]
---------
-make rigrelease rebuild linux32-updates-client linux64-updates-client
-make install
---------
-+
-This builds and copies two staff client tarballs for Linux to the `updates`
-directory on the Web server.
-+
-. As the *root* user, reset the ownership of the Evergreen install directory
- to the *opensrf* user. For example, if your install directory is `/openils`:
-+
-[source, bash]
---------
-chown -R opensrf:opensrf /openils
---------
-+
-. On your staff client workstation, download the 32-bit or 64-bit version of
- the staff client from your Web server at
- http://hostname/updates/manualupdate.html (where _hostname_ represents the
- hostname of your Web server).
-. On your staff client workstation, create a directory with the name of your
- staff client and version.
-. Extract the tar files into that directory.
-. Within the directory, click on the `evergreen` file to start the program.
-+
-Or, you can run the program from a terminal (command line). For example, if the
-staff client files were extracted to a directory called `evergreen_client` in
-your home directory, you can run it with:
-+
-[source, bash]
---------
-~/evergreen_client/evergreen
---------
-
-Registering a Workstation
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-anchor:register_workstation[]
-
-
-indexterm:[staff client, registering a workstation]
-
-Before you can connect to Evergreen from your staff client, you will need to
-register your workstation when you try to login.
-
-[NOTE]
-===============
-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, a red box will appear around your workstation
-information on the right side of the screen.
-+
-image::media/staff_client_installation_4.png[]
-+
-. Create a unique workstation name or use the default computer name provided.
-. Click _Register_
-. You will now be able to log into the system.
-
-Removing Staff Client Preferences
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-indexterm:[staff client, removing user preferences]
-indexterm:[staff client, removing user settings]
-
-Windows
-^^^^^^^
-
-When you uninstall the Evergreen staff client code from your system, the staff
-client preferences and cached data are not removed from your system. This can
-be a problem if, for example, you have registered your workstation with the
-wrong library; or if you have chosen a display language (locale) that is broken
-and will not let you start up the client again
-
-On Windows, you can uninstall the Evergreen staff client code using the
-Add/Remove Programs menu.
-
-To remove the staff client preferences and cached data entirely on Windows,
-there are two directories that you must delete completely (where _<profile>_
-represents your user profile name):
-
-* *C:\Documents and Settings\<profile>\Application Data\OpenILS*
-* *C:\Documents and Settings\<profile>\Local Settings\Application Data\OpenILS*
-
-You might need to change the preferences in Windows Explorer to display hidden
-files (Tools -> Folder Options… -> View).
-
-Linux
-^^^^^
-
-To remove the staff client preferences and cached data from your user account
-on Linux, there is one directory that you must delete completely:
-
-[source, bash]
-----------
-rm -fr ~/.openils
-----------
-
--- /dev/null
+System Requirements
+-------------------
+
+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.
+
+Web Client Requirements
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The current stable release of Firefox or Chrome is required to run the web
+client in a browser.
+
+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.
+++ /dev/null
-System Requirements
--------------------
-
-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.
-
-Web Client Requirements
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The current stable release of Firefox or Chrome is required to run the web
-client in a browser.
-
-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.
--- /dev/null
+[[licensing]]
+[appendix]
+Licensing
+=========
+
+image::media/ccbysa.png["CC-BY-SA",link="http://creativecommons.org/licenses/by-sa/3.0/"]
+
+This work is licensed under a
+link:http://creativecommons.org/licenses/by-sa/3.0/[Creative
+Commons Attribution-ShareAlike 3.0 Unported License].
+
+
+++ /dev/null
-[[licensing]]
-[appendix]
-Licensing
-=========
-
-image::media/ccbysa.png["CC-BY-SA",link="http://creativecommons.org/licenses/by-sa/3.0/"]
-
-This work is licensed under a
-link:http://creativecommons.org/licenses/by-sa/3.0/[Creative
-Commons Attribution-ShareAlike 3.0 Unported License].
-
-
--- /dev/null
+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.
+
+
+Use the Catalog to Retrieve Records with Specified Date Ranges:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+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)
+
+
+
+
+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)
+
+
+
+
+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
+
+
+
+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
+
+
+NOTE: To retrieve deleted records, replace the # with %23 in your URL.
+
+
+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.
+
+
+
+
+
+++ /dev/null
-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.
-
-
-Use the Catalog to Retrieve Records with Specified Date Ranges:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-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)
-
-
-
-
-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)
-
-
-
-
-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
-
-
-
-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
-
-
-NOTE: To retrieve deleted records, replace the # with %23 in your URL.
-
-
-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.
-
-
-
-
-
--- /dev/null
+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*.
+
+++ /dev/null
-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*.
-
--- /dev/null
+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.
+
+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.
+
+image::media/Kids_OPAC1.jpg[Kids_OPAC1]
+
+*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.
+
+image::media/Kids_OPAC2.jpg[Kids_OPAC2]
+
+
+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.
+
+
+image::media/Kids_OPAC4.jpg[Kids_OPAC4]
+
+
+You can add multiple layers of icons and searches to your grid:
+
+
+image::media/Kids_OPAC5.jpg[Kids_OPAC5]
+
+
+
+*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.
+
+
+image::media/Kids_OPAC17.jpg[Kids_OPAC17]
+
+
+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.
+
+
+image::media/Kids_OPAC6.jpg[Kids_OPAC6]
+
+
+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.
+
+
+image::media/Kids_OPAC7.jpg[Kids_OPAC7]
+
+
+
+Place a Hold
+~~~~~~~~~~~~
+
+From the search results, click the *Get it!* link to place a hold.
+
+
+image::media/Kids_OPAC11.jpg[Kids_OPAC11]
+
+
+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*.
+
+
+image::media/Kids_OPAC12.jpg[Kids_OPAC12]
+
+
+A confirmation of hold placement appears. You can return to the previous record
+or to your search results.
+
+
+image::media/Kids_OPAC13.jpg[Kids_OPAC13]
+
+
+
+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.
+
+
+image::media/Kids_OPAC14.jpg[Kids_OPAC14]
+
+
+Select a list in the *Save It!* panel beneath the brief information, and click *Submit*.
+
+
+image::media/Kids_OPAC16.jpg[Kids_OPAC16]
+
+
+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.
+
+
+image::media/Kids_OPAC15.jpg[Kids_OPAC15]
+
+
+
+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.
+
+image::media/Kids_OPAC8.jpg[Kids_OPAC8]
+
+
+Click the Reviews link to view reader reviews from a third party source. The reader
+reviews open beneath the brief information.
+
+
+image::media/Kids_OPAC9.jpg[Kids_OPAC9]
+
+
+Summaries and reviews from other publications appear in separate tabs beneath the
+copy information.
+
+
+image::media/Kids_OPAC10.jpg[Kids_OPAC10]
+
+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.
+++ /dev/null
-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.
-
-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.
-
-image::media/Kids_OPAC1.jpg[Kids_OPAC1]
-
-*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.
-
-image::media/Kids_OPAC2.jpg[Kids_OPAC2]
-
-
-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.
-
-
-image::media/Kids_OPAC4.jpg[Kids_OPAC4]
-
-
-You can add multiple layers of icons and searches to your grid:
-
-
-image::media/Kids_OPAC5.jpg[Kids_OPAC5]
-
-
-
-*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.
-
-
-image::media/Kids_OPAC17.jpg[Kids_OPAC17]
-
-
-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.
-
-
-image::media/Kids_OPAC6.jpg[Kids_OPAC6]
-
-
-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.
-
-
-image::media/Kids_OPAC7.jpg[Kids_OPAC7]
-
-
-
-Place a Hold
-~~~~~~~~~~~~
-
-From the search results, click the *Get it!* link to place a hold.
-
-
-image::media/Kids_OPAC11.jpg[Kids_OPAC11]
-
-
-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*.
-
-
-image::media/Kids_OPAC12.jpg[Kids_OPAC12]
-
-
-A confirmation of hold placement appears. You can return to the previous record
-or to your search results.
-
-
-image::media/Kids_OPAC13.jpg[Kids_OPAC13]
-
-
-
-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.
-
-
-image::media/Kids_OPAC14.jpg[Kids_OPAC14]
-
-
-Select a list in the *Save It!* panel beneath the brief information, and click *Submit*.
-
-
-image::media/Kids_OPAC16.jpg[Kids_OPAC16]
-
-
-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.
-
-
-image::media/Kids_OPAC15.jpg[Kids_OPAC15]
-
-
-
-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.
-
-image::media/Kids_OPAC8.jpg[Kids_OPAC8]
-
-
-Click the Reviews link to view reader reviews from a third party source. The reader
-reviews open beneath the brief information.
-
-
-image::media/Kids_OPAC9.jpg[Kids_OPAC9]
-
-
-Summaries and reviews from other publications appear in separate tabs beneath the
-copy information.
-
-
-image::media/Kids_OPAC10.jpg[Kids_OPAC10]
-
-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.
--- /dev/null
+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.
+[NOTE]
+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.
+++ /dev/null
-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.
-[NOTE]
-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.
--- /dev/null
+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.
+
+image::media/My_Lists.png[My Lists]
+
+*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*.
+
+image::media/My_Lists1.jpg[My_Lists1]
+
+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.
+
+image::media/My_Lists3.jpg[My_Lists3]
+
+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.
+
+image::media/My_Lists4.jpg[My_Lists4]
+
+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.
+
+image::media/My_Lists5.jpg[My_Lists5]
+
+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*.
+
+image::media/My_Lists6.jpg[My_Lists6]
+
+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*.
+
+image::media/My_Lists7.jpg[My_Lists7]
+
+
+16) When you no longer need a list, click *Delete List*.
+
+
+*Local Call Number in My Lists*
+
+As of Evergreen version 2.4, 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:
+
+image::media/my_list_call_numbers.png[Local Call Number in List]
+++ /dev/null
-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.
-
-image::media/My_Lists.png[My Lists]
-
-*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*.
-
-image::media/My_Lists1.jpg[My_Lists1]
-
-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.
-
-image::media/My_Lists3.jpg[My_Lists3]
-
-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.
-
-image::media/My_Lists4.jpg[My_Lists4]
-
-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.
-
-image::media/My_Lists5.jpg[My_Lists5]
-
-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*.
-
-image::media/My_Lists6.jpg[My_Lists6]
-
-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*.
-
-image::media/My_Lists7.jpg[My_Lists7]
-
-
-16) When you no longer need a list, click *Delete List*.
-
-
-*Local Call Number in My Lists*
-
-As of Evergreen version 2.4, 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:
-
-image::media/my_list_call_numbers.png[Local Call Number in List]
--- /dev/null
+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.
+
+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
+------------------------------------------------------------------------------
+
+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.
+
+NOTE: 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.
+* `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
+ http://evergreen-ils.org[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.
+* `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 http://goo.gl/WfNkE[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>
+------------------------------------------------------------------------------
+
+++ /dev/null
-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.
-
-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
-------------------------------------------------------------------------------
-
-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.
-
-NOTE: 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.
-* `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
- http://evergreen-ils.org[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.
-* `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 http://goo.gl/WfNkE[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>
-------------------------------------------------------------------------------
-
--- /dev/null
+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
+http://www.opensearch.org[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.
++
+image::media/opensearch1.png[opensearch1]
+
+. 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).
++
+image::media/opensearch2.png[opensearch2]
+
+. 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.
++
+image::media/opensearch3.png[opensearch3]
+
+. You can select which search source to use by clicking on the dropdown
+ picker.
++
+image::media/opensearch4.png[opensearch4]
+++ /dev/null
-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
-http://www.opensearch.org[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.
-+
-image::media/opensearch1.png[opensearch1]
-
-. 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).
-+
-image::media/opensearch2.png[opensearch2]
-
-. 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.
-+
-image::media/opensearch3.png[opensearch3]
-
-. You can select which search source to use by clicking on the dropdown
- picker.
-+
-image::media/opensearch4.png[opensearch4]
--- /dev/null
+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:
+
+Simple search form
+------------------
+
+[source,html]
+------------------------------------------------------------------------------
+<form action="http://example.com/eg/opac/results" method="get" accept-charset="UTF-8"> <!-- <1> -->
+ <input type="search" alt="Catalog Search" maxlength="200"
+ size="20" name="query"
+ placeholder="Search catalog for..." />
+ <input type="hidden" name="qtype" value="keyword" /> <!-- <2> -->
+ <input type="hidden" name="locg" value="4" /> <!-- <3> -->
+ <input type="submit" value="Search" />
+</form>
+------------------------------------------------------------------------------
+<1> Replace ''example.com'' with the hostname for your catalog. To link to
+ the Kid's OPAC instead of the TPAC, replace ''opac'' with ''kpac''.
+<2> 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.
+<3> 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.
+
+Advanced search form
+--------------------
+
+[source,html]
+--------------------------------------------------------------------------------
+<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>
+
+ <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>
+ </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">
+ Central Library
+ </option>
+ <option value='10' class="org_unit">
+ Little Library
+ </option>
+ </select>
+ </label>
+ <input class="searchbutton" type="submit" value="SEarch" />
+</form>
+--------------------------------------------------------------------------------
+
+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.
+
+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. https://www.loc.gov/marc/bibliographic/bdleader.html[Leader, position 06]).
+
+For example, for musical recordings you could use `<option value='j'>Musical Sound Recording</option>`
+
+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.
+
+
+++ /dev/null
-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:
-
-Simple search form
-------------------
-
-[source,html]
-------------------------------------------------------------------------------
-<form action="http://example.com/eg/opac/results" method="get" accept-charset="UTF-8"> <!-- <1> -->
- <input type="search" alt="Catalog Search" maxlength="200"
- size="20" name="query"
- placeholder="Search catalog for..." />
- <input type="hidden" name="qtype" value="keyword" /> <!-- <2> -->
- <input type="hidden" name="locg" value="4" /> <!-- <3> -->
- <input type="submit" value="Search" />
-</form>
-------------------------------------------------------------------------------
-<1> Replace ''example.com'' with the hostname for your catalog. To link to
- the Kid's OPAC instead of the TPAC, replace ''opac'' with ''kpac''.
-<2> 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.
-<3> 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.
-
-Advanced search form
---------------------
-
-[source,html]
---------------------------------------------------------------------------------
-<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>
-
- <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>
- </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">
- Central Library
- </option>
- <option value='10' class="org_unit">
- Little Library
- </option>
- </select>
- </label>
- <input class="searchbutton" type="submit" value="SEarch" />
-</form>
---------------------------------------------------------------------------------
-
-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.
-
-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. https://www.loc.gov/marc/bibliographic/bdleader.html[Leader, position 06]).
-
-For example, for musical recordings you could use `<option value='j'>Musical Sound Recording</option>`
-
-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.
-
-
--- /dev/null
+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.
+
+image::media/advsrchpg_1.jpg[]
+
+*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.
+
+image::media/srchresultpg_2.jpg[]
+
+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.
+
+image::media/srchresultpg2_3.jpg[]
+
+For the metarecord search result, the *Place Hold* link defaults to a metarecord level hold.
+
+image::media/srchresultpg3_4.jpg[]
+
+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*.
+
+image::media/placehold_5.jpg[]
+
+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.
+
+image::media/advholdoption_6.jpg[]
+
+*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.
+
+image::media/srchresultpg4_7.jpg[]
+
+This will allow the user to view the results for grouped records.
+
+image::media/recorddetailpg_8.jpg[]
+
+*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.
+
+image::media/mrholdgf_9.jpg[]
+
+
+++ /dev/null
-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.
-
-image::media/advsrchpg_1.jpg[]
-
-*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.
-
-image::media/srchresultpg_2.jpg[]
-
-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.
-
-image::media/srchresultpg2_3.jpg[]
-
-For the metarecord search result, the *Place Hold* link defaults to a metarecord level hold.
-
-image::media/srchresultpg3_4.jpg[]
-
-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*.
-
-image::media/placehold_5.jpg[]
-
-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.
-
-image::media/advholdoption_6.jpg[]
-
-*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.
-
-image::media/srchresultpg4_7.jpg[]
-
-This will allow the user to view the results for grouped records.
-
-image::media/recorddetailpg_8.jpg[]
-
-*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.
-
-image::media/mrholdgf_9.jpg[]
-
-
--- /dev/null
+Using the Public Access Catalog
+-------------------------------
+
+Basic Search
+~~~~~~~~~~~~
+
+indexterm:[OPAC]
+
+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.
+
+indexterm:[search box]
+
+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:
+
+indexterm:[search, keyword]
+indexterm:[search, title]
+indexterm:[search, journal title]
+indexterm:[search, author]
+indexterm:[search, subject]
+indexterm:[search, series]
+indexterm:[search, bib call number]
+
+* *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.
+
+[TIP]
+=============
+To search an item copy call number, use <<numeric_search, _Advanced Search: Numeric_>>
+=============
+
+Formats
+^^^^^^^
+
+You can limit your search by formats based on MARC fixed field type:
+
+indexterm:[formats, books]
+indexterm:[formats, audiobooks]
+indexterm:[formats, video]
+indexterm:[formats, music]
+
+
+* *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*
+
+
+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.
+
+
+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.
+
+
+Sort Results
+^^^^^^^^^^^^
+
+indexterm:[advanced search, sort results]
+
+By default, the search results are in order of greatest to least relevance, see <<order_of_results, Order of Results>>. In the sort results menu you may select to order the search results by relevance, title, author, or publication date.
+
+
+Search Library
+^^^^^^^^^^^^^^
+
+indexterm:[advanced search, 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.
+
+
+Limit to Available
+^^^^^^^^^^^^^^^^^^
+
+indexterm:[advanced search, 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_).
+
+Exclude Electronic Resources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[advanced search, 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.
+
+[TIP]
+===============
+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.
+===============
+
+
+Search Filter
+^^^^^^^^^^^^^
+
+indexterm:[advanced search, search filters]
+
+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.
+
+
+anchor:numeric_search[]
+indexterm:[advanced search, numeric search]
+
+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.
+
+Expert Search
+^^^^^^^^^^^^^
+
+indexterm:[advanced search, 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.
+
+[TIP]
+=============
+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".
+=============
+
+Boolean operators
+~~~~~~~~~~~~~~~~~
+
+indexterm:[search, AND operator]
+indexterm:[search, OR operator]
+indexterm:[search, NOT operator]
+indexterm:[search, boolean]
+
+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:
+
+.Boolean symbolic operators
+[width="50%",options="header"]
+|=================================
+| Operator | Symbol | Example
+| AND | `&&` | `a && b`
+| OR | `\|\|` | `a \|\| b`
+| NOT | `-`_term_ | `a -b`
+|=================================
+
+Search Tips
+~~~~~~~~~~~
+
+indexterm:[search, stop words]
+indexterm:[search, truncation]
+
+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_)
+
+
+Search Methodology
+~~~~~~~~~~~~~~~~~~
+
+anchor:stemming[]
+
+Stemming
+^^^^^^^^
+
+indexterm:[search, 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_.
+
+
+anchor:order_of_results[]
+
+Order of Results
+^^^^^^^^^^^^^^^^
+
+indexterm:[search, 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.
+
+
+Search URL
+~~~~~~~~~~
+
+indexterm:[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]
+
+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.
+
+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.
+
+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.
+
+
+Search Results
+~~~~~~~~~~~~~~
+
+indexterm:[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:
+
+
+image::media/catalogue-3.png[catalogue-3]
+
+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.
+
+
+Facets: Subjects, Authors, and Series
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[search results, 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 done 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.
+
+image::media/catalogue-5.png[catalogue-5]
+
+
+Availability
+^^^^^^^^^^^^
+
+indexterm:[search results, 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.
+
+
+image::media/catalogue-6.png[catalogue-6]
+
+image::media/catalogue-7.png[catalogue-7]
+
+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.
+
+
+Viewing a record
+^^^^^^^^^^^^^^^^
+
+indexterm:[search results, 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.
+
+image::media/catalogue-8.png[catalogue-8]
+image::media/catalogue-8a.png[catalogue-8a]
+
+Details
+~~~~~~~
+
+The record shows details such as the cover image, title, author, publication information, and an abstract or summary, if available.
+
+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.
+
+[NOTE]
+==========
+Copies are sorted by (in order): org unit, call number, part label, copy number, and barcode.
+==========
+
+
+
+Placing Holds
+^^^^^^^^^^^^^
+
+indexterm:[search results, 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,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.
+
+
+image::media/catalogue-9.png[catalogue-9]
+
+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.
+
+image::media/using-opac-view-permalink.png[Permalink]
+
+
+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.
+
+image::media/textcn1.png[]
+
+See the *<<Sending_Copy_Details_via_Text_Message, Sending Copy Details via Text Message>>* section of the documentation for more information on how to use this feature.
+
+[WARNING]
+==========
+Carrier charges may apply when using the SMS call number feature.
+==========
+
+Details
+^^^^^^^
+
+indexterm:[search results, details]
+
+The record shows details such as the cover image, title, author, publication information, and an abstract or summary, if available.
+
+Near the bottom of the record, the copy summary 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 _Shelving Location_ for locating the item on the shelves. You can click _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 _Table of Contents_ to see the book’s table of contents online (if available). You can select _MARC Record_ to display the record in MARC format. You can also select _Awards, Reviews, & Suggested Reads_ and _Additional Content_ to see more details (if available).
+
+
+Going back
+^^^^^^^^^^
+
+indexterm:[search results, 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.
+
+image::media/catalogue-10.png[catalogue-10]
+
+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.
+
+anchor:my_account[]
+
+
+My Account
+~~~~~~~~~~
+
+// ``First Login Password Update'' the following documentation comes from JSPAC
+// as of 2013-03-12 this feature did not exist in EG 2.4 TPAC,
+// so I am commenting it out for now because it will be added in the future
+// see bug report https://bugs.launchpad.net/evergreen/+bug/1013786
+// Yamil Suarez 2013-03-12
+
+////
+
+
+First Login Password Update
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+indexterm:[my account, first login password update]
+
+Patrons are given temporary passwords when new accounts are created, or forgotten passwords are reset by staff. Patrons MUST change their password to something more secure when they login or for the first time. Once the password is updated, they will not have to repeat this process for subsequent logins.
+
+. Open a web browser and go 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 library to have it reset or use the online the section called ``<<password_reset,Password Reset>>'' tool.
+////
+
+
+Logging In
+^^^^^^^^^^
+
+indexterm:[my account, 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, 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_!
+
+[CAUTION]
+=================
+If using a public computer be sure to log out!
+=================
+
+anchor:password_reset[]
+
+Password Reset
+^^^^^^^^^^^^^^
+
+indexterm:[my account, 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.
++
+[NOTE]
+=================
+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.
+
+
+Account Summary
+^^^^^^^^^^^^^^^
+
+indexterm:[my account, 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.
+
+
+Items Checked Out
+^^^^^^^^^^^^^^^^^
+
+indexterm:[my account, 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_
+
+
+Holds
+^^^^^
+
+indexterm:[my account, 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.
+
+
+Account Preferences
+^^^^^^^^^^^^^^^^^^^
+
+indexterm:[my account, 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?
+
+
+After changing any of these settings, you must click _Save_ to store your preferences.
+
+
+indexterm:[holds, preferred pickup location]
+
+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.
+
+image::media/message_center11.PNG[Message Center 11]
+
+Patrons will see a list of the messages from the library by clicking on the *Messages* tab.
+
+image::media/message_center10.PNG[Message Center 10]
+
+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.
+
+image::media/message_center12.PNG[Message Center 12]
+
+NOTE: Patron deleted messages will still appear in the patron's account in the staff client under Other -> Message Center.
+++ /dev/null
-Using the Public Access Catalog
--------------------------------
-
-Basic Search
-~~~~~~~~~~~~
-
-indexterm:[OPAC]
-
-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.
-
-indexterm:[search box]
-
-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:
-
-indexterm:[search, keyword]
-indexterm:[search, title]
-indexterm:[search, journal title]
-indexterm:[search, author]
-indexterm:[search, subject]
-indexterm:[search, series]
-indexterm:[search, bib call number]
-
-* *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.
-
-[TIP]
-=============
-To search an item copy call number, use <<numeric_search, _Advanced Search: Numeric_>>
-=============
-
-Formats
-^^^^^^^
-
-You can limit your search by formats based on MARC fixed field type:
-
-indexterm:[formats, books]
-indexterm:[formats, audiobooks]
-indexterm:[formats, video]
-indexterm:[formats, music]
-
-
-* *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*
-
-
-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.
-
-
-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.
-
-
-Sort Results
-^^^^^^^^^^^^
-
-indexterm:[advanced search, sort results]
-
-By default, the search results are in order of greatest to least relevance, see <<order_of_results, Order of Results>>. In the sort results menu you may select to order the search results by relevance, title, author, or publication date.
-
-
-Search Library
-^^^^^^^^^^^^^^
-
-indexterm:[advanced search, 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.
-
-
-Limit to Available
-^^^^^^^^^^^^^^^^^^
-
-indexterm:[advanced search, 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_).
-
-Exclude Electronic Resources
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[advanced search, 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.
-
-[TIP]
-===============
-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.
-===============
-
-
-Search Filter
-^^^^^^^^^^^^^
-
-indexterm:[advanced search, search filters]
-
-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.
-
-
-anchor:numeric_search[]
-indexterm:[advanced search, numeric search]
-
-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.
-
-Expert Search
-^^^^^^^^^^^^^
-
-indexterm:[advanced search, 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.
-
-[TIP]
-=============
-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".
-=============
-
-Boolean operators
-~~~~~~~~~~~~~~~~~
-
-indexterm:[search, AND operator]
-indexterm:[search, OR operator]
-indexterm:[search, NOT operator]
-indexterm:[search, boolean]
-
-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:
-
-.Boolean symbolic operators
-[width="50%",options="header"]
-|=================================
-| Operator | Symbol | Example
-| AND | `&&` | `a && b`
-| OR | `\|\|` | `a \|\| b`
-| NOT | `-`_term_ | `a -b`
-|=================================
-
-Search Tips
-~~~~~~~~~~~
-
-indexterm:[search, stop words]
-indexterm:[search, truncation]
-
-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_)
-
-
-Search Methodology
-~~~~~~~~~~~~~~~~~~
-
-anchor:stemming[]
-
-Stemming
-^^^^^^^^
-
-indexterm:[search, 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_.
-
-
-anchor:order_of_results[]
-
-Order of Results
-^^^^^^^^^^^^^^^^
-
-indexterm:[search, 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.
-
-
-Search URL
-~~~~~~~~~~
-
-indexterm:[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]
-
-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.
-
-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.
-
-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.
-
-
-Search Results
-~~~~~~~~~~~~~~
-
-indexterm:[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:
-
-
-image::media/catalogue-3.png[catalogue-3]
-
-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.
-
-
-Facets: Subjects, Authors, and Series
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[search results, 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 done 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.
-
-image::media/catalogue-5.png[catalogue-5]
-
-
-Availability
-^^^^^^^^^^^^
-
-indexterm:[search results, 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.
-
-
-image::media/catalogue-6.png[catalogue-6]
-
-image::media/catalogue-7.png[catalogue-7]
-
-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.
-
-
-Viewing a record
-^^^^^^^^^^^^^^^^
-
-indexterm:[search results, 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.
-
-image::media/catalogue-8.png[catalogue-8]
-image::media/catalogue-8a.png[catalogue-8a]
-
-Details
-~~~~~~~
-
-The record shows details such as the cover image, title, author, publication information, and an abstract or summary, if available.
-
-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.
-
-[NOTE]
-==========
-Copies are sorted by (in order): org unit, call number, part label, copy number, and barcode.
-==========
-
-
-
-Placing Holds
-^^^^^^^^^^^^^
-
-indexterm:[search results, 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,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.
-
-
-image::media/catalogue-9.png[catalogue-9]
-
-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.
-
-image::media/using-opac-view-permalink.png[Permalink]
-
-
-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.
-
-image::media/textcn1.png[]
-
-See the *<<Sending_Copy_Details_via_Text_Message, Sending Copy Details via Text Message>>* section of the documentation for more information on how to use this feature.
-
-[WARNING]
-==========
-Carrier charges may apply when using the SMS call number feature.
-==========
-
-Details
-^^^^^^^
-
-indexterm:[search results, details]
-
-The record shows details such as the cover image, title, author, publication information, and an abstract or summary, if available.
-
-Near the bottom of the record, the copy summary 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 _Shelving Location_ for locating the item on the shelves. You can click _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 _Table of Contents_ to see the book’s table of contents online (if available). You can select _MARC Record_ to display the record in MARC format. You can also select _Awards, Reviews, & Suggested Reads_ and _Additional Content_ to see more details (if available).
-
-
-Going back
-^^^^^^^^^^
-
-indexterm:[search results, 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.
-
-image::media/catalogue-10.png[catalogue-10]
-
-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.
-
-anchor:my_account[]
-
-
-My Account
-~~~~~~~~~~
-
-// ``First Login Password Update'' the following documentation comes from JSPAC
-// as of 2013-03-12 this feature did not exist in EG 2.4 TPAC,
-// so I am commenting it out for now because it will be added in the future
-// see bug report https://bugs.launchpad.net/evergreen/+bug/1013786
-// Yamil Suarez 2013-03-12
-
-////
-
-
-First Login Password Update
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-indexterm:[my account, first login password update]
-
-Patrons are given temporary passwords when new accounts are created, or forgotten passwords are reset by staff. Patrons MUST change their password to something more secure when they login or for the first time. Once the password is updated, they will not have to repeat this process for subsequent logins.
-
-. Open a web browser and go 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 library to have it reset or use the online the section called ``<<password_reset,Password Reset>>'' tool.
-////
-
-
-Logging In
-^^^^^^^^^^
-
-indexterm:[my account, 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, 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_!
-
-[CAUTION]
-=================
-If using a public computer be sure to log out!
-=================
-
-anchor:password_reset[]
-
-Password Reset
-^^^^^^^^^^^^^^
-
-indexterm:[my account, 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.
-+
-[NOTE]
-=================
-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.
-
-
-Account Summary
-^^^^^^^^^^^^^^^
-
-indexterm:[my account, 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.
-
-
-Items Checked Out
-^^^^^^^^^^^^^^^^^
-
-indexterm:[my account, 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_
-
-
-Holds
-^^^^^
-
-indexterm:[my account, 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.
-
-
-Account Preferences
-^^^^^^^^^^^^^^^^^^^
-
-indexterm:[my account, 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?
-
-
-After changing any of these settings, you must click _Save_ to store your preferences.
-
-
-indexterm:[holds, preferred pickup location]
-
-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.
-
-image::media/message_center11.PNG[Message Center 11]
-
-Patrons will see a list of the messages from the library by clicking on the *Messages* tab.
-
-image::media/message_center10.PNG[Message Center 10]
-
-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.
-
-image::media/message_center12.PNG[Message Center 12]
-
-NOTE: Patron deleted messages will still appear in the patron's account in the staff client under Other -> Message Center.
--- /dev/null
+Adding Data Sources to Reporter
+-------------------------------
+
+indexterm:[reports, adding data sources]
+
+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.
+
+indexterm:[fm_IDL.xml]
+
+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:
+
+indexterm:[PostgreSQL]
+
+indexterm:[SQL]
+
+* 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.
+
+Create a PostgreSQL query, view, or table for your data source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[PostgreSQL]
+
+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
+http://http://www.postgresql.org/docs/[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
+http://docs.evergreen-ils.org/2.2/schema/[Evergreen schema]
+
+indexterm:[database 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';
+-----------
+
+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_.
+
+indexterm:[fm_IDL.xml]
+indexterm:[fieldmapper]
+indexterm:[report sources]
+
+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>
+---------
+
+NOTE: _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.
+
+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*
+
+++ /dev/null
-Adding Data Sources to Reporter
--------------------------------
-
-indexterm:[reports, adding data sources]
-
-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.
-
-indexterm:[fm_IDL.xml]
-
-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:
-
-indexterm:[PostgreSQL]
-
-indexterm:[SQL]
-
-* 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.
-
-Create a PostgreSQL query, view, or table for your data source
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[PostgreSQL]
-
-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
-http://http://www.postgresql.org/docs/[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
-http://docs.evergreen-ils.org/2.2/schema/[Evergreen schema]
-
-indexterm:[database 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';
------------
-
-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_.
-
-indexterm:[fm_IDL.xml]
-indexterm:[fieldmapper]
-indexterm:[report sources]
-
-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>
----------
-
-NOTE: _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.
-
-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*
-
--- /dev/null
+Cloning Shared Templates
+------------------------
+
+indexterm:[reports, cloning]
+
+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 <<reporter_creating_folders,Creating Folders>>.
+
+. Access the reports interface from the _Admin_ (-) menu under _Local
+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_.
++
+NOTE: 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
+<<reporter_creating_folders,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
+<<reporter_creating_templates,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.
+++ /dev/null
-Cloning Shared Templates
-------------------------
-
-indexterm:[reports, cloning]
-
-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 <<reporter_creating_folders,Creating Folders>>.
-
-. Access the reports interface from the _Admin_ (-) menu under _Local
-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_.
-+
-NOTE: 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
-<<reporter_creating_folders,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
-<<reporter_creating_templates,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.
--- /dev/null
+[[reporter_creating_templates]]
+Creating Templates
+------------------
+
+indexterm:[reports, 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.
+
+Choosing Report Fields
+~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[reports, creating templates, choosing reports fields]
+
+. Click on the My Folder template folder where you want the template to be saved.
++
+image::media/create-template-1.png[create-template-1]
++
+. Click on Create a new Template for this folder.
++
+image::media/create-template-2.png[create-template-2]
++
+. 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).
++
+image::media/create-template-3.png[create-template-3]
++
+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.
++
+image::media/create-template-4.png[create-template-4]
++
+. 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.
++
+image::media/create-template-5.png[create-template-5]
++
+. 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.
++
+indexterm:[reports, field transform]
++
+image::media/create-template-6.png[create-template-6]
++
+_Field Transforms_ have either an _Aggregate_ or _Non-Aggregate_ output type.
+See the section called <<field_transforms,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.
++
+image::media/create-template-7.png[create-template-7]
++
+. _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_.
++
+image::media/create-template-8.png[create-template-8]
++
+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_.
++
+image::media/create-template-9.png[create-template-9]
++
+. 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.
++
+image::media/create-template-10.png[create-template-10]
++
+Click on the _+_ or arrow to expand _Circulating Item_. Select
+_Shelving Location_.
++
+image::media/create-template-11.png[create-template-11]
++
+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.
++
+image::media/create-template-12.png[create-template-12]
++
+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.
++
+image::media/create-template-13.png[create-template-13]
++
+Name will appear in the bottom left pane. Select the Name row and click _Alter
+Display Header_.
++
+image::media/create-template-15.png[create-template-15]
++
+. Enter a new, more descriptive column header, for example, _Shelving location_.
+Click _OK_.
++
+image::media/create-template-16.png[create-template-16]
++
+. 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_.
++
+image::media/create-template-17.png[create-template-17]
++
+. 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.
++
+image::media/create-template-19.png[create-template-19]
++
+. Select _Year + Month_ in the right hand _Field Transform_ pane and click _Add
+Selected Fields_
++
+image::media/create-template-20.png[create-template-20]
++
+. _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.
++
+image::media/create-template-21.png[create-template-21]
++
+. Select the _Check Out Date/Time_ row. Click _Alter Display Header_ and change
+the column header to _Check out month_.
++
+image::media/create-template-22.png[create-template-22]
++
+. 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.
+
+image::media/create-template-23.png[create-template-23]
+
+[NOTE]
+======
+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.
+
+image::media/create-template-24.png[create-template-24]
+======
+
+
+Applying Filters
+~~~~~~~~~~~~~~~~
+
+indexterm:[reports, 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.
+
+indexterm:[reports, applying filters, base filter]
+
+indexterm:[reports, applying filters, aggregate filters]
+
+_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.
+
+Using Base Filters
+^^^^^^^^^^^^^^^^^^
+
+indexterm:[reports, applying filters, base filter]
+
+. 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.
++
+image::media/create-template-25.png[create-template-25]
++
+. Select _Check Out Date/Time_. Click on _Change Operator_ and select _In list_
+from the dropdown menu.
++
+image::media/create-template-26.png[create-template-26]
++
+. To filter on the location of the circulation select
+_Circulation --> Circulating library --> Raw Data_ and click on _Add Selected Fields_.
++
+image::media/create-template-27.png[create-template-276]
++
+. 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.
++
+image::media/create-template-28.png[create-template-28]
++
+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_.
++
+image::media/create-template-29.png[create-template-29]
++
+. Click _OK_.
++
+image::media/create-template-30.png[create-template-30]
++
+. You will get a confirmation dialogue box that the template was successfully
+saved. Click OK.
++
+image::media/create-template-31.png[create-template-31]
++
+After saving it is not possible to edit a template. To make changes you will
+need to clone it and edit the clone
+
+[NOTE]
+==========
+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.
+
+image::media/create-template-32.png[create-template-32]
+==========
+
+
+
+++ /dev/null
-[[reporter_creating_templates]]
-Creating Templates
-------------------
-
-indexterm:[reports, 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.
-
-Choosing Report Fields
-~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[reports, creating templates, choosing reports fields]
-
-. Click on the My Folder template folder where you want the template to be saved.
-+
-image::media/create-template-1.png[create-template-1]
-+
-. Click on Create a new Template for this folder.
-+
-image::media/create-template-2.png[create-template-2]
-+
-. 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).
-+
-image::media/create-template-3.png[create-template-3]
-+
-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.
-+
-image::media/create-template-4.png[create-template-4]
-+
-. 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.
-+
-image::media/create-template-5.png[create-template-5]
-+
-. 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.
-+
-indexterm:[reports, field transform]
-+
-image::media/create-template-6.png[create-template-6]
-+
-_Field Transforms_ have either an _Aggregate_ or _Non-Aggregate_ output type.
-See the section called <<field_transforms,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.
-+
-image::media/create-template-7.png[create-template-7]
-+
-. _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_.
-+
-image::media/create-template-8.png[create-template-8]
-+
-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_.
-+
-image::media/create-template-9.png[create-template-9]
-+
-. 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.
-+
-image::media/create-template-10.png[create-template-10]
-+
-Click on the _+_ or arrow to expand _Circulating Item_. Select
-_Shelving Location_.
-+
-image::media/create-template-11.png[create-template-11]
-+
-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.
-+
-image::media/create-template-12.png[create-template-12]
-+
-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.
-+
-image::media/create-template-13.png[create-template-13]
-+
-Name will appear in the bottom left pane. Select the Name row and click _Alter
-Display Header_.
-+
-image::media/create-template-15.png[create-template-15]
-+
-. Enter a new, more descriptive column header, for example, _Shelving location_.
-Click _OK_.
-+
-image::media/create-template-16.png[create-template-16]
-+
-. 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_.
-+
-image::media/create-template-17.png[create-template-17]
-+
-. 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.
-+
-image::media/create-template-19.png[create-template-19]
-+
-. Select _Year + Month_ in the right hand _Field Transform_ pane and click _Add
-Selected Fields_
-+
-image::media/create-template-20.png[create-template-20]
-+
-. _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.
-+
-image::media/create-template-21.png[create-template-21]
-+
-. Select the _Check Out Date/Time_ row. Click _Alter Display Header_ and change
-the column header to _Check out month_.
-+
-image::media/create-template-22.png[create-template-22]
-+
-. 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.
-
-image::media/create-template-23.png[create-template-23]
-
-[NOTE]
-======
-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.
-
-image::media/create-template-24.png[create-template-24]
-======
-
-
-Applying Filters
-~~~~~~~~~~~~~~~~
-
-indexterm:[reports, 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.
-
-indexterm:[reports, applying filters, base filter]
-
-indexterm:[reports, applying filters, aggregate filters]
-
-_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.
-
-Using Base Filters
-^^^^^^^^^^^^^^^^^^
-
-indexterm:[reports, applying filters, base filter]
-
-. 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.
-+
-image::media/create-template-25.png[create-template-25]
-+
-. Select _Check Out Date/Time_. Click on _Change Operator_ and select _In list_
-from the dropdown menu.
-+
-image::media/create-template-26.png[create-template-26]
-+
-. To filter on the location of the circulation select
-_Circulation --> Circulating library --> Raw Data_ and click on _Add Selected Fields_.
-+
-image::media/create-template-27.png[create-template-276]
-+
-. 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.
-+
-image::media/create-template-28.png[create-template-28]
-+
-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_.
-+
-image::media/create-template-29.png[create-template-29]
-+
-. Click _OK_.
-+
-image::media/create-template-30.png[create-template-30]
-+
-. You will get a confirmation dialogue box that the template was successfully
-saved. Click OK.
-+
-image::media/create-template-31.png[create-template-31]
-+
-After saving it is not possible to edit a template. To make changes you will
-need to clone it and edit the clone
-
-[NOTE]
-==========
-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.
-
-image::media/create-template-32.png[create-template-32]
-==========
-
-
-
--- /dev/null
+Starting and Stopping the Reporter Daemon
+-----------------------------------------
+
+indexterm:[reports, starting server application]
+
+indexterm:[reporter, starting 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.
+
+Starting the Reporter Daemon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[reporter, starting]
+
+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
+
+
+[NOTE]
+=============
+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.
+==============
+
+Stopping the Reporter Daemon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+indexterm:[reports, stopping server application]
+
+indexterm:[reporter, stopping 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
+----
+
+++ /dev/null
-Starting and Stopping the Reporter Daemon
------------------------------------------
-
-indexterm:[reports, starting server application]
-
-indexterm:[reporter, starting 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.
-
-Starting the Reporter Daemon
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[reporter, starting]
-
-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
-
-
-[NOTE]
-=============
-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.
-==============
-
-Stopping the Reporter Daemon
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-indexterm:[reports, stopping server application]
-
-indexterm:[reporter, stopping 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
-----
-
--- /dev/null
+Exporting Report Templates Using phpPgAdmin
+-------------------------------------------
+
+indexterm:[reports, exporting templates]
+
+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.
+
+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
+
+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.
+
+
+++ /dev/null
-Exporting Report Templates Using phpPgAdmin
--------------------------------------------
-
-indexterm:[reports, exporting templates]
-
-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.
-
-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
-
-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.
-
-
--- /dev/null
+[[reporter_folders]]
+Folders
+-------
+
+indexterm:[reports, 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.
+
+image::media/folder-1.png[folder-1]
+
+[[reporter_creating_folders]]
+Creating Folders
+~~~~~~~~~~~~~~~~
+
+
+indexterm:[reports, folders, creating]
+
+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_.
+
+
+TIP: 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.
+
+Managing Folders
+~~~~~~~~~~~~~~~~
+
+indexterm:[reports, folders, managing]
+
+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_.
+
+
+
+++ /dev/null
-[[reporter_folders]]
-Folders
--------
-
-indexterm:[reports, 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.
-
-image::media/folder-1.png[folder-1]
-
-[[reporter_creating_folders]]
-Creating Folders
-~~~~~~~~~~~~~~~~
-
-
-indexterm:[reports, folders, creating]
-
-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_.
-
-
-TIP: 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.
-
-Managing Folders
-~~~~~~~~~~~~~~~~
-
-indexterm:[reports, folders, managing]
-
-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_.
-
-
-
--- /dev/null
+[[generating_reports]]
+Generating Reports from Templates
+----------------------------------
+
+indexterm:[reports, generating]
+
+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_.
++
+image::media/generate-report-1.png[generate-report-1]
++
+. Select the box beside _Circulations by month for one library_. Select _Create a
+new report_ from selected template from the dropdown menu. Click _Submit_.
++
+image::media/generate-report-2.png[generate-report-2]
++
+. Complete the first part of report settings. Only _Report Name_ and _Choose a
+folder_... are required fields.
++
+image::media/generate-report-3.png[generate-report-3]
++
+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.
++
+image::media/generate-report-8.png[generate-report-8]
++
+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_.
++
+image::media/generate-report-10.png[generate-report-10]
++
+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,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_.
++
+image::media/generate-report-14.png[generate-report-14]
++
+Once saved, reports stay there forever unless you delete them.
+
+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.
+
+image::media/2_7_Enhancements_to_Reports4.jpg[Reports4]
+
+
+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.
+
+
+image::media/2_7_Enhancements_to_Reports6.jpg[Reports6]
+
+
+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.
+
+image::media/2_7_Enhancements_to_Reports5.jpg[Reports5]
+++ /dev/null
-[[generating_reports]]
-Generating Reports from Templates
-----------------------------------
-
-indexterm:[reports, generating]
-
-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_.
-+
-image::media/generate-report-1.png[generate-report-1]
-+
-. Select the box beside _Circulations by month for one library_. Select _Create a
-new report_ from selected template from the dropdown menu. Click _Submit_.
-+
-image::media/generate-report-2.png[generate-report-2]
-+
-. Complete the first part of report settings. Only _Report Name_ and _Choose a
-folder_... are required fields.
-+
-image::media/generate-report-3.png[generate-report-3]
-+
-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.
-+
-image::media/generate-report-8.png[generate-report-8]
-+
-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_.
-+
-image::media/generate-report-10.png[generate-report-10]
-+
-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,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_.
-+
-image::media/generate-report-14.png[generate-report-14]
-+
-Once saved, reports stay there forever unless you delete them.
-
-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.
-
-image::media/2_7_Enhancements_to_Reports4.jpg[Reports4]
-
-
-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.
-
-
-image::media/2_7_Enhancements_to_Reports6.jpg[Reports6]
-
-
-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.
-
-image::media/2_7_Enhancements_to_Reports5.jpg[Reports5]
--- /dev/null
+[[recurring_reports]]
+Running Recurring Reports
+-------------------------
+
+indexterm:[reports, recurring]
+
+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,Viewing Report Output>>.
+
+To set up a monthly recurring report follow the procedure in <<generating_reports,
+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.
+
+TIP: 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.
+
+++ /dev/null
-[[recurring_reports]]
-Running Recurring Reports
--------------------------
-
-indexterm:[reports, recurring]
-
-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,Viewing Report Output>>.
-
-To set up a monthly recurring report follow the procedure in <<generating_reports,
-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.
-
-TIP: 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.
-
--- /dev/null
+Template Enhancements
+---------------------
+
+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.
+
+
+image::media/2_7_Enhancements_to_Reports1.jpg[Reports1]
+
+
+The link to this documentation will also appear in your list of report templates.
+
+
+image::media/2_7_Enhancements_to_Reports2a.jpg[Reports2a]
+
+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.
+
+image::media/2_7_Enhancements_to_Reports2.jpg[Reports2]
+
+
+To add or edit a field hint, select a filter or field, and click *Change Field Hint*. Enter text, and click *Ok*.
+
+
+image::media/2_7_Enhancements_to_Reports3.jpg[Reports3]
+++ /dev/null
-Template Enhancements
----------------------
-
-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.
-
-
-image::media/2_7_Enhancements_to_Reports1.jpg[Reports1]
-
-
-The link to this documentation will also appear in your list of report templates.
-
-
-image::media/2_7_Enhancements_to_Reports2a.jpg[Reports2a]
-
-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.
-
-image::media/2_7_Enhancements_to_Reports2.jpg[Reports2]
-
-
-To add or edit a field hint, select a filter or field, and click *Change Field Hint*. Enter text, and click *Ok*.
-
-
-image::media/2_7_Enhancements_to_Reports3.jpg[Reports3]
--- /dev/null
+Template Terminology
+--------------------
+
+Data Types
+~~~~~~~~~~
+
+indexterm:[reports, data types]
+
+The central column of the _Database Source Browser_ lists _Field Name_ and _Data
+Type_ for the selected database table.
+
+image::media/view-output-2.png[view-output-2]
+
+Each data type has its own characteristics and uses:
+
+[options="header,footer"]
+|====================================
+|Data Type |Description |Notes
+|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.
+|int |Integer
+|money |Number (in dollars)
+|=====================================
+
+[[field_transforms]]
+Field Transforms
+~~~~~~~~~~~~~~~~
+
+indexterm:[reports, field transforms]
+
+A _Field Transform_ tells the reporter how to process a field for output.
+Different data types have different transform options.
+
+indexterm:[reports, field transforms, raw data]
+
+*Raw Data*. To display a field exactly as it appears in the database use the
+_Raw Data_ transform, available for all data types.
+
+indexterm:[reports, field transforms, count]
+
+indexterm:[reports, field transforms, raw distinct]
+
+*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.
+
+[options="header,footer"]
+|====================================
+|Title |Patron ID |Patron Name
+|Harry Potter and the Chamber of Secrets |001 |John Doe
+|Northern Lights |001 |John Doe
+|Harry Potter and the Philosopher’s Stone |222 |Jane Doe
+|====================================
+
+indexterm:[reports, field transforms, output type]
+
+*Output Type*. Note that each transform has either an _Aggregate_ or
+_Non-Aggregate_ output type.
+
+indexterm:[reports, field transforms, output type, non-aggregate]
+
+indexterm:[reports, field transforms, output type, aggregate]
+
+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.
+
+++ /dev/null
-Template Terminology
---------------------
-
-Data Types
-~~~~~~~~~~
-
-indexterm:[reports, data types]
-
-The central column of the _Database Source Browser_ lists _Field Name_ and _Data
-Type_ for the selected database table.
-
-image::media/view-output-2.png[view-output-2]
-
-Each data type has its own characteristics and uses:
-
-[options="header,footer"]
-|====================================
-|Data Type |Description |Notes
-|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.
-|int |Integer
-|money |Number (in dollars)
-|=====================================
-
-[[field_transforms]]
-Field Transforms
-~~~~~~~~~~~~~~~~
-
-indexterm:[reports, field transforms]
-
-A _Field Transform_ tells the reporter how to process a field for output.
-Different data types have different transform options.
-
-indexterm:[reports, field transforms, raw data]
-
-*Raw Data*. To display a field exactly as it appears in the database use the
-_Raw Data_ transform, available for all data types.
-
-indexterm:[reports, field transforms, count]
-
-indexterm:[reports, field transforms, raw distinct]
-
-*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.
-
-[options="header,footer"]
-|====================================
-|Title |Patron ID |Patron Name
-|Harry Potter and the Chamber of Secrets |001 |John Doe
-|Northern Lights |001 |John Doe
-|Harry Potter and the Philosopher’s Stone |222 |Jane Doe
-|====================================
-
-indexterm:[reports, field transforms, output type]
-
-*Output Type*. Note that each transform has either an _Aggregate_ or
-_Non-Aggregate_ output type.
-
-indexterm:[reports, field transforms, output type, non-aggregate]
-
-indexterm:[reports, field transforms, output type, aggregate]
-
-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.
-
--- /dev/null
+[[viewing_report_output]]
+Viewing Report Output
+---------------------
+
+indexterm:[reports, output]
+
+indexterm:[reports, output, tabular]
+
+indexterm:[reports, output, Excel]
+
+indexterm:[reports, output, spreadsheet]
+
+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).
++
+image::media/view-output-1.png[view-output-1]
++
+. View report output is the default selection in the dropdown menu. Select
+_Recurring Monthly Circ by Location_ by clicking the checkbox and click _Submit_.
++
+image::media/view-output-2.png[view-output-2]
++
+. 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:
++
+image::media/view-output-4.png[view-output-4]
++
+. 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:
++
+image::media/view-output-5.png[view-output-5]
+
+
+++ /dev/null
-[[viewing_report_output]]
-Viewing Report Output
----------------------
-
-indexterm:[reports, output]
-
-indexterm:[reports, output, tabular]
-
-indexterm:[reports, output, Excel]
-
-indexterm:[reports, output, spreadsheet]
-
-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).
-+
-image::media/view-output-1.png[view-output-1]
-+
-. View report output is the default selection in the dropdown menu. Select
-_Recurring Monthly Circ by Location_ by clicking the checkbox and click _Submit_.
-+
-image::media/view-output-2.png[view-output-2]
-+
-. 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:
-+
-image::media/view-output-4.png[view-output-4]
-+
-. 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:
-+
-image::media/view-output-5.png[view-output-5]
-
-
--- /dev/null
+Evergreen Documentation
+=======================
+Documentation Interest Group
+:doctype: book
+:toc:
+:numbered:
+
+Introduction
+============
+
+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,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/.
+
+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.
+
+
+include::RELEASE_NOTES_2_12.adoc[]
+
+
+Software Installation
+=====================
+
+
+Introduction
+------------
+
+This part will guide you through the installation steps installation or
+upgrading your Evergreen system. It is intended for system administrators.
+
+
+include::installation/system_requirements.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::installation/server_installation.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::installation/staff_client_installation.adoc[]
+
+include::installation/server_upgrade.adoc[]
+
+include::installation/edi_setup.adoc[]
+
+
+System Configuration and Customization
+======================================
+
+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.
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::admin_initial_setup/describing_your_organization.adoc[]
+
+include::admin_initial_setup/describing_your_people.adoc[]
+
+include::admin_initial_setup/migrating_patron_data.adoc[]
+
+include::admin_initial_setup/migrating_your_data.adoc[]
+
+include::admin_initial_setup/importing_via_staff_client.adoc[]
+
+include::admin_initial_setup/ordering_materials.adoc[]
+
+include::admin_initial_setup/designing_your_catalog.adoc[]
+
+include::admin_initial_setup/borrowing_items.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::admin_initial_setup/hard_due_dates.adoc[]
+
+
+
+include::admin/template_toolkit.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::opac/new_skin_customizations.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::admin/auto_suggest_search.adoc[]
+
+include::admin/authentication_proxy.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::TechRef/KidsOPAC.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::admin/customize_staff_client.adoc[]
+
+include::admin/patron_address_by_zip_code.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::admin/phonelist.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::admin/sip_server.adoc[]
+
+include::admin/apache_rewrite_tricks.adoc[]
+
+include::admin/apache_access_handler.adoc[]
+
+
+Using the Browser Staff Client
+==============================
+
+
+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 http://docs.evergreen-ils.org/2.11/[Evergreen 2.11 documentation].
+
+include::admin/web_client-login.adoc[]
+
+include::admin/web_client-browser-tab-shortcuts.adoc[]
+
+include::admin/staff_client-column_picker.adoc[]
+
+include::admin/staff_client-recent_searches.adoc[]
+
+include::admin/staff_client-return_to_results_from_marc.adoc[]
+
+include::admin/workstation_admin.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::admin/workstation_admin_receipt_template_editor.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+System Administration From the Staff Client
+===========================================
+
+Introduction
+------------
+
+This part deals with the options in the Server Administration menu found in the
+staff client.
+
+// Follow structure from staff client system admin menu.
+
+include::admin/acquisitions_admin.adoc[]
+
+include::admin/age_hold_protection.adoc[]
+
+include::admin/authorities.adoc[]
+
+include::admin/Best_Hold_Selection_Sort_Order.adoc[]
+
+include::admin/booking-admin.adoc[]
+
+include::admin/cn_prefixes_and_suffixes.adoc[]
+
+include::admin/circulation_limit_groups.adoc[]
+
+include::admin/copy_statuses.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::admin/floating_groups.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::admin/MARC_Import_Remove_Fields.adoc[]
+
+include::admin/MARC_RAD_MVF_CRA.adoc[]
+
+include::admin/Org_Unit_Proximity_Adjustments.adoc[]
+
+include::admin/permissions.adoc[]
+
+include::admin/SMS_messaging.adoc[]
+
+include::admin/user_activity_type.adoc[]
+
+include::admin/restrict_Z39.50_sources_by_perm_group.adoc[]
+
+
+Local Administration
+====================
+
+Introduction
+------------
+
+This part covers the options in the Local Administration menu found in the staff
+client.
+
+// Follow structure from staff client local admin menu.
+
+include::admin/librarysettings.adoc[]
+
+// Address Alert Feature
+include::admin/lsa-address_alert.adoc[]
+
+// Barcode Completion Feature
+include::admin/lsa-barcode_completion.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::admin/hold_driven_recalls.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::admin/actiontriggers.adoc[]
+
+include::admin/recent_staff_searches.adoc[]
+
+include::admin/lsa-standing_penalties.adoc[]
+
+include::admin/lsa-statcat.adoc[]
+
+include::admin/lsa-work_log.adoc[]
+
+Acquisitions
+===========
+
+include::acquisitions/introduction.adoc[]
+
+include::acquisitions/selection_lists_po.adoc[]
+
+include::acquisitions/invoices.adoc[]
+
+include::acquisitions/receive_items_from_invoice.adoc[]
+
+include::acquisitions/vandelay_acquisitions_integration.adoc[]
+
+include::acquisitions/purchase_requests_patron_view.adoc[]
+
+include::acquisitions/purchase_requests_management.adoc[]
+
+
+Cataloging
+==========
+
+include::cataloging/cataloging_web_client.adoc[]
+
+include::cataloging/copy-buckets_web_client.adoc[]
+
+
+include::cataloging/MARC_Editor.adoc[]
+
+// Push titles down one level.
+:leveloffset: 2
+
+include::cataloging/physical_char_wizard.adoc[]
+
+// Return titles to correct level.
+:leveloffset: 0
+
+include::cataloging/batch_importing_MARC.adoc[]
+
+include::cataloging/overlay_record_3950_import.adoc[]
+
+include::cataloging/z39.50_search_enhancements.adoc[]
+
+include::cataloging/monograph_parts.adoc[]
+
+include::cataloging/conjoined_items.adoc[]
+
+include::cataloging/cataloging_electronic_resources.adoc[]
+
+include::cataloging/tpac_copy_edit_links.adoc[]
+
+include::cataloging/MARC_batch_edit.adoc[]
+
+include::cataloging/authorities.adoc[]
+
+include::cataloging/link_checker.adoc[]
+
+
+Serials
+=======
+
+include::serials/A-intro.adoc[]
+
+include::serials/B-copy_template.adoc[]
+
+include::serials/C-subscription-SCV.adoc[]
+
+include::serials/D-subscription-ASCV.adoc[]
+
+include::serials/E-edit_subscriptions.adoc[]
+
+include::serials/F-Receiving.adoc[]
+
+include::serials/G-Special_issue.adoc[]
+
+include::serials/H-holdings_statements.adoc[]
+
+include::serials/Group_Serials_Issues_in_the_OPAC_2.2.adoc[]
+
+Circulation
+===========
+
+Introduction
+------------
+
+Use this section for understanding the circulation procedures in the Evergreen
+system.
+
+include::circulation/circulating_items_web_client.adoc[]
+
+include::circulation/holds.adoc[]
+
+include::circulation/booking.adoc[]
+
+include::circulation/circulation_patron_records_web_client.adoc[]
+
+include::circulation/triggered_events.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::circulation/offline_mode.adoc[]
+
+include::circulation/self_check.adoc[]
+
+include::circulation/rfid_product_integration.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+Reports
+=======
+
+Introduction
+------------
+
+Learn how to create and use reports in Evergreen.
+
+include::reports/reporter_daemon.adoc[]
+
+include::reports/reporter_folder.adoc[]
+
+include::reports/reporter_create_templates.adoc[]
+
+include::reports/reporter_generating_reports.adoc[]
+
+include::reports/reporter_view_output.adoc[]
+
+include::reports/reporter_cloning_shared_templates.adoc[]
+
+include::reports/reporter_add_data_source.adoc[]
+
+include::reports/reporter_running_recurring_reports.adoc[]
+
+include::reports/reporter_template_terminology.adoc[]
+
+include::reports/reporter_template_enhancements.adoc[]
+
+include::reports/reporter_export_usingpgAdmin.adoc[]
+
+Using the Public Access Catalog
+===============================
+
+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.
+
+include::opac/using_the_public_access_catalog.adoc[]
+
+include::opac/my_lists.adoc[]
+
+include::opac/kids_opac.adoc[]
+
+include::opac/catalog_browse.adoc[]
+
+include::opac/advanced_features.adoc[]
+
+include::opac/tpac_meta_record_holds.adoc[]
+
+include::opac/linked_libraries.adoc[]
+
+include::opac/opensearch.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::opac/search_form.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+
+Developer Resources
+===================
+
+Introduction
+------------
+
+Developers can use this part to learn more about the programming languages,
+communication protocols and standards used in Evergreen.
+
+include::development/support_scripts.adoc[]
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::development/pgtap.adoc[]
+include::development/intro_opensrf.adoc[]
+include::development/updating_translations_launchpad.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+
+Getting Data from Evergreen
+===========================
+
+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.
+
+// Push titles down one level.
+:leveloffset: 1
+
+include::development/data_supercat.adoc[]
+
+include::development/data_unapi.adoc[]
+
+// Return to normal title levels.
+:leveloffset: 0
+
+include::attributions.adoc[]
+
+include::licensing.adoc[]
+
+[appendix]
+Admonitions
+===========
+
+* Note
+
+image::media/note.png[]
+
+* warning
+
+image::media/warning.png[]
+
+* caution
+
+image::media/caution.png[]
+
+* tip
+
+image::media/tip.png[]
+
+[index]
+Index
+=====
+
+++ /dev/null
-Evergreen Documentation
-=======================
-Documentation Interest Group
-:doctype: book
-:toc:
-:numbered:
-
-Introduction
-============
-
-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,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/.
-
-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.
-
-
-include::RELEASE_NOTES_2_12.adoc[]
-
-
-Software Installation
-=====================
-
-
-Introduction
-------------
-
-This part will guide you through the installation steps installation or
-upgrading your Evergreen system. It is intended for system administrators.
-
-
-include::installation/system_requirements.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::installation/server_installation.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::installation/staff_client_installation.txt[]
-
-include::installation/server_upgrade.txt[]
-
-include::installation/edi_setup.txt[]
-
-
-System Configuration and Customization
-======================================
-
-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.
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::admin_initial_setup/describing_your_organization.txt[]
-
-include::admin_initial_setup/describing_your_people.txt[]
-
-include::admin_initial_setup/migrating_patron_data.txt[]
-
-include::admin_initial_setup/migrating_your_data.txt[]
-
-include::admin_initial_setup/importing_via_staff_client.txt[]
-
-include::admin_initial_setup/ordering_materials.txt[]
-
-include::admin_initial_setup/designing_your_catalog.txt[]
-
-include::admin_initial_setup/borrowing_items.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::admin_initial_setup/hard_due_dates.txt[]
-
-
-
-include::admin/template_toolkit.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::opac/new_skin_customizations.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::admin/auto_suggest_search.txt[]
-
-include::admin/authentication_proxy.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::TechRef/KidsOPAC.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::admin/customize_staff_client.txt[]
-
-include::admin/patron_address_by_zip_code.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::admin/phonelist.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::admin/sip_server.txt[]
-
-include::admin/apache_rewrite_tricks.txt[]
-
-include::admin/apache_access_handler.txt[]
-
-
-Using the Browser Staff Client
-==============================
-
-
-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 http://docs.evergreen-ils.org/2.11/[Evergreen 2.11 documentation].
-
-include::admin/web_client-login.txt[]
-
-include::admin/web_client-browser-tab-shortcuts.txt[]
-
-include::admin/staff_client-column_picker.txt[]
-
-include::admin/staff_client-recent_searches.txt[]
-
-include::admin/staff_client-return_to_results_from_marc.txt[]
-
-include::admin/workstation_admin.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::admin/workstation_admin_receipt_template_editor.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-System Administration From the Staff Client
-===========================================
-
-Introduction
-------------
-
-This part deals with the options in the Server Administration menu found in the
-staff client.
-
-// Follow structure from staff client system admin menu.
-
-include::admin/acquisitions_admin.txt[]
-
-include::admin/age_hold_protection.txt[]
-
-include::admin/authorities.txt[]
-
-include::admin/Best_Hold_Selection_Sort_Order.txt[]
-
-include::admin/booking-admin.txt[]
-
-include::admin/cn_prefixes_and_suffixes.txt[]
-
-include::admin/circulation_limit_groups.txt[]
-
-include::admin/copy_statuses.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::admin/floating_groups.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::admin/MARC_Import_Remove_Fields.txt[]
-
-include::admin/MARC_RAD_MVF_CRA.txt[]
-
-include::admin/Org_Unit_Proximity_Adjustments.txt[]
-
-include::admin/permissions.txt[]
-
-include::admin/SMS_messaging.txt[]
-
-include::admin/user_activity_type.txt[]
-
-include::admin/restrict_Z39.50_sources_by_perm_group.txt[]
-
-
-Local Administration
-====================
-
-Introduction
-------------
-
-This part covers the options in the Local Administration menu found in the staff
-client.
-
-// Follow structure from staff client local admin menu.
-
-include::admin/librarysettings.adoc[]
-
-// Address Alert Feature
-include::admin/lsa-address_alert.txt[]
-
-// Barcode Completion Feature
-include::admin/lsa-barcode_completion.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::admin/hold_driven_recalls.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::admin/actiontriggers.txt[]
-
-include::admin/recent_staff_searches.txt[]
-
-include::admin/lsa-standing_penalties.txt[]
-
-include::admin/lsa-statcat.txt[]
-
-include::admin/lsa-work_log.txt[]
-
-Acquisitions
-===========
-
-include::acquisitions/introduction.txt[]
-
-include::acquisitions/selection_lists_po.txt[]
-
-include::acquisitions/invoices.txt[]
-
-include::acquisitions/receive_items_from_invoice.txt[]
-
-include::acquisitions/vandelay_acquisitions_integration.txt[]
-
-include::acquisitions/purchase_requests_patron_view.txt[]
-
-include::acquisitions/purchase_requests_management.txt[]
-
-
-Cataloging
-==========
-
-include::cataloging/cataloging_web_client.txt[]
-
-include::cataloging/copy-buckets_web_client.txt[]
-
-
-include::cataloging/MARC_Editor.txt[]
-
-// Push titles down one level.
-:leveloffset: 2
-
-include::cataloging/physical_char_wizard.txt[]
-
-// Return titles to correct level.
-:leveloffset: 0
-
-include::cataloging/batch_importing_MARC.txt[]
-
-include::cataloging/overlay_record_3950_import.txt[]
-
-include::cataloging/z39.50_search_enhancements.txt[]
-
-include::cataloging/monograph_parts.txt[]
-
-include::cataloging/conjoined_items.txt[]
-
-include::cataloging/cataloging_electronic_resources.txt[]
-
-include::cataloging/tpac_copy_edit_links.txt[]
-
-include::cataloging/MARC_batch_edit.txt[]
-
-include::cataloging/authorities.txt[]
-
-include::cataloging/link_checker.txt[]
-
-
-Serials
-=======
-
-include::serials/A-intro.txt[]
-
-include::serials/B-copy_template.txt[]
-
-include::serials/C-subscription-SCV.txt[]
-
-include::serials/D-subscription-ASCV.txt[]
-
-include::serials/E-edit_subscriptions.txt[]
-
-include::serials/F-Receiving.txt[]
-
-include::serials/G-Special_issue.txt[]
-
-include::serials/H-holdings_statements.txt[]
-
-include::serials/Group_Serials_Issues_in_the_OPAC_2.2.txt[]
-
-Circulation
-===========
-
-Introduction
-------------
-
-Use this section for understanding the circulation procedures in the Evergreen
-system.
-
-include::circulation/circulating_items_web_client.txt[]
-
-include::circulation/holds.txt[]
-
-include::circulation/booking.txt[]
-
-include::circulation/circulation_patron_records_web_client.txt[]
-
-include::circulation/triggered_events.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::circulation/offline_mode.txt[]
-
-include::circulation/self_check.txt[]
-
-include::circulation/rfid_product_integration.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-Reports
-=======
-
-Introduction
-------------
-
-Learn how to create and use reports in Evergreen.
-
-include::reports/reporter_daemon.txt[]
-
-include::reports/reporter_folder.txt[]
-
-include::reports/reporter_create_templates.txt[]
-
-include::reports/reporter_generating_reports.txt[]
-
-include::reports/reporter_view_output.txt[]
-
-include::reports/reporter_cloning_shared_templates.txt[]
-
-include::reports/reporter_add_data_source.txt[]
-
-include::reports/reporter_running_recurring_reports.txt[]
-
-include::reports/reporter_template_terminology.txt[]
-
-include::reports/reporter_template_enhancements.txt[]
-
-include::reports/reporter_export_usingpgAdmin.txt[]
-
-Using the Public Access Catalog
-===============================
-
-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.
-
-include::opac/using_the_public_access_catalog.txt[]
-
-include::opac/my_lists.txt[]
-
-include::opac/kids_opac.txt[]
-
-include::opac/catalog_browse.txt[]
-
-include::opac/advanced_features.txt[]
-
-include::opac/tpac_meta_record_holds.txt[]
-
-include::opac/linked_libraries.txt[]
-
-include::opac/opensearch.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::opac/search_form.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-
-Developer Resources
-===================
-
-Introduction
-------------
-
-Developers can use this part to learn more about the programming languages,
-communication protocols and standards used in Evergreen.
-
-include::development/support_scripts.txt[]
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::development/pgtap.txt[]
-include::development/intro_opensrf.txt[]
-include::development/updating_translations_launchpad.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-
-Getting Data from Evergreen
-===========================
-
-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.
-
-// Push titles down one level.
-:leveloffset: 1
-
-include::development/data_supercat.txt[]
-
-include::development/data_unapi.txt[]
-
-// Return to normal title levels.
-:leveloffset: 0
-
-include::attributions.txt[]
-
-include::licensing.txt[]
-
-[appendix]
-Admonitions
-===========
-
-* Note
-
-image::media/note.png[]
-
-* warning
-
-image::media/warning.png[]
-
-* caution
-
-image::media/caution.png[]
-
-* tip
-
-image::media/tip.png[]
-
-[index]
-Index
-=====
-
--- /dev/null
+Serials
+-------
+
+This documentation is intended for users who will be ordering subscriptions, distributing issues, and receiving issues in Evergreen.
+
+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, <<_generate_prediction,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 link:http://libmail.georgialibraries.org/mailman/listinfo/open-ils-general[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.
+
+[NOTE]
+The new combination view tries to provide the best of both views in one place. Try it out and send your feedback to the link:http://libmail.georgialibraries.org/mailman/listinfo/open-ils-general[Evergreen general discussion list].
+
+.Serials Control View and Alternate Serials Control View Comparison
+[options="header"]
+|====================================================================================================
+|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
+|====================================================================================================
+
+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.
+++ /dev/null
-Serials
--------
-
-This documentation is intended for users who will be ordering subscriptions, distributing issues, and receiving issues in Evergreen.
-
-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, <<_generate_prediction,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 link:http://libmail.georgialibraries.org/mailman/listinfo/open-ils-general[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.
-
-[NOTE]
-The new combination view tries to provide the best of both views in one place. Try it out and send your feedback to the link:http://libmail.georgialibraries.org/mailman/listinfo/open-ils-general[Evergreen general discussion list].
-
-.Serials Control View and Alternate Serials Control View Comparison
-[options="header"]
-|====================================================================================================
-|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
-|====================================================================================================
-
-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.
--- /dev/null
+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.
+
+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,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*.
+
+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*.
+
+[NOTE]
+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*.
+++ /dev/null
-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.
-
-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,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*.
-
-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*.
-
-[NOTE]
-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*.
--- /dev/null
+
+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.
+
+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.
+
+image::media/scv-combined-sub.png[Subscription]
+
+. 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*.
+
+[NOTE]
+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).
+
+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.
+
+From the new combination Serial Control View
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+image::media/scv-combined-dist.png[Distribution]
+
+. 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.
+
+[NOTE]
+Label, Holding Library, and Receive Unit Template are required fields when creating a distribution.
+
+[NOTE]
+Streams are created automatically in the Serial Control View. For information on using Streams in the combination Serial Control View, see <<_creating_a_stream,Creating a Stream>>.
+
+From the original Serial Control View
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+image::media/scv-distr.png[Distribution]
+
+. 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*.
+
+[NOTE]
+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).
+
+Create Captions and Patterns
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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.
+
+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*.
+
+Page 1: Enumerations
+++++++++++++++++++++
+
+image::media/cap-wiz-num.jpg[Enumeration]
+
+. 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.
++
+[NOTE]
+You can add up to six levels of enumeration.
++
+. Add Alternate Enumeration if desired.
+. When you have completed the enumerations, click *Next*.
+
+
+Page 2: Calendar
+++++++++++++++++
+
+image::media/cap-wiz-cal.jpg[Enumeration]
+
+. 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*.
+
+Page 3: Chronology
+++++++++++++++++++
+
+image::media/cap-wiz-chron.jpg[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*.
+
+Page 4: Compress and Expand Captions
+++++++++++++++++++++++++++++++++++++
+
+image::media/cap-wiz-freq.jpg[Compress or Expand]
+
+. 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*.
+
+Page 5: Regularity Information
+++++++++++++++++++++++++++++++
+
+image::media/cap-wiz-chan.jpg[Changes]
+
+. 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
+
+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.
+
+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.
+
+From the new combination Serial Control View
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+image::media/scv-combined-iss.png[Issuance]
+
+. 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.
+
+From the original Serial Control View
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+image::media/scv-iss.png[Issuance]
+
+. 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.
+
+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.
+++ /dev/null
-
-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.
-
-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.
-
-image::media/scv-combined-sub.png[Subscription]
-
-. 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*.
-
-[NOTE]
-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).
-
-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.
-
-From the new combination Serial Control View
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-image::media/scv-combined-dist.png[Distribution]
-
-. 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.
-
-[NOTE]
-Label, Holding Library, and Receive Unit Template are required fields when creating a distribution.
-
-[NOTE]
-Streams are created automatically in the Serial Control View. For information on using Streams in the combination Serial Control View, see <<_creating_a_stream,Creating a Stream>>.
-
-From the original Serial Control View
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-image::media/scv-distr.png[Distribution]
-
-. 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*.
-
-[NOTE]
-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).
-
-Create Captions and Patterns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-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.
-
-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*.
-
-Page 1: Enumerations
-++++++++++++++++++++
-
-image::media/cap-wiz-num.jpg[Enumeration]
-
-. 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.
-+
-[NOTE]
-You can add up to six levels of enumeration.
-+
-. Add Alternate Enumeration if desired.
-. When you have completed the enumerations, click *Next*.
-
-
-Page 2: Calendar
-++++++++++++++++
-
-image::media/cap-wiz-cal.jpg[Enumeration]
-
-. 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*.
-
-Page 3: Chronology
-++++++++++++++++++
-
-image::media/cap-wiz-chron.jpg[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*.
-
-Page 4: Compress and Expand Captions
-++++++++++++++++++++++++++++++++++++
-
-image::media/cap-wiz-freq.jpg[Compress or Expand]
-
-. 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*.
-
-Page 5: Regularity Information
-++++++++++++++++++++++++++++++
-
-image::media/cap-wiz-chan.jpg[Changes]
-
-. 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
-
-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.
-
-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.
-
-From the new combination Serial Control View
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-image::media/scv-combined-iss.png[Issuance]
-
-. 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.
-
-From the original Serial Control View
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-image::media/scv-iss.png[Issuance]
-
-. 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.
-
-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.
--- /dev/null
+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
+
+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.
+
+image::media/ascv-sub.jpg[Creating a Subscription]
+
+. 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.
+
+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.
+
+image::media/ascv-dist1.png[Creating a Distribution]
+
+. 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.
++
+[NOTE]
+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.
++
+image::media/ascv-dist2.png[New Distribution Form]
++
+. Click Save. The distribution will appear in a list in the Distributions tab in the Subscription Details.
+
+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.
++
+[NOTE]
+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.
+
+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*
+
+image::media/Added_User_to_Routing_Slip.jpg[]
+
+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.
+
+image::media/Address_on_Routing_Slip.jpg[]
+
+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.
+
+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.
+
+
+[NOTE]
+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.
+
+
+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.
+
+Page 1: Enumerations
+++++++++++++++++++++
+
+image::media/cap-wiz-num.jpg[Enumeration]
+
+. 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.
++
+[NOTE]
+You can add up to six levels of enumeration.
++
+. Add Alternate Enumeration if desired.
+. When you have completed the enumerations, click Next.
+
+Page 2: Calendar
+++++++++++++++++
+
+image::media/cap-wiz-cal.jpg[Enumeration]
+
+. 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.
+
+Page 3: Chronology
+++++++++++++++++++
+
+image::media/cap-wiz-chron.jpg[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.
+
+Page 4: Compress and Expand Captions
+++++++++++++++++++++++++++++++++++++
+
+image::media/cap-wiz-freq.jpg[Compress or Expand]
+
+. 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.
+
+Page 5: Regularity Information
+++++++++++++++++++++++++++++++
+
+image::media/cap-wiz-chan.jpg[Changes]
+
+. 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
+
+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.
+
+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.
+
+image::media/ascv-issues.jpg[Changes]
+
+. 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.
+
+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,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.
+++ /dev/null
-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
-
-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.
-
-image::media/ascv-sub.jpg[Creating a Subscription]
-
-. 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.
-
-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.
-
-image::media/ascv-dist1.png[Creating a Distribution]
-
-. 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.
-+
-[NOTE]
-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.
-+
-image::media/ascv-dist2.png[New Distribution Form]
-+
-. Click Save. The distribution will appear in a list in the Distributions tab in the Subscription Details.
-
-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.
-+
-[NOTE]
-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.
-
-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*
-
-image::media/Added_User_to_Routing_Slip.jpg[]
-
-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.
-
-image::media/Address_on_Routing_Slip.jpg[]
-
-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.
-
-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.
-
-
-[NOTE]
-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.
-
-
-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.
-
-Page 1: Enumerations
-++++++++++++++++++++
-
-image::media/cap-wiz-num.jpg[Enumeration]
-
-. 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.
-+
-[NOTE]
-You can add up to six levels of enumeration.
-+
-. Add Alternate Enumeration if desired.
-. When you have completed the enumerations, click Next.
-
-Page 2: Calendar
-++++++++++++++++
-
-image::media/cap-wiz-cal.jpg[Enumeration]
-
-. 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.
-
-Page 3: Chronology
-++++++++++++++++++
-
-image::media/cap-wiz-chron.jpg[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.
-
-Page 4: Compress and Expand Captions
-++++++++++++++++++++++++++++++++++++
-
-image::media/cap-wiz-freq.jpg[Compress or Expand]
-
-. 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.
-
-Page 5: Regularity Information
-++++++++++++++++++++++++++++++
-
-image::media/cap-wiz-chan.jpg[Changes]
-
-. 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
-
-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.
-
-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.
-
-image::media/ascv-issues.jpg[Changes]
-
-. 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.
-
-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,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.
--- /dev/null
+Edit Subscriptions
+------------------
+Subscriptions can be edited to change the caption and pattern and other information.
+
+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
+
+
+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
+
+++ /dev/null
-Edit Subscriptions
-------------------
-Subscriptions can be edited to change the caption and pattern and other information.
-
-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
-
-
-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
-
--- /dev/null
+Receiving
+---------
+You can receive either through the Serials Control View or in Batch Receive with the simple or advanced interface.
+
+Serials Control View Receiving
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+image::media/scv-rec.png[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.
+
+Notes in the Receiving Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+image::media/scv-notes.png[Alert Notes in 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*.
+
+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.
+
+Set Special Statuses
+^^^^^^^^^^^^^^^^^^^^
+
+image::media/scv-status.png[Set Item Status]
+
+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.
+
+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*.
+
+Simple Batch Receiving
+^^^^^^^^^^^^^^^^^^^^^^
+Follow these steps to receive items in batch in a simple interface.
+
+image::media/scv-srec.jpg[Receiving]
+
+. 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.
+
+Advanced Batch Receiving
+^^^^^^^^^^^^^^^^^^^^^^^^
+Follow these steps to receive items in batch in a simple interface.
+
+image::media/scv-srec.jpg[Receiving]
+
+. 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.
+
+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.
+
+image::media/dup_serials_barcode.JPG[Duplicate Barcode Warning]
+++ /dev/null
-Receiving
----------
-You can receive either through the Serials Control View or in Batch Receive with the simple or advanced interface.
-
-Serials Control View Receiving
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-image::media/scv-rec.png[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.
-
-Notes in the Receiving Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-image::media/scv-notes.png[Alert Notes in 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*.
-
-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.
-
-Set Special Statuses
-^^^^^^^^^^^^^^^^^^^^
-
-image::media/scv-status.png[Set Item Status]
-
-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.
-
-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*.
-
-Simple Batch Receiving
-^^^^^^^^^^^^^^^^^^^^^^
-Follow these steps to receive items in batch in a simple interface.
-
-image::media/scv-srec.jpg[Receiving]
-
-. 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.
-
-Advanced Batch Receiving
-^^^^^^^^^^^^^^^^^^^^^^^^
-Follow these steps to receive items in batch in a simple interface.
-
-image::media/scv-srec.jpg[Receiving]
-
-. 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.
-
-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.
-
-image::media/dup_serials_barcode.JPG[Duplicate Barcode Warning]
--- /dev/null
+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.
+++ /dev/null
-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.
--- /dev/null
+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.
+
+NOTE: This feature is only available in the Template Toolkit OPAC.
+
+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*.
+
+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*.
++
+image::media/Group_Serials_Issues_in_the_OPAC2.jpg[Group_Serials_Issues_in_the_OPAC2]
++
+. 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:
+
+image::media/Group_Serials_Issues_in_the_OPAC5.jpg[Group_Serials_Issues_in_the_OPAC5]
+
+The issues owned by the McKinley branch are grouped by enumeration:
+
+image::media/Group_Serials_Issues_in_the_OPAC7.jpg[Group_Serials_Issues_in_the_OPAC7]
+++ /dev/null
-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.
-
-NOTE: This feature is only available in the Template Toolkit OPAC.
-
-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*.
-
-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*.
-+
-image::media/Group_Serials_Issues_in_the_OPAC2.jpg[Group_Serials_Issues_in_the_OPAC2]
-+
-. 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:
-
-image::media/Group_Serials_Issues_in_the_OPAC5.jpg[Group_Serials_Issues_in_the_OPAC5]
-
-The issues owned by the McKinley branch are grouped by enumeration:
-
-image::media/Group_Serials_Issues_in_the_OPAC7.jpg[Group_Serials_Issues_in_the_OPAC7]
--- /dev/null
+Holdings
+--------
+
+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.
+
+MARC Format for Holdings Display (MFHD)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Evergreen users can create, edit and delete their own MFHD.
+
+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.
+
+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
+
+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
+++ /dev/null
-Holdings
---------
-
-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.
-
-MARC Format for Holdings Display (MFHD)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Evergreen users can create, edit and delete their own MFHD.
-
-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.
-
-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
-
-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
projects / evergreen / equinox.git / commitdiff