User Tools

Site Tools


A high-level birds-eye-view roadmap is now available on the main project site.

The original goal here was to delineate and organize every required/desired feature related to an ILS, and indicate whether Evergreen has it, can kludge it, or is going to get it properly. What I've decided to do for the time being is an informal/casual walkthrough of Evergreen, highlighting key features and benefits for end-users and developers alike, and maybe commenting on some future directions. I'll try to place bullet points in each section for easy skimming. If anyone wants to help, please give us a hollar at either OPEN-ILS-DEV or!

This document may freely interchange the words patrons, accounts, and users.

I'm going to start with the staff client, since I wrote most of it and it's what I know best.

Staff Client

Features for Developers

The staff client is a XUL application, which means it uses the same Mozilla framework that programs like Firefox and Thunderbird use. The technology stack would look familiar to web application developers; you have CSS, DTD's, DOM, AJAX, and XHTML. You also have things like XUL itself, which is an XML language geared toward representing interfaces, and XBL, another XML language for binding behavior to XUL elements, and XPCOM, a cross-platform component object specification.

  • I18N/L10N framework for language/locale support

For all of Mozilla/XUL/xulrunner's advantages, there are some disadvantages, and we're looking to consolidate technology stacks across the online catalog, the staff client, and things like Acquistions.

Features for End-Users

Login Window

Like most authenticated systems, Evergreen utilizes "user accounts" to restrict access to information in the system. The Login Window is the main staff interface for entering account credentials (though the Admin->Operator Change option in the main interface is another way for temporarily changing accounts and priviledges). You can also specify the server you wish to authenticate against. Conceivably, there might be demo servers, training servers, testing servers, staging servers, production servers, etc. The client is versioned with a Target Server ID, viewable from the About window, and a server may allow or disallow access based on that ID in addition to authentication credentials.

  • Offline Circulation Module
  • Secure authentication with SSL and 1-way algorithms
  • Named/registered workstation
  • Allows for specific/individual logins for better accountability
  • One user database, with patrons and staff (and staff roles) distinguished via permissions

Going in reverse order, the login name staff uses here is the same as their login for the public catalog. It's the same database. The permission system for Evergreen can be very granular, and users can be members of multiple permission groups, and/or could have permissions applied directly to their accounts. Evergreen gives you the option of using specific logins for better accountability. In most cases, the system will prompt you for a different set of credentials if you try to do something for which you don't have adequate permission (in the other cases, the action just fails). Raw permissions and permission groups can be managed by system administrators through the bootstrap config CGI's, and library admins can apply these permissions and groups to specific user accounts through the Admin->User Permission Editor available in the main interface.

  • Granular permission system with ranges based on the organization hierarchy (which is represented by an n-tier tree and associated depths)
  • Override prompts use the same username/permission system for re-trying failed actions, instead of secret codes

Each workstation (or user-based instance of the staff client) has to be registered with the system (and such registration requires specific permission from the system). Registration associates the client with a name and a library, and the permission system can consider the workstation library when interpreting permissions. So, for example, you can configure things such that a Cataloger from Branch A can only add items to Branch A when using a Branch A workstation. The workstation library affects circulation behavior. For example, if a circulating item is returned and checked in, it's the workstation library that is considered to be the physical location at which that happens. If that item belongs to a different library, Evergreen will tell you.

Sensitive data (or configurably, all data) is only sent over the wire with SSL encryption. Passwords during authentication are hashed against a challenge key and that hash is sent over the wire with SSL encryption. This is a CHAP-like means of authentication.

Standalone/Offline Interface

The offline mode is used for non-networked locations such as bookmobiles, and for emergencies when power/network is not available:

  • Basic circulation functions for offline mode: check out, check in, renew, in-house use, registration
  • System synchronizes at login, and updates:
    • non-barcoded options for checkout
    • libraries and surveys for patron registration
    • the delta or difference between system time and local time for correct merging of consolidated offline transactions
    • and optionally, a list of patrons denied circ privileges
  • Offline transactions from multiple locations can be consolidated and time-sorted (with the system being cognizant of variations in server time and various workstation times) and processed in batch.

