Through the Looking-Glass:
In-Database Approach for Circulation/Hold Policy Configuration

The tables config.circ_matrix_matchpoint and config.hold_matrix_matchpoint are central to the configuration of in-database parameters. They collect the main set of data used to determine what rules apply to any given circulation or hold repsectively. 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 or hold transaction, and “result” columns, those that return the various parameters that are applied to the matching transaction.

config.circ_matrix_matchpoint

config.hold_matrix_matchpoint

Higher numbers imply a higher weight, so columns with a higher value in their weights table will have precedence over columns with a lower value. This is a useful way to break ties, if all other considerations between two potential matchpoints are equal.

For circ_weights the org_unit in the weight_assoc table corresponds to the org_unit column in config.circ_matrix_matchpoint.

For hold weights, the org_unit corresponds to either the copy’s circ_lib or the call number’s owning_lib depending on the setting of the circ.holds.weight_owner_not_circ internal flag. If that flag is enabled, the call number owning_lib is used.

There is an interface in the gui for editing these, but it is broken as of this writing (20120419). There is a bug report with a potential fix available.

The GUIs can be found in the staff client on the Server Administration submenu of the Admin menu. The specific menu options are:

Let’s say that 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. This situation might look like this:

Fall through is rather hard to explain, but it is a rather simple concept once you grasp it. It works a lot like cascading style sheets.

It is perhaps easiest to think of fall through as working the org unit level. Let’s assume that we have constructed a set of circulation matchpoints that apply at the consortium. We could consider these matchpoints as representing default circulation rules for our consortium. Let us also assume that our consortium has decided on some common policies regarding loan periods and number of renewals for most materials but that we don’t have uniformity on overdue fines for various political reasons. If most of our members actually don’t charge fines, then it makes sense to set up a matchpoint for regular books at the consortium org unit that has all of the basic parameters and an empty recurring fine rule. If one of our members uses all of the basic parameters for book circulation, but charges 25 cents a day to a maximum of $3.00 for fines, then fall through allows us to configure only those two field for that library’s book matchpoint. The rest of the rules will fall through to the consortium’s matchpoint.

Fall through works similarly for branches and systems as well. If all members of a system use the same circulation rules, then you need only configure the rules at the system level. If, however, 1 branch needs something special for some reason, you can configure only those fields that differ from the system or consortium for that one branch.

The default rules for recurring fines and circulation durations that ship with Evergreen have different values for the 3 “levels.” For instance, the intervals for circulation duration are 7 days, 14 days and 21 days respectively. Our members' staff seemed to find this idea confusing, so we created additional rules to cover our particular use cases where all three values were the same. If you look at the pre-existing rules in the editor, you’ll see that the first 10 entries follow this pattern and the “default” entry is the only one with 3 different values. I suggest making all three values the same for your circulation duration rules as well as your recurring fine rules. This helps avoid confusion with library cataloging and circulation staff.

Age hold protection has caused (and continues to cause) some confusion in our consortium. Part of the blame with that lies in the fact that its operation was explained to us at it functions when using scripted circulation parameters and not how it works with in database rules. With in-database rules, only the age hold protection rule applied to the copy (or in the future, the matchpoint applies). This means that if you set a 3-month age hold protection at the system level on a copy, then the copy will only have age hold protection at the system leve for those three months. There is no cascade effect with age hold protection when using the in-database circulation.

The “old” way is fairly simple. It requires that you base all of your circulation limits on circulation modifiers, so you’re encouraged by this method to use circulation modifiers as “circulation types.”

You can add multiple circ_matrix_mod_test_map entries with different circ_mod values and the total of the copies with those circ_mod values will be counted. Thus, if you were using circulation modifiers to track different types of DVDs (DVD, HOTDVD, RENTALDVD, for instance), you could have a limit of 10 DVDs that included the counts from all three types, and two separate limits that allow say 3 RENTALDVD and 1 HOTDVD.

The new way still can do everything that the old way does. In fact, the upgrade script for 2.1 to 2.2 will convert your circ_matrix_mod_test_map entries to the new way of doing things.

This new method of configuring limits offers much more flexibility over the old way. You can now configure limits without requiring a circulation modifier to set the the limits. You can enable fallthrough on the limits so that the limit will apply to any matching circulation. You can set organizational unit depths at which the limits apply, so it is easier to set up limits that apply consortium-wide or at just a single system or branch. If your limit set does not require a circulation modifier it is also possible to set a tag only rule so that circulations are tagged for future use. (This is, in fact, the recommendation of the developer who added the new way of handling limits.)

Helper functions make creating certain complicated rules easier. Typically, you’d write them such that they provide default arguments for most parameters, and so you can use shortnames or names instead of database ids.

TODO Create helper functions for the “new” way.

Notes plagiarized from the developer who plans to do the work.

Updated Editors

