This is an old revision of the document!
Table of Contents
INDB Circulation (DRAFT)
Tables
config.circ_matrix_matchpoint
The circ matrix matchpoint table could be seen as being split into several sections. Over time features are added, and thus a version for when the column was added is included.
To start with, every row has an id and whether or not it is active:
| Column Name | Column Description | Requires Version |
|---|---|---|
| id | Matchpoint ID | 1.6+ |
| active | Is matchpoint active? | 1.6+ |
Then there are the "match values". With the exception of grp and org_unit, every one of these can be null to indicate that they don't matter. The most basic rule thus only sets grp and org_unit.
| Column Name | Column Description | Requires Version |
|---|---|---|
| grp | User Permission Group the matchpoint applies to | 1.6+ |
| org_unit | Org Unit, owning and applied to | 1.6+ |
| copy_owning_lib | Owning Library of the call number | 2.0+ |
| copy_circ_lib | Copy Circulation Library | 2.0+ |
| usr_home_lib | User Home Library (profile setting, not additional!) | In Patch |
| is_renewal | Is this circ a renewal? | 1.6+ |
| juvenile_flag | Is the user flagged as juvenile? | 1.6+ |
| circ_modifier | Copy Circulation Modifier | 1.6+ |
| marc_type | Copy circ as type if set, otherwise rec descriptor item type | 1.6+ |
| marc_form | rec descriptor item form | 1.6+ |
| marc_vr_format | rec descriptor videorecording format | 1.6+ |
| ref_flag | Copy reference flag | 1.6+ |
| usr_age_lower_bound | User minimum age based on DOB | 1.6+ |
| usr_age_upper_bound | User maximum age based on DOB | 1.6+ |
Then there are the "result values" that determine the circ parameters and if the circ is allowed. Pre-patch only the script test and hold ratio values could be set to null. Post-patch they can all be set to null for fallthrough purposes.
| Column Name | Column Description | Requires Version |
|---|---|---|
| circulate | Is the item allowed to circulate | 1.6+ |
| duration_rule | The id of the rule to use from config.rule_circ_duration, Pre-patch this includes the renewal count | 1.6+ |
| recurring_fine_rule | The id of the rule to use from config.rule_recurring_fine | 1.6+ |
| max_fine_rule | The id of the rule to use from config.rule_max_fine | 1.6+ |
| max_renewals | The allowed renewal count | In Patch |
| grace | The number of allowed grace intervals (based on recurring fine period) | In Patch |
| total_copy_hold_ratio | If there are holds, and ratio of copies to holds is less than this, deny circulation | 2.0+ |
| available_copy_hold_ratio | If there are holds, and the ratio of available copies to holds is less than this, deny circulation | 2.0+ |
| script_test | Currently unused(?) | 1.6+ |
config.circ_matrix_circ_mod_test
The circ matrix circ mod test table is used to limit checkouts by circ modifier or circ modifier set. It has so far remained unchanged since 1.6.
| Column Name | Column Description |
|---|---|
| id | Circ Mod Test ID |
| matchpoint | Linked matchpoint from config.circ_matrix_matchpoint |
| items_out | Max number of items out for this test |
config.circ_matrix_circ_mod_test_map
The circ matrix circ mod test map table links circulation modifier values to the test table
| Column Name | Column Description |
|---|---|
| id | Circ Mod Test Map ID |
| circ_mod_test | Linked circ mod test from config.circ_matrix_circ_mod_test |
| circ_mod | The Circulation Modifier from config.circ_modifier.code |
Circulation Rules/Allowed Check
Lookups are done by way of a call to action.item_user_circ_test or action.item_user_renew_test. Each of these takes three parameters:
- The Context OU, where the circulation is occuring, as an integer
- The item to be circulated's database ID
- The database ID of the user the circulation is for
They then call a second variant of action.item_user_circ_test. This one takes a fourth parameter for "is a renewal", which is only set to true in the action.item_user_renew_test variant. No other information is passed in, and all decisions must then be made with those few pieces of information or information that can be gathered by using them.
action.item_user_circ_test returns a set of data:
| Field | Description | Requires Version |
|---|---|---|
| success | True if circulation should go through, false if there is a failure | 1.6+ |
| matchpoint | The ID of the most specific matchpoint found. This will be the only matchpoint pre-patch. | 1.6+ |
| fail_part | String identifying why success was false | 1.6+ |
| duration_rule | The ID of the duration rule matched | In Patch |
| recurring_fine_rule | The ID of the recurring fine rule matched | In Patch |
| max_fine_rule | The ID of the max fine rule matched | In Patch |
| max_renewals | The max number of renewals | In Patch |
| grace | The grace period | In Patch |
| buildrows | Ordered array of rows used to generate the above | In Patch |
If success is true only one row should be returned. If success is false one or more rows may be returned, depending on the number of failure points. Pre-patch the duration_rule, recurring_fine_rule, max_fine_rule, and max_renewals are obtained by looking up the matchpoint ID. Renewals is part of the duration rule, grace period doesn't exist, and buildrows is for potential debugging output and is not normally used.
fail_part can be one of the following, in order of return:
| fail_part | Description | Requires Version |
|---|---|---|
| no_user | The user was not found - Bails out | 1.6+ |
| no_item | The item was not found - Bails out | 1.6+ |
| no_matchpoint | No matchpoint was found | 1.6+ |
| actor.usr.barred | The user is barred | 1.6+ |
| asset.copy.circulate | The copy is set to not circulate | 1.6+ |
| asset.copy.status | The copy is in the wrong status | 1.6+ |
| asset.copy_location.circulate | The copy's location is set to not circulate | 1.6+ |
| config.circ_matrix_test.circulate | The returned matchpoint has the circulate flag set to false | 1.6+ |
| config.circ_matrix_test.total_copy_hold_ratio | The total copy count to hold count ratio is too small | 2.0+ |
| config.circ_matrix_test.available_copy_hold_ratio | The available copy count to hold count ratio is too small | 2.0+ |
| A Standing Penalty Name | The user has an active standing penalty preventing circulation | 1.6+ |
| config.circ_matrix_circ_mod_test | The user has too many items out matching the circ mod rules | 1.6+ |
Matchpoint Lookup
The matchpoint used for the circulation rules above is located, or built, by action.find_circ_matrix_matchpoint. This function takes the context ou, the item's database ID, the user's database ID, and a boolean stating if the circulation is a renewal. It then searches the config.circ_matrix_matchpoint table for a corresponding matchpoint (or matchpoints) to return back to action.item_user_circ_test.
With the exception of the user's permission group and the context org unit all of the "match values" can be set to null to indicate that the rule isn't limited to something matching them. This means it is a good idea to always have at least one rule set to the top of the user permission tree and the top of the organizational unit tree with no other match values set that defines the overall defaults for in the event no other rule matches.
The various match values are weighted in a somewhat strict fashion:
- User's Permission Group (grp) - Used as the outermost check, the matchpoint finding "walks" up the user permission group tree starting at the permission group in the user's profile
- Context OU (org_unit) - Used as the second check, by increasing proximity (0 is exact match and is first, parent is 1, parent of parent is 2, etc)
- In Patch: Copy Owning and Circ Libraries and User Home Library (copy_owning_lib, copy_circ_lib, usr_home_lib) - Add up the proximities of each to the setting in the matchpoint (or 6 if null) and place in increasing order
- Weighted values - In Descending order of weight added up from the following:
- Without patch: copy_owning_lib - 256/(proximity + 1) - exact match will be weight 256, parent will be weight 128, parent of parent will be weight 85.3, etc
- Without patch: copy_circ_lib - 256/(proximity + 1) - exact match will be weight 256, parent will be weight 128, parent of parent will be weight 85.3, etc
- is_renewal: 128 if set
- juvenile_flag: 64 if set
- circ_modifier: 32 if set
- marc_type: 16 if set
- marc_form: 8 if set
- marc_vr_format: 4 if set
- ref_flag: 2 if set
- usr_age_lower_bound: 0.5 if set
- usr_age_upper_bound: 0.5 if set
- In patch: Tiebreaker is matchpoint id, lower id wins (rule 1 will beat rule 2+, rule 2 will beat rule 3+, etc, assuming all other sorting criteria are identical)
Before the patch the first matchpoint found that matches all non-null match value fields in the above sorting is returned. After the patch the "result values" that are null are attempted to be filled in from second/third/fourth/etc matchpoint rows. Take note that only the first matchpoint is used for circ modifier limit checking in either case!
Rule Migration
Migrating rules from 1.6 to 2.0 or to the post-patch rules is simple, as everything that changes is an addition. After that rules can be examined for fallthrough simplification based on the sorting rules, or for adding additional information to the rules.
Migrating rules from 2.0 to post-patch is simple if you are not using the copy owning or circ library settings, as they will map directly and without changes. When you are using the copy owning or circ library settings, however, the resulting ordering will change in some cases.
If your copy owning library settings are on rules at the same level your call numbers are defined at then you will see no difference in their ordering. The same goes for copy circ library settings that are on the same level as the item circ location. It is when these settings are higher on the tree than on the call numbers or items that differences may be noted.
In particular, is_renewal as a flag becomes of equal value to either when they are at one org unit above the call number or item org unit, and juvenile_flag becomes of equal value when they are three org units above the call number or item org unit.
If you rely on those distinctions in your rules then you will need to adjust your rules accordingly.