We can go into more detail with offline mode when we get to the interface for managing those transactions.

With future versions of Evergreen, I would like to see the regular circulation interfaces have a "seamless" offline mode.

Workspace Management

After authenticating through the Login Window, the client will download and cache some data up-front to save time later, and then it will spawn the Main Window. In the titlebar for the Main Window, it will show the window number (each Main Window you open will be numbered consecutively), the current logged in user, the workstation name, and the server name. Below the titlebar is the menubar, with the options File, Edit, Search, Circulation, Cataloging, Admin, and Help. Below the titlebar is a tabbed interface, consisting of a horizontal list of labels for opened tabs and one panel below that showing the contents of the active/selected tab. This is similar to the tabbed interfaces found in modern web browsers. Pressing Control+T or selecting File->New Tab will open a new tab and active or select it, giving it focus. Control+W or File-Close Tab will close the active tab.

By default, one tab is opened on login, and the content for that tab depends on the server. A System Admin could place any arbitrary web page there, be it an information portal, a wiki, a helpdesk, a survey form, or even a XUL page that gives nice large buttons to use to launch interfaces with instead of the menubar. This custom content is shown any time a new tab is opened. Selecting an interface from the menubar, such as Circulation->Check In Items will replace the active tab with the new interface. Some actions within specific interfaces will replace or spawn new tabs depending on what seems most useful.

Each tab has a number associated with it that provides a keyboard shortcut for selecting the tab. For example, pressing Alt+1 will bring the first tab into focus. There is currently a hard limit of 9 tabs per Main Window, though that restriction will be removed in the future.

File->New Window or Control+W will open a new Main Window. File->Close Window or Control+Q will close the Main Window in focus.

Generally, I recommend that you only open tabs when you need to. For example, I think it's better to just hit F1 or F2 for Check Out and Check In as needed and recycle a single tab, than it is to keep open a specific tab for Check Out and an adjacent tab for Check In. One rationale for this is that the shortcut keys you use will be more consistent (F1 will always open Check Out, whereas Alt+1 just selects a tab that may or may not contain Check Out) and another is that you don't risk leaving open an old patron or bib record and acting upon it by mistake. But how you manage your workspaces is up to you.

  • Multiple Windows
  • Tab-based document interface
  • Customizable portal page
  • Keyboard and mouse driven, optionally icon-driven through portal page

Patron Management

Patrons and staff are both stored in the same user table in the database; the only difference between them is permissions. Library cards are stored in a separate table in the database and may be associated with users and used to retrieve them in the main Patron interface. F1 is the keyboard shortcut for the patron interface, as well as Circulation->Check Out Items and Circulation->Retrieve Patron by Barcode. You may also search for and retrieve users with the Patron Search interface, which is invoked with the F4 keyboard shortcut, or the Search->for patrons action. And you may retrieve the last user retrieved with Circulation->Retrieve Last Patron or F8. You may create new users with Circulation->Register Patron, or Shift+F1.

  • Supports barcode scanners for input of library cards
  • Users may be grouped together (for example, to model families and classrooms)
  • Library cards can be deactivated separately from users, preserving historical information
  • Evergreen has an option for recording and requiring staff to "Opt-In" to accessing a patron's record from other libraries in a consortium (this could, for example, be used to acknowledge that staff has the patron's consent). Tied to this feature is the masking of foreign patrons in the Patron Search interface that have not been Opted-In by the library.

Patron Registration

