HomeBasic Evergreen FunctionsPrinter Friendly Version

Basic Evergreen Functions

While this book is *incomplete* at best, we will slowly be adding sections to it as they become available. Any additions for this KB are greatly appreciated!

1. Acquisitions

1.1. What is the Unnamed search that appears in My Selection Lists?

Confirmed Version: Evergreen 2.1

In the Acquisitions module of Evergreen, when performing a General Search that involves the specific type "line items & catalog records" the staff user working with the module will notice upon switching to the My Selection Lists page an additional pre-filled search titled "Unnamed" that appears to be filled with random items.

This "canned" search is created within /openils/var/web/js/ui/default/acq/search/unified.js by virtue of the function URIManager. In this portion of code, there are several different canned searches, however the one pertinent to this issue is pl, which refers to picklist.

When the staff member executes a search in General Search and specifically chooses line items & catalog records, a canned search is simultaneously created from the general results that is output to My Selection Lists as Unnamed. This canned search utilises the union of all items contained in the search results that were also created by the staff member running the general search.

Members with admin permissions may or may not notice items created by other staff connected to the Admin account.

This Unnamed search may serve as a starting point for a staff member creating a new pick list, and may be ignored or deleted at will.

Any future General Searches with the above parameter update and change the Unnamed search results. If Unnamed is deleted, a new search will re-create it.

This is a normal function of the Evergreen system.

2. Cataloging

2.1. How to add a merge profile

To add a merge profile, go to Cataloging MARC Batch Import/Export. You should see this:



You will notice at the top the "Edit Merge Overlay Profiles". Click on that. It will lead you to this:

As you can see, the org unit is selectable, but there are no profiles for my org unit yet. So click "New Merge Profile". A screen will pop up like this:

I will then enter "Blank" and select my org unit. Nothing else need be added. Click "Save". You will be returned to the previous screen. There you will observe the new profile:

We now return to the original screen by clicking "Import Records". Remember, once you return, you MUST click "Reload" to get a fresh copy of the contents of this screen. Then you will be able to select your new profile.

3. Technical Support

3.1. Support Procedures

To Submit a support issue via email: support@esilibrary.com -- When submitting an email ticket please remember to supply as much information as possible. This includes the steps taken to create the issue, what you were originally trying to do, and what actually happened after you took those steps. Usually the support staff try and recreate the issue so that they may fully understand the issue and resolve it quickly. If provided with enough information to recreate the problem, we can formulate a solution for you quickly and efficiently.

To submit or check on a request via the web portal: http://support.esilibrary.com -- When logging in for the first time, first select "Check on a Request." Enter your email address as shown above and click 'Retrieve password' to have a password generated and emailed to you. This password will allow you to check on all tickets submitted. To check on one specific request, enter the access key that can be found in the confirmation of submission email that you receive after a ticket is created. There is also a link in the confirmation email that will take you directly to the ticket to update or retrieve more information.

To Call in Urgent Support Issues: 1-877-OPEN-ILS Option 2. Our phone number can also be found on the support web portal should you need to find it quickly. Urgent issues include, but are not necessarily limited to: system down scenarios, complete loss of searching or circulation, or other complete loss of functionality scenarios.

3.2. Master Permissions List