At this point I plan on replacing the existing editor interfaces with more “TPac-like” editors, that is generated server side. This will allow a lot more flexibility in overall display, will permit more complicated sorting, and will make it easier to implement things like filtering.

My overall goal is to always sort the way they will be used, but allow filtering on anything that affects what rules are in use.

Custom Failure Codes

Not much to say here. Instead of the generic failure code of “we said no” I plan on having custom failure codes that permit things like “This is a Local Use Only patron” and such. As a side benefit, these custom failure codes will also be able to get custom override permissions, allowing much more granular override options.

Split “grouped” failure reasons into individual codes

It is very hard to provide granular control over overrides when a half dozen failure reasons all get the same code, and thus the same override permission. Splitting them up will help with that. Dealing with upgrade scripts (as in, what to do about who gets the new override permissions, mainly) is a different matter.

Failure Scopes

At the moment all overrides for circulation are “do you have permission at the circ desk you are standing at” when they are checked. I want to change this so that, for example, you can say “do you have permission at the item’s owning library” and similar, to give greater control over who can override what.

Importance/Manual Ordering

Some people want a lot of control over the ordering of the matrix, and weighting doesn’t give them enough control. This field would allow for all else to be considered equal and an explicit numerical order to be applied. Or, in the case of normal configurations, it would allow for fine adjustment of otherwise equal rules.

Comments/Notes Field

I mainly want to put this in for when you go to edit a rule, so you can see what someone else who edited it might have been thinking when they did so. Or put a warning not to mess with the rule for whatever reason, etc.

Relative Org Units

Similar to the current strict org unit checks, I see it as being potentially useful to be able to say things like “The User’s Home Library is the same as the Item’s Circ Library” and similar, possibly with the following variants:

Adding copy locations to the limit sets means that you would be able to limit the number of copies that a patron can have checked out from a given copy location. This way you could put your new books or bestsellers in a copy location and limit that way, rather than having a circulation modifier or having to configure all of the MARC specifics.

Context Field in the circulation matrix

Sometimes you want the rules for a circulation to differ depending on where the circulation is being triggered from. Allow renewals, but not OPAC renewals, or allow checkout but not at the self check, that kind of thing. This field would allow for those differences by allowing filtering based on which interface the circulation is happening at.

Capture holds at circulation library only

This flag would cause the hold matchpoint to only capture the hold if the copy being considered is presently at its home library (‘asset.copy.circ_lib`). One example where this would be useful is how the Merrimack Valley Library Consortium handles statewide virtual catalog requests. Our policy is for members to transit other libraries’ materials home rather than sending them in transit to the statewide VC when these holds trigger. This additional transit often results in the hold expiring before the copy gets home. Setting this flag would prevent the hold from taking place until the copy gets home, thus improving that situation.

At the moment HOLD_EXISTS is only checked at the final place hold step. This means that if any other override has been requested we may silently override the HOLD_EXISTS failure as well.

By checking for it at “can this be placed” time we get a better picture of why placement might fail overall.

Stalling Start

Currently stalling starts at hold placement, which means that patrons who place suspended holds bypass stalling when they re-activate the holds. This would allow for holds to flag when they were placed or unfrozen and use that as the start of the stalling period instead, possibly with a global flag to turn it on and off.

Overrides

At this point I have too many issues with storing overrides, but I feel that the full list of reasons a hold could not be placed, in groups by the copy that generated them, should be returned to the UI layer. Otherwise you don’t get enough information to make a decision about overriding.

Parts

Parts can cause a lot of issues, and don’t seem to be as useful/powerful as they could be. The easy solution is to add optional fields to the parts themselves. Without the fields filled in the system will act identically, but once supplied the system will act upon the information.

Default Part

By adding a “default” flag to parts, with a limit of one per bib, we can support older and/or on order title holds (by assuming the default part flagged copies can fill them) and allow for partless copies to fill holds on the default part (by assuming no part is the default part). In addition, this could be used to auto-select the default part when placing a hold, and disallow title holds when there is a default part.

Subparts

Adding subpart designators to the system will allow part holds to be filled by copies that contain the part in question. Interface wise it may be possible to provide “auto-subpart” routines where ranges are involved to automatically build and populate subpart information for new and existing bibs.

Age protection is a hot topic, where different groups want different things where age protection is concerned. Some want to match on the user’s home library, others on the circ library, some want cascading rules and others don’t. By adding two new fields to the hold matrix we can permit a lot of these configurations.

The first is a “Match the Age Protect rule on the copy” field, where you select the age protect rule to match. This allows your rules to take into account what the cataloger has put on the copy for age protection.

The second is a “Bypass Copy Age Protection” result field that tells the system to not do the normal copy level age protect checks, allowing the matrix itself to provide that. This also allows for staff (or any other group) to not be subject to age protection for any reasons desired.