This interface will create a user and a library card for that user, and allows staff to set such fields as Username (to use, for example, for logging into the public catalog), Password, First Name, Middle Name, Last Name, Name Suffix, Date of Birth, an Identification Type and associated information, email address (used for overdue notices, hold notifications, etc.), daytime phone number, evening phone, other/cell phone, home library, an unlimited number of addresses (which can be annotated with a label, flagged as invalid, marked as being within city limits, marked as being the user's mailing address, and marked as being the user's physical address), Profile Group (the main permission group, which can affect for circulation behavior), Account Expiration Date, Internet Access Level (used by computer reservation and Internet filtering software via SIP2), an Active flag (to use instead of completely obliterating a patron record, if desired), a Barred flag, a Family/Group Lead Account flag for user groupings, a Claims Returned Count for tracking potential abuse by patrons who claim to have returned items that have not been checked in, a free-form Alert Message field to convey important information to staff on patron retrieval, unlimited library-defined Statistical Categories (or StatCats) and optionally defined entries for those StatCats, to store and tag information arbitrary information on the user (for example, Student or Military Identification, Demographic information such as Language or hair style, etc.) StatCats may optionaly be configured so that they are viewable by the patron in their My Account section in the public catalog. The Patron Registration interface can also present unlimited library defined polls or surveys, which may be answered repeatedly, and which can be configured to expire after a specified time frame. For example, PINES uses this for voter registration information. This same interface is also used for editing existing patrons from the main Patron Display.

  • Separate fields for name information (first, middle, last, suffix)
  • Unlimited addresses that may be canonically linked/shared between users
  • Unlimited library-defined Statistical Categories and Polls/Surveys, to eliminate the need for overloading/abusing fields with data that should be orthogonal
  • Real-time behind-the-scenes searching of existing patrons and warning of possible duplicate patrons during data entry
  • Printable summary of registration information for paper records and patron confirmation
  • Ability to clone and link patrons for fast entry of, for example, families

The Patron Search interface is invoked with either the F4 shortcut key or the Search->for patrons menu option from the main window. This is a left-anchored fielded search that allows you to search on Last Name, First Name, Middle Name, Email Address, Phone Number (for all the phone number fields on the patron), ID (for all Identification Types), and Address 1, Address 2, City, and Postal Code for all addresses attached to the patron. There is also a flag for including Inactive patrons, and a menu dropdown for limiting results to patrons associated with specific library ranges (based on the organization hierarchy) by Home Library. Results for a patron search are displayed in a customizable list, and as you step through them, the same Patron Summary Sidebar from the main Patron Display is updated in an adjacent panel. You may select multiple patrons from that list and retrieve them all at once, with each being loaded into a new tab.

  • Fielded search for specific queries
  • Inactive and Home Library filters on search results
  • Customizable, sortable pick list and summary sidebar for easy comparison of patrons
  • Ability to retrieve multiple patrons at one time from the pick list

Patron Display

The main Patron Display appears after you retrieve a patron by either barcode or from the Patron Search interface, or from the Circulation->Retrieve Last Patron action. The interface is divided into 3 parts: a horizontal strip at the top and two vertical panels beneath. The horizontal strip contains the patron's name and some brief status information, and some navigation buttons for which sub-interface will appear in the vertical panel on the right (similar to a tabbed interface). The patron's name will be color-coded based on various criteria: green means the patron is in good standing, red means the patron is barred, and other colors might mean that the patron has overdue items, bills, etc. The non-green colors will correspond with colored textual tags that will appear immediately below the patron's name, and with data in the Patron Summary Sidebar, which sits in the vertical pane on the left. These colors are customizable via CSS. The textual labels include the following: (Barred), (Expired), (In-Active), (Juvenile), (Alert), (See Notes), (Has Bills), (Max Bills), (Has Overdues), (Max Overdues), (Invalid DOB), and (Invalid Address).

The summary sidebar contains the following information: patron name, main permission group (or profile), home library, internet access level (for certain SIP2 uses), account expiration date, number of hold requests (total and available), total bills, check outs (total, overdue, long overdue, claimed returned, lost, and non-cataloged), active library card barcode, identification, date of birth, phone number (day, evening, and other), OPAC Login (or username), email address, mailing address, and physical address. In the future we plan to add summary information for linked group members.

  • Patron-specific interfaces embedded in a general patron display which packs a lot of information in consistent locations
  • Customizable color-coded information for at-a-glance discernation of patron status
  • By default, the Check Out interface is selected in the Patron Display for quick circulation, however an automatic alert screen will appear instead if information needs to be conveyed to staff about the patron