Permission NamePermission Description
ABORT_REMOTE_TRANIST Allows user to abort a copy transit if the user is not at the transit source or destination
ABORT_TRANSIT Allows user to abort a copy transit if the user is at the transit destination or source
ASSIGN_WORK_ORG_UNIT Allows user to define where another staff member's permissions apply via the Permissions Editor interface.
BAR_PATRON Allows user to bar a patron
CANCEL_HOLDS Allows user to cancel holds
CHECKIN_BYPASS_HOLD_FULFILL *no longer applicable
CIRC_CLAIMS_RETURNED.override Allows user to check in/out an item that is claims returned
CIRC_EXCEEDS_COPY_RANGE.override Allows user to override the copy exceeds range event
CIRC_OVERRIDE_DUE_DATE Allows user to change due date
CIRC_PERMIT_OVERRIDE Allows user to bypass the circ permit call for checkout
COPY_ALERT_MESSAGE.override Allows user to check in/out an item that has an alert message
COPY_BAD_STATUS.override Allows user to check out an item in a non-circulatable status
COPY_CHECKIN Allows user to check in a copy
COPY_CHECKOUT Allows user to check out a copy
COPY_CIRC_NOT_ALLOWED.override Allows user to checkout an item that is marked as non-circ
COPY_HOLDS Allows user to place a hold on a specific copy
COPY_IS_REFERENCE.override Allows user to override the copy_is_reference event
COPY_NEEDED_FOR_HOLD.override Allows user to check out a copy even if it is needed to fill a hold.
COPY_NOT_AVAILABLE.override Allows user to force checkout of Missing/Lost type items
COPY_STATUS_LOST.override Allows user to remove the lost status from a copy
COPY_STATUS_MISSING.override Allows user to change the missing status on a copy
COPY_TRANSIT_RECEIVE Allows user to close out a transit on a copy
CREATE_BILL Allows user to create a new bill on a transaction
CREATE_CONTAINER Allows user to create containers owned by other users (containers are Item Buckets, Volume Buckets, and Book Bags)
CREATE_CONTAINER_ITEM Allows user to place an item in a container (even if the container is owned by other users).
CREATE_COPY Allows user to create a new copy object
CREATE_COPY_LOCATION Allows user to create a new copy location
CREATE_COPY_NOTE Allows user to create a new copy note
CREATE_COPY_STAT_CAT Allows user to create a statisitcal category for copies
CREATE_COPY_STAT_CAT_ENTRY Allows user to create a new entry for a copy statistical category
CREATE_COPY_STAT_CAT_ENTRY_MAP Allows user to link a copy to a statistical category entry (i.e., allows user to specify the appropriate entry for a copy and given statistical category)
CREATE_COPY_TRANSIT Allows user to create a transit
CREATE_DUPLICATE_HOLDS Allows user to create duplicate holds (e.g. two holds on the same title)
CREATE_HOLD_NOTIFICATION Allows user to create new hold notifications
CREATE_IN_HOUSE_USE Allows user to create a new in-house-use
CREATE_MARC Allows user to create new MARC records
CREATE_MY_CONTAINER Allows user to create containers for self (containers are Item Buckets, Volume Buckets, and Book Bags).
CREATE_NON_CAT_TYPE Allows user to create a new non-cataloged item type
CREATE_PATRON_STAT_CAT Allows user to create a new patron statistical category
CREATE_PATRON_STAT_CAT_ENTRY Allows user to create a new possible entry for patron statistical categories
CREATE_PATRON_STAT_CAT_ENTRY_MAP Allows user to link another user to a stat cat entry (i.e., specify the patron's entry for a given statistical category)
CREATE_PAYMENT Allows user to record payments in the Billing Interface
CREATE_TITLE_NOTE Allows user to create a new title note
CREATE_TRANSACTION Allows user to create new billable transactions (these include checkouts and transactions created via the Bill Patron operation)
CREATE_TRANSIT Allows user to place item in transit
CREATE_USER Allows user to create another user
CREATE_USER_GROUP_LINK Allows user to add other users to permission groups
CREATE_VOLUME Allows user to create a volume
CREATE_VOLUME_NOTE Allows user to create a new volume note
DELETE_CONTAINER Allows user to delete containers (containers are Item Buckets, Volume Buckets, and Book Bags).
DELETE_CONTAINER_ITEM Allows user to remove items from buckets and bookbags
DELETE_COPY Allows user to delete a copy
DELETE_COPY_LOCATION Allows user to delete a copy location
DELETE_COPY_NOTE Allows user to delete copy notes
DELETE_COPY_STAT_CAT Allows user to delete a copy statistical category
DELETE_COPY_STAT_CAT_ENTRY Allows user to delete an entry for a copy statistical category
DELETE_COPY_STAT_CAT_ENTRY_MAP Allows user to delete a copy stat cat entry map
DELETE_HOLDS * no longer applicable
DELETE_NON_CAT_TYPE Allows user to delete a non cataloged type (the user still cannot deleted a non-cat type if any items of that type have circulated).
DELETE_PATRON_STAT_CAT Allows user to delete a patron statistical category
DELETE_PATRON_STAT_CAT_ENTRY Allows user to delete an entry for patron statistical categories
DELETE_PATRON_STAT_CAT_ENTRY_MAP Allows user to remove a patron's entry for a given statistical category
DELETE_RECORD Allows user to delete a bib record
DELETE_TITLE_NOTE Allows user to delete title notes
DELETE_USER Allows user to mark a user as deleted
DELETE_VOLUME Allows user to delete a volume
DELETE_VOLUME_NOTE Allows user to delete volume notes
DELETE_WORKSTATION Allows user to remove an existing workstation so a new one can replace it
EVERYTHING Every permssion is granted (for sysadmins and developers only!)
HOLD_EXISTS.override Allows users to place multiple holds on a single copy/volume/title/metarecord (depending on hold type)
IMPORT_MARC Allows user to import a MARC record via the z39.50 interface
ITEM_AGE_PROTECTED.override Allows user to place a hold on an age-protected item
ITEM_ON_HOLDS_SHELF.override Allows user to check out an item that is on holds shelf for a different patron
MAX_RENEWALS_REACHED.override Allows user to renew an item past the maximun renewal count
MERGE_BIB_RECORDS Allows user to merge bib records and their associated data regardless of their bib/volume/copy level perms (in theory - as of 1.2.2, users still must have VOLUME_UPDATE and UPDATE_VOLUME ino rder to merge records.
MR_HOLDS Allows user to create a metarecord holds
OFFLINE_EXECUTE Allows user to process an offline/standalone script batch
OFFLINE_UPLOAD Allows user to upload an offline/standalone script
OFFLINE_VIEW Allows user to view uploaded offline script information
OPAC_LOGIN Allows user to login to the OPAC
PATRON_EXCEEDS_CHECKOUT_COUNT.override Allow user to override checkout count failure
PATRON_EXCEEDS_FINES.override Allow user to override fine amount checkout failure
PATRON_EXCEEDS_OVERDUE_COUNT.override Allow user to override overdue count failure
REGISTER_WORKSTATION Allows user to register a new workstation
REMOTE_Z3950_QUERY Allows user to perform z3950 queries against remote servers
REMOVE_USER_GROUP_LINK Allows user to remove other users from permission groups
RENEW_CIRC Allows user to renew items
RENEW_HOLD_OVERRIDE Allows user to continue to renew an item even if it is required for a hold.
REQUEST_HOLDS Allows user to create holds for another user (if true, we still check to make sure they have permission to make the type of hold they are requesting, e.g. COPY_HOLDS)
REQUEST_HOLDS_OVERRIDE * no longer applicable
RUN_REPORTS Allows user to view the Reports Interface, create templates, and run reports
SET_CIRC_CLAIMS_RETURNED Allows user to mark an item as claimed returned
SET_CIRC_LOST Allows user to mark an item as lost
SET_CIRC_MISSING Allows user to mark an item as missing
SHARE_REPORT_FOLDER Allows user to share Template/Report/Output folders via the Reporting Interface
STAFF_LOGIN Allows user to login to the staff client
TITLE_HOLDS Allows user to place a hold at the title level
UNBAR_PATRON Allows user to un-bar a patron
UPDATE_BATCH_COPY Allows user to edit copies in batch
UPDATE_CONTAINER Allows user to update another users Buckets or Book Bags
UPDATE_COPY Allows user to edit a copy
UPDATE_COPY_LOCATION Allows user to edit a copy location
UPDATE_COPY_STAT_CAT Allows user to change a copy statistical category
UPDATE_COPY_STAT_CAT_ENTRY Allows user to change a copy statistical category entry
UPDATE_HOLD Allows user to edit holds (such as change notification phone number or pickup library, as well as retarget the hold and capture an item for hold or pickup)
UPDATE_MARC Allows user to edit a marc record
UPDATE_NON_CAT_TYPE Allows user to update a non cataloged type
UPDATE_ORG_SETTING Allows user to update an org unit setting
UPDATE_ORG_UNIT Allows user to change org unit settings
UPDATE_PATRON_STAT_CAT Allows user to change a patron statistical category (such as renaming the category)
UPDATE_PATRON_STAT_CAT_ENTRY Allows user to change a patron stat cat entry (such as renaming the entry)
UPDATE_RECORD Allows user to undelete a MARC record
UPDATE_USER Allows user to edit a user's record
UPDATE_VOLUME Allows user to edit volumes - needed for merging records. This is a duplicate of VOLUME_UPDATE; user must have both permissions at appropriate level to merge records.
VIEW_CIRCULATIONS Allows user to see what another user has checked out
VIEW_CONTAINER Allows user to view buckets and bookbags
VIEW_COPY_CHECKOUT_HISTORY Allows user to view which users have checked out a given copy
VIEW_COPY_NOTES Allows user to view notes attached to a copy
VIEW_HOLD Allows user to view another user's holds
VIEW_HOLD_NOTIFICATION Allows user to view notifications attached to a hold
VIEW_HOLD_PERMIT Allows user to see if another user has permission to place a hold on a given copy
VIEW_PERM_GROUPS Allows user to view permission groups.
VIEW_PERMISSION Allows user to view user permissions within the user permissions editor
VIEW_PERMIT_CHECKOUT Allows user to see if another user can check out an item (should be true for all staff)
VIEW_REPORT_OUTPUT Allows user to view report output
VIEW_TITLE_NOTES Allows user to view all notes attached to a title
VIEW_TRANSACTION Allows user to see another users grocery/circ transactions in the Bills Interface
VIEW_USER Allows user to view another user's Patron Record
VIEW_USER_FINES_SUMMARY Allows user to view bill details
VIEW_VOLUME_NOTES Allows user to view all notes attached to a volume
VIEW_ZIP_DATA Allows user to query the zip code data method
VOID_BILLING Allows user to void a bill
VOLUME_HOLDS Allows user to place a volume level hold
VOLUME_UPDATE Allows user to edit volumes - needed for merging records. This is a duplicate of UPDATE_VOLUME; user must have both permissions at appropriate level to merge records.
actor.org_unit.closed_date.create Allows user to create a new closed date for a location
actor.org_unit.closed_date.delete Allows user to remove a closed date interval for a given location
actor.org_unit.closed_date.update Allows user to update a closed date interval for a given location
group_application.user Allows user to add/remove users to/from the User group
group_application.user.patron Allows user to add/remove users to/from the Patron group
group_application.user.sip_client Allows user to add/remove users to/from the SIP-Client group
group_application.user.staff Allows user to add/remove users to/from the Staff group
group_application.user.staff.admin.global_admin Allows user to add/remove users to/from the GlobalAdmin group
group_application.user.staff.admin.lib_manager Allows user to add/remove users to/from the LibraryManager group
group_application.user.staff.admin.local_admin Allows user to add/remove users to/from the LocalAdmin group
group_application.user.staff.cat Allows user to add/remove users to/from the Cataloger group
group_application.user.staff.cat.cat1 Allows user to add/remove users to/from the Cat1 group
group_application.user.staff.circ Allows user to add/remove users to/from the Circulator group
group_application.user.staff.supercat Allows user to add/remove users to/from the Supercat group
group_application.user.vendor Allows user to add/remove users to/from the Vendor group
money.collections_tracker.create Allows user to put someone into collections
money.collections_tracker.delete Allows user to take someone out of collections

4. Staff Client

4.1. Installation of the Evergreen Staff Client in Mac Environments

1. Fetch & install latest Xulrunner from here:


2. Fetch the staff client build directory you want to run.  For example:


3. Unpack the build directory somewhere, e.g. Desktop.

4. Open Terminal app and navigate to the directory where the "build" directory is sitting, then follow these steps (don't type the $'s):

$ cd ~/Desktop/
$ APPNAME=StaffClientKCLSProd
$  sudo rm -rf "/Applications/$APPNAME.app";
$ /Library/Frameworks/XUL.framework/xulrunner-bin --install-app build /Applications "$APPNAME.app";

You now have an application in your Applications folder called "StaffClientKCLSProd".  You can run it directly from there w/ the usual double-click. 

If you want to run the application with the console for debugging, continue like this:

$ cd "/Applications/$APPNAME.app/Contents/";
$ MacOS/xulrunner Resources/application.ini -console

To update, repeat steps 2-4, changing the APPNAME variable depending on which Evergreen server you want to talk to.  

4.2. Changing Workstation Name


In Linux, a hidden directory is provided of ~home/.openils/open_ils_staff_client/[random].default/chrome/.

The file you are looking for is ws_info. Delete this file, as it will be re-created when the next login occurs.

This login will force a new registration.



In Wine, change directory into the place your Evergreen Staff Client is located. This is usually ~home/.wine/drive_c/windows/profiles/[username]/Application\ Data/OpenILS/open_ils_staff_client/Profiles/[random].default/chrome/.

The file you are looking for is ws_info. Delete this file, as it will be re-created when the next login occurs.

This login will force a new registration.




On your computer, go into your "Documents and Settings" folder.

Go into the Application Data folder. If you don't see it, you'll need to go into Tools >> Folder Options >> View tab and turn on "Show hidden files and folders."

Go into the open_ils_staff_client folder.

Go into the Profiles folder.

At this point you will see another folder name. It will be a bunch of characters and letters followed by .default. Go into that folder.

Go into the chrome folder.

Now delete the file ws_info.


When you restart the staff client now, it should once again prompt you for your workstation name.


Uninstalling won't do it, since it hangs onto the config information.


5.1. Item was visible, but now I can't find it. Help!

In the event an item formerly visible in an OPAC seems to magically disappear, a simple question needs to be asked.


  • Can the item be located in the staff client via a cataloger permission, or by barcode in the database?


If NO, then consult with your Cataloger on staff.

If YES, then consider the following:

Every item, depending on its point in the Status cycle has an ability to appear or not to appear via config.copy_status in the database.

First, determine your current item's status through asset.copy in the column status. The integer provided corresponds with config.copy_status.id.

The row provided by this id with have four columns. The last, opac_visible, will determine if your item can be viewed in the OPAC or not.

Once this status changes, say from Reservation Shelf to Available, then your item will once again appear in the OPAC.

6. Self-Check in 2.0

6.1. Built in Self Check Basics

Q.) Is self checkout only accessible via a web browser or is there a client that can be installed?

A.) For self-checkout, the Firefox web browser is basically the client.  It could also be embedded in the staff client, but I don't see much point in that.

