| Next revision | Previous revision |
| evergreen-admin:customization:indb-circ [2010/10/12 13:19] – created tsbere | evergreen-admin:customization:indb-circ [2022/02/10 13:34] (current) – external edit 127.0.0.1 |
|---|
| ======INDB Circulation (DRAFT)====== | ======INDB Circulation (DRAFT)====== |
| | |
| | WARNING: This has not been updated for various changes in 2.2+. |
| |
| =====Tables===== | =====Tables===== |
| |
| ^ Column Name ^ Column Description ^ Requires Version ^ | ^ Column Name ^ Column Description ^ Requires Version ^ |
| | grp | User Permission Group the matchpoint applies to | 1.6+ | | | grp | User Permission Group the matchpoint applies to (primary only)| 1.6+ | |
| | org_unit | Org Unit, owning and applied 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_owning_lib | Owning Library of the call number | 2.0+ | |
| | copy_circ_lib | Copy Circulation Library | 2.0+ | | | copy_circ_lib | Copy Circulation Library | 2.0+ | |
| | usr_home_lib | User Home Library (profile setting, not additional!) | In Patch | | | usr_home_ou | User Home Library | 2.1+ | |
| | is_renewal | Is this circ a renewal? | 1.6+ | | | is_renewal | Is this circ a renewal? | 1.6+ | |
| | juvenile_flag | Is the user flagged as juvenile? | 1.6+ | | | juvenile_flag | Is the user flagged as juvenile? | 1.6+ | |
| | usr_age_upper_bound | User maximum 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. | Then there are the "result values" that determine the circ parameters and if the circ is allowed. Pre-2.1 only the script test, hold ratio, and hard due date values could be set to null. In 2.1+ they can all be set to null for fallthrough purposes (though script_test does not fall through). |
| |
| ^ Column Name ^ Column Description ^ Requires Version ^ | ^ Column Name ^ Column Description ^ Requires Version ^ |
| | circulate | Is the item allowed to circulate | 1.6+ | | | 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+ | | | duration_rule | The id of the rule to use from config.rule_circ_duration | 1.6+ | |
| | recurring_fine_rule | The id of the rule to use from config.rule_recurring_fine | 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_fine_rule | The id of the rule to use from config.rule_max_fine | 1.6+ | |
| | max_renewals | The allowed renewal count | In Patch | | | hard_due_date | The id of the rule to use from config.hard_due_date | 1.6.2+ | |
| | grace | The number of allowed grace intervals (based on recurring fine period) | In Patch | | | renewals | Override for max renewals | 2.1+ | |
| | | grace | Override for grace period | 2.1+ | |
| | total_copy_hold_ratio | If there are holds, and ratio of copies to holds is less than this, deny circulation | 2.0+ | | | 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+ | | | available_copy_hold_ratio | If there are holds, and the ratio of available copies to holds is less than this, deny circulation | 2.0+ | |
| ^ Field ^ Description ^ Requires Version ^ | ^ Field ^ Description ^ Requires Version ^ |
| | success | True if circulation should go through, false if there is a failure | 1.6+ | | | 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+ | | | matchpoint | The ID of the most specific matchpoint found. This will be the only matchpoint pre-2.1. | 1.6+ | |
| | fail_part | String identifying why success was false | 1.6+ | | | fail_part | String identifying why success was false | 1.6+ | |
| | duration_rule | The ID of the duration rule matched | In Patch | | | duration_rule | The ID of the duration rule matched | 2.1+ | |
| | recurring_fine_rule | The ID of the recurring fine rule matched | In Patch | | | recurring_fine_rule | The ID of the recurring fine rule matched | 2.1+ | |
| | max_fine_rule | The ID of the max fine rule matched | In Patch | | | max_fine_rule | The ID of the max fine rule matched | 2.1+ | |
| | max_renewals | The max number of renewals | In Patch | | | hard_due_date | The ID of the hard due date rule matched | 2.1+ | |
| | grace | The grace period | In Patch | | | renewals | The renewals override (if any) | 2.1+ | |
| | buildrows | Ordered array of rows used to generate the above | In Patch | | | grace | The grace period override (if any) | 2.1+ | |
| | | buildrows | Ordered array of rows used to generate the above | 2.1+ | |
| |
| 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. | 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-2.1 the sole returned matchpoint is then loaded with fleshing to obtain results, 2.1+ loads the various pieces returned instead. |
| |
| fail_part can be one of the following, in order of return: | fail_part can be one of the following: |
| |
| ^ fail_part ^ Description ^ Requires Version | | ^ fail_part ^ Description ^ Requires Version | |
| | no_user | The user was not found - Bails out | 1.6+ | | | A Standing Penalty Name | The user has an active standing penalty preventing circulation | 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+ | | | actor.usr.barred | The user is barred | 1.6+ | |
| | asset.copy.circulate | The copy is set to not circulate | 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.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+ | | | asset.copy_location.circulate | The copy's location is set to not circulate | 1.6+ | |
| | | config.circ_matrix_circ_mod_test | The user has too many items out matching the circ mod rules | 1.6+ | |
| | | config.circ_matrix_test.available_copy_hold_ratio | The available copy count to hold count ratio is too small | 2.0+ | |
| | config.circ_matrix_test.circulate | The returned matchpoint has the circulate flag set to false | 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.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+ | | | no_item | The item was not found - Bails out | 1.6+ | |
| | A Standing Penalty Name | The user has an active standing penalty preventing circulation | 1.6+ | | | no_matchpoint | No matchpoint was found | 1.6+ | |
| | config.circ_matrix_circ_mod_test | The user has too many items out matching the circ mod rules | 1.6+ | | | no_user | The user was not found - Bails out | 1.6+ | |
| |
| =====Matchpoint Lookup===== | =====Matchpoint Lookup===== |
| 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. | 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: | ====Pre-2.1==== |
| | |
| | Pre-2.1 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 | - 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) | - 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: | - 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 | - 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 | - 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 | - is_renewal: 128 if set |
| - juvenile_flag: 64 if set | - juvenile_flag: 64 if set |
| - usr_age_lower_bound: 0.5 if set | - usr_age_lower_bound: 0.5 if set |
| - usr_age_upper_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! | ====2.1+==== |
| | |
| | By default the same general calculation is done in 2.1+ as in Pre-2.1, but with the addition of the user_home_ou field being treated like the copy owning and circ libraries. However, 2.1 includes Dynamic Weighting, which allows for the values used to vary by the value of the Context OU (org_unit). This also allows for the grp and org_unit fields to be less important than other fields for ordering purposes. |
| | |
| | In addition, in the event of a tie, 2.1+ does a final sort on the rule ID number, to ensure consistent sorting. |
| |
| =====Rule Migration===== | =====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. | ====To 2.0==== |
| | |
| | Migrating from 1.6 to 2.0 is a matter of doing nothing. All previous rules should function exactly as they did before, and you can begin to take advantage of the new fields available in 2.0. |
| |
| 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. | ====To 2.1+==== |
| |
| 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. | Migrating from Pre-2.1 to 2.1+ may result in different results in some cases due to the addition of fallthrough. While all your Pre-2.1 rules will include the circulate, duration_rule, recurring_fine_rule, and max_fine_rule values they may not contain hard_due_date, total_copy_hold_ratio, and available_copy_hold_ratio. If you are using these values in your Pre-2.1 rules at all then fallthrough may cause them to be applied where you do not want them to be. |
| |
| 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. | There are two quick solutions to this problem: |
| |
| If you rely on those distinctions in your rules then you will need to adjust your rules accordingly. | - For total_copy_hold_ratio and available_copy_hold_ratio you can set them to 0 for all matchpoints they are not set in. A value of 0 effectively disables them. |
| | - For hard_due_date you can create a dummy hard due date value (Such as "None") with a date in the past (such as 1970-1-31). Hard due dates in the past return to using the duration rule. |
| |