These are the buttons to the right of the patron's name in the Patron Display:


This forces a refresh from the server of all patron information being displayed.

Check Out

This is where you circulate (i.e. check out, lend, loan, charge) items to the patron. We'll go into more detail in the Circulation section.

  • Ability to circulate cataloged, non-cataloged (labeled but not barcoded or cataloged), and pre-cataloged (barcoded but not yet cataloged) items
Items Out

In this interface we see the items the patron currently has out, as well as unresolved items the patron may be responsible for (lost, long-overdue, and claimed returned). The lists here are customizable, sortable, exportable, and printable, and various actions may be performed on selected items from a list, such as Copy to Clipboard, Add to Item Bucket, Show in Catalog, Show Item Details, Show Last Few Circulations, Edit Due Date, Mark Lost (by Patron), Mark Claimed Returned, Renew, Renew All, Check In, and Add Billing.

  • Ability to renew specific items without having the items in-hand

In this interface we see the active hold requests for the patron (materials that the patron desires), and whether they are ready for pick-up by the patron or not. The hold list here, like all hold lists, is customizable, sortable, exportable, and printable, and various actions may be performed on selected holds, such as Copy to Clipboard, Show in Catalog, Show Item Details, Show Last Few Circulations, Retrieve Patron, Show Notices, Edit Pickup Library, Edit Phone Notification, Set Email Notification, Edit Thaw Date, Set Freeze, Mark Item Damaged, Mark Item Missing, Find Another Target, and Cancel Hold.

We'll go into how holds work in the section for the online catalog.

  • Ability to freeze, thaw, and retarget specific holds

With this interface we see all monies owed by the patron, and are able to add new bills and record payments received. There are multiple payment types, such as cash, check, credit card, work, forgive, and goods. There are also library definable billing types, and staff are able to annotate both bills and payments. Bills may be linked to circulations or stand alone. Billable transactions contain billing line-items and payment line-items. Evergreen has optional support for allowing patrons to carry credit. Staff are able to select specific bills to apply payments to. Like all printable lists, bill/payment receipts are templatable.

  • Ability to cherry-pick bills for applying payment
  • Ability to annotate bills and payments, and void specific line-items
  • Customizable receipt templates
  • Fine-grained information with multiple billing and payment types and notes, as well as multiple billing and payment line-items on a single transaction
  • Fines accrue as they logically become due, with a line item per fine interval, instead of being a nebulous calculated value that becomes real upon check-in. Backdated returns can automatically void accrued fines.

This is the same interface used by Patron Registration, with extra functions allowing staff to mark the active library card as being lost and replacing it, and an action for quickly generating a random 4-digit password.

  • Unified interface for creating new and editing existing accounts.

This is a catch-all section containing staff Notes on the patron (which may optionally be made visible to the patron in the online catalog in the My Account as a means of communicating with the patron), Stat Cats, Surveys, and an account Group interface for managing the patron's membership in a group (as well as for managing other members in that group).


This action will clear out the Patron Display and recycle the tab for the scanning of another patron's library card.


  • Extremely flexible and granular scriptable circulation logic
  • Optional Codabar check-digit algorithm for barcodes
  • Pre-Cataloged or Fast Add or On-The-Fly circulations which do not create fake bibliographic records and can be later cataloged without losing circulation statistics
  • Library-Definable Non-Barcoded Non-Cataloged types for circulation and In-House use
  • Customizable receipt templates
  • Optional automatic printing of Hold and Transit slips
  • Information display on Check In for such things as redundant check-ins and patron late fees, and audible sound effects
  • Ability to backdate returns in batch during Check In (with a color-coded background to make it obvious)
  • Scan-proof alert messages that prevent accidental closure from barcode scanners

Check Out