You'll need version 3 or greater for audio support.
Q.) Is the receipt printing setup similar to printing in the staff client (html template)?

A.) Self-check receipts are generated from HTML templates.  The mechanism is a little simpler in self-check than in the staff client.  It just formats the data based on the configuration and sends it to whatever printer is connected. 

Two things are needed to enable printing:

In Firefox, navigate to "about:config" and set the following setting to "true": signed.applets.codebase_principal_support

The first time you navigate to the self-check page, you will have to click through a series of warnings based on some preferences the self-check code sets.  Make sure you tell the browser to remember the decision to Allow the preference changes.

You will also need a code fix that I just committed.  You will get this with the next update (or I can manually patch if you are eager to test).
Q.) Does Equinox have a minimum hardware/OS requirement for self checkout?

A.) It's not a very heavy application, but I would recommend 512+ RAM.  Hardware/OS doesn't make much difference, as long as it can run Firefox.

7. Holds

7.1. Opportunistic and Targeted Holds with Staffing

7.2. Holds Boundaries

Hold Boundaries

7.3. Holds target eligibility

For a copy to be considered for a hold, the library must be opened (IE: no entry in asset.org_unit_closed or closed in actor.hours_of_operation), the copy must be circulate=true, holdable=true, reference=false, deleted=false, the volume must be deleted=false, , the copy location must be holdable=true and circulate=true.


