Sharing (code) is caring

As some of you know, ESI is finishing the creation of FulfILLment, a new Open Source resource sharing program. FulfILLment, unsurprisingly, is based on Evergreen and because of their shared lineage they have each driven the development of features in the other.  For example, improvements in BibTemplate and metarecord holds from FulfILLment made their way back into Evergreen, and new backend search techniques and capabilities such as QueryParser, from Evergreen, found their way into FulfILLment.

One feature, Calculated Proximity Adjustment, has been on the wish list for Evergreen for a long time.  Put one way, it is the ability to encode policy-level information regarding lending priority for use with hold targeting.  For example, to be able to specify a lender-of-first-resort for a particular library branch or system when there is a special agreement between two Evergreen-participating organizations.  In the spectrum of Evergreen use-cases, this has always been seen as a nice-to-have, but has not received particular attention, nor funding.

However, this is critical to the successful functioning of FulfILLment, where knowing about this information may be necessary for fulfilling inter-consortial contractual agreements.  And, so, we have implemented it.  What’s more, because we know there are several use cases for Evergreen, we are in the process of side-porting this functionality.

Another development plan, Custom Best-Hold Selection Order, is something that has become of relatively great import for Evergreen.  As more libraries adopt Evergreen, the desire for more variation on the ideal order for hold capture becomes evident.  This has, to date, resulted in the FIFO Org Unit Setting and, to my knowledge, at least three local business logic customizations specifically for changing the semantics of hold selection at capture time.

In other words, best-hold order is now, or is in great danger of becoming, unmaintainable.  Therefore, Equinox is proposing a solution.  It’s not-trivial, but we have the plan well-laid, it is backward-compatible with what exists today, and we can complete it quickly.  What’s more, it goes well beyond simply allowing custom ordering of the hold selection fields available today and adds, among other things, a “holds-go-home” function.  That in particular is something we know many Evergreen users want.

Much like Calculated Proximity Adjustment was for Evergreen, this is something that we will side-port to FulfILLment because it will be useful, but it is not critical today.  See? Sharing is caring.

So, all of that to say, if the above are thing you’d like to see in Evergreen, and you’d like to see them sooner rather than later, and you’d like to see the code in Evergreen help other Open Source projects as well, and you are in a position to become a development partner, please contact me!

Mike Rylander,


Calculated Proximity Adjustment

Currently, 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.

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 and time 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


Evergreen can be made to provide a way to specify two types of proximity adjustment: Relative and Absolute.

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 configured circumstances.

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, or replacement Absolute Proximity, under configured circumstances.

In other words, through proximity adjustment you can manipulate the system into believing that other Org Units are either closer or farther than the hierarchy defines, allowing finer-grained control over hold targeting.


The FulfILLment project, an new inter-library resource sharing product based on the Evergreen source code and created by Equinox Software, has exactly this functionality today.  Equinox therefore plans to side-port this functionality from FulfILLment for the benefit of the greater Evergreen community.

This functionality in FulfILLment consists of several pieces of code involving the User Interface, the Middle Layer Logic and the Database.  All of this will be included in the side-port to Evergreen.

For the purpose of interacting with the functionality, a configuration interface exists allowing certain item-level 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)
  • Item circ modifier
  • Item shelving location
  • Hold pickup library (or ancestor thereof)
  • Hold request library (or ancestor thereof)

At least one criterion must be supplied.  These criteria are ranked by UI order, and reordering is allowed.

In addition to these criteria, an Absolute or Relative proximity adjustment is supplied.  For Absolute proximity adjustments, the best matching rule is used for each item being evaluated for a hold.  For Relative proximity adjustments, all applicable adjustments are added together, forming a total adjustment.  In the case that both an Absolute and one or more Relative adjustments are found for the currently evaluated item and hold, the Absolute proximity adjustment replaces the baseline distance and is then modified by the total Relative proximity adjustment.

See, for example, the below image.  By adding an Absolute Adjustment of 0 between NPL and SLO, items at either will be more likely to be targeted by holds at items at any other location because branches of the other are equivalent to local branches for the purpose of hold targetting.


To support both targeting-time and capture-time use of this derived proximity information, the calculated value is stored on the hold-copy map.  Hold selection performed at item capture time has been adjusted to take into account this new calculated proximity value.


Custom Best-Hold Selection Order

Evergreen currently has two best-hold selection sort orders for use at hold capture time:


  1. Proximity of capturing location to pickup library
  2. Group hold priority
  3. Hold cut-in-line
  4. Hold selection depth (deeper/narrower first)
  5. Hold request time


  1. Group hold priority
  2. Hold cut-in-line
  3. Hold request time
  4. Hold selection depth (deeper/narrower first)
  5. 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 controlled by a single Org Unit Setting to turn FIFO on or off.  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.


To that end, ESI proposes a new mechanism 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 will consist of a DnD or Multi-select list for ordering the options, a text entry for naming the definition, and a save button that will trigger inspection of the ordinal position of the options within the list.

This Org Unit Setting will be retrieved at capture time, instead of the FIFO setting, and inspected by the middle layer code responsible for selecting which hold to fill with the item being captured.  If no value is set, the equivalent of the “traditional” order will be used.

An upgrade script will change all FIFO Org Unit 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.

Additional Features

In addition to simply replacing the existing hold sort order options and allowing for trivial reordering of some options, this new functionality will add a set of new sort ordering options to extend the general functionality of Evergreen’s hold capture subsystem.  Among these new ordering options will be:

  • Home-Capture Proximity — the distance between the capturing location and the item’s home location
  • Home-Request Proximity — the distance between the item’s home library and the home library of the requesting user
  • Adjusted Proximity — with the side-porting of Calculated Proximity Adjustment from FulfILLment, the administrator-adjusted distance between item’s home library and the hold pickup library
  • Last Home Time Threshold Exceeded, or “Holds Go Home” — in combination with a new Org Unit Setting, the ability to elevate the priority of holds that are to be picked up at the item’s home library after the item has circulated away from its home for a specified amount of time