The main means of tracking circulations in Evergreen is through the scanning of barcoded items. Circulation behavior (lending periods, fine structures, allowed renewals) is scriptable on the server, and can be based on virtually any information or aspect of objects in the system, such as patron attributes (types, profiles, age, permissions, etc.), item attributes (types, circ modifier, Circ Library, Owning Library, Shelving Location, relative Loan Duration, relative Fine Level, etc.), and bibliographic information such as the record type. The due dates for circulations may also be overriden by staff based on permissions. These rules and behaviors can be defined for specific libraries and/or specific sets of libraries based on the organization hierarchy. For example, at a consortial level, you could define a set of global default rules, and then override them at regional, system, and branch levels with more specific rules (assuming you define your organization hierarchy thus).

Cataloged items may also be marked as "used in-house", which is distinguishable from real circulations in statistical reporting.

Alert messages on items may halt the Check Out process, requiring confirmation from staff. Other alerts may be based on such things as patron statuses/standing (max fines, max items out, etc.) and item attributes (for example, Do Not Circulate). Alert dialogs are "scan-proof", immune from inadvertant dismissal from barcode scanner activity.

The item list in Check Out is customizable, sortable, exportable, and printable.


When staff tries to circulate a barcoded item that is not in the system, Evergreen prompts to see if they would like to circulate the item as Pre-cataloged. This creates an item record in the database, but no corresponding bibliographic record (though staff may record a temporary title and author for the item). Upon return of the item during Check In, Evergreen optionally alerts staff that the item is a Pre-Cat. The item may be transferred to an existing volume/record at any time and maintain its circulation history.


Evergreen also allows you to track non-barcoded (non-cataloged) items. You can define arbitrary non-cat types and corresponding loan durations for specific libraries and/or specific sets of libraries based on the organization hierarchy. Non-Cat items work on the honor system: when one "circulates", it is listed on a patron's record until the loan duration expires, at which point it is no longer listed on the patron's record. These circulations can be distinguished from cataloged circulations in statistical reporting. Non-cat items may also be marked as "used in-house", which is distinct from regular circulations.

Check In

The Check In interface handles returns of barcoded items, as well as hold captures (both opportunistic and from shelf-pulls). You may place the interface in a visually distinguished backdating mode for batch processing of, for example, overnight and bookdrop returns, with an arbitrary Effective Date for the purpose of automatically voiding inadvertant fine accrual. Check In may optionally automatically print Hold and Transit slips.

Alert messages on items may halt the Check In process, requiring confirmation from staff. Other alerts may be based on criteria such as Item Lost, Missing, Claimed Returned, etc. Alert dialogs are "scan-proof", immune from inadvertant dismissal from barcode scanner activity.

The item list in Check In is customizable, sortable, exportable, and printable, and various actions may be performed on selected items, such as Copy to Clipboard, Add to Item Bucket, Show in Catalog, Show Item Details, Show Last Few Circulations, Retrieve Last Patron who circulated item, Edit Item Attributes, Mark Item Damaged, Abort Transit, and Print Spine Label.

Hold Capture

We'll go into detail with how holds work in the section for the online catalog. Briefly, when an eligible or targeted item becomes captured for a hold, it is either placed into transit to the pickup library, or, if it is already at the pickup library, it is routed to the Hold Shelf.


There are two types of transits. The first is when an item is returned to a foreign library: upon Check In, the item is automatically placed into a transit status (the original status is preserved) and a transit record is created indicating the item's Circulation Lib as the destination library. Staff is either optionally alerted and offered a print-out of the transit slip or the slip can be automatically printed. The second type of transit is a Hold Transit, for when an item is captured for a hold and must be sent to a specified pickup library. Transits are both initiated and received through the Check In interface.

In-House Use




MARC Editor

Holdings Maintenance

Volumes and Items

Record Buckets

Spine/Pocket Labels



Offline Transactions

Receipt Templates

Item/Shelving Locations

Statistical Categories

zzz_archive/dev/feature_tree.txt · Last modified: 2022/02/10 13:34 (external edit)

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.