Attached diagram from Grace

7.4. Status of -1 when displaying hold for specific patron

When displaying the hold status for a specific item on the record of a specific patron library staff may observe the status code of -1 for a status code.

This means that the item, and the hold on that item are in an inconsistent state. An example of this is when a hold is placed on an item that is currently checked out by another patron, or otherwise unavailable for the fulfillment of the hold. This status will change once the item is checked in, or otherwise made available for the hold to be fulfilled.

Status of this item can be checked in the database table asset.copy_status by selecting for the captured copy.

This is a normal operation, and not an error.

8. Searching

8.1. Search Relevancy

Version:1.0 StartHTML:0000000167 EndHTML:0000006750 StartFragment:0000000457 EndFragment:0000006734

Search Relevancy Ranking


The base relevancy score is determined by the cover density of the searched terms. After this base score is determined, items may receive score bumps based on word order, matching on the first word, and exact matches depending on the type of search performed.

Gory Details

The core relevance is based on the average, across the containing metarecord, of the cover density of the stemmed version of the searched terms in all matching record. heh... here's an example:

Metarecord (MR) 1 contains records (REC) 5, 6 and 7, and MR 2 contains REC 8.

Keywords for:

  • REC 5: "foo bar baz boo"

  • REC 6: "fee bar fie fo baz"

  • REC 7: "bar baz fee fo bar"

  • REC 8: "harry potter and the cowboy bar rowling j k"

User searches for "bar", which matches all of the above keywords. We score the individual matches:

  • REC 5: 0.9

  • REC 6: 0.8 (keywords are longer, so cover density is lower)

  • REC 7: 1.4 (matched twice, CD is higher)

  • REC 8: 0.6

Then, we get the average per MR:

  • MR 1 := AVG( 0.9, 0.8, 1.4 ) == 1.03

  • MR 2 := AVG( 0.6 ) == 0.6

That provides a base to work with, which we then augment with bonuses in specific cases. Bonuses, or "relevance bumps", are supplied as a multiplier to the base CD relevance on a per-record basis. They cause a small effect when only one of many RECs within a MR gain that bonus, but when most RECs gain that bonus they help to push the "best" MRs to the top of the list.

For subject and author searches, because the indexed strings are so short, and word order basically irrelevant, there are not special bonuses and we use the base CD ranking for relevance ordering.

For keyword searches, word order is important, because people generally type in phrases as they would speak them and the indexed strings are long enough for order to be relevant. With that in mind, we provide a bonus multiplier of 1.2 (20%) to the rank of each matching record where all of the words (unstemmed, but stripped of diacritics and lower cased) in the user's query are in the same order as they are in the searched field.

For series title searching, word order is less important, but the first indexable, non-article word and the possibility of a complete match are important. A first-word match (the first indexable word in both the query and the searched string are the same) provides a bonus of 1.5 (50%). If the entire series title, minus leading articles, matches the entire user query then we provide a very big bonus of 200.

Title searches, which search all titles but series titles, combine the relevance bonuses from keyword (word order) and series (first word and whole string) to provide very good matching, especially on very short titles which would otherwise have little chance of coming to the top, even thought they are the most likely target of a short title query.

9. Data extractions for union catalogs

10. My System...

10.1. is not running notices

This page is based on the idea that your Evergreen server has an active mail service, and an outgoing SMTP server to connect to. If these are fulfilled, check the following:

  • Verify that your definitions in action_trigger.event_definition are marked "true" rather than "false".
  • Check /openils/bin for the existence of action_trigger_runner.pl
  • Check /openils/conf for action_trigger_filters.json. It is possible that you may find a single file similar to this, but with the extension *.example. Copy this into a new file, minus the "example" suffix.
  • Check crontab and verify an entry with action_trigger_runner.pl
If these are all fulfilled, more troubleshooting may be necessary.