As described in FOLIO’s official documentation, circulation or circ rules are used to determine how items circulate. They follow FOLIO specific criteria and logic and are made up of one or more criteria and the policies to be associated with those criteria. When a defined set of criteria matches a circulation action, the policies that are attached to that criteria are then applied. Circulation rules can be written to determine the following:
Techie Tip: A much more detailed (and very technical) description of circ rules can be found in the FOLIO GitHub Circulation Rules documentation.
In order to edit circ rules, you must have the permission “Settings (Circ): Can create, edit and remove circulation rules.” At CUL, this is part of our Access Services Administrator permissions set. More information about our permissions can be found on the Cornell Library FOLIO Confluence page.
A circ rule is made up of:
Each loan or policy component is represented by a letter code, shown in the charts below. (Unfortunately, the letter codes are not intuitive.)
Loan Component Code | Loan Component Name | URLs for list of values for the loan components |
t | Loan Type | https://cornell.folio.ebsco.com/settings/inventory/loantypes |
g | Patron Group | |
m | Material Type | https://cornell.folio.ebsco.com/settings/inventory/materialtypes |
a | Institution | https://cornell.folio.ebsco.com/settings/tenant-settings/location-institutions |
b | Campus | https://cornell.folio.ebsco.com/settings/tenant-settings/location-campuses |
c | Library | https://cornell.folio.ebsco.com/settings/tenant-settings/location-libraries |
s | Location | https://cornell.folio.ebsco.com/settings/tenant-settings/location-locations |
Policy Component Code | Policy Name | URLs to view list of values for the policies |
l | Loan Policy | https://cornell.folio.ebsco.com/settings/circulation/loan-policies |
r | Request Policy | https://cornell.folio.ebsco.com/settings/circulation/request-policies |
o | Overdue Fine Policy | https://cornell.folio.ebsco.com/settings/circulation/fine-policies |
i | Lost Item Fee Policy | https://cornell.folio.ebsco.com/settings/circulation/lost-item-fee-policy |
n | Notice Policy | https://cornell.folio.ebsco.com/settings/circulation/notice-policies |
The order in which the loan components are listed establishes the hierarchical pattern for circ rules (which tells FOLIO how to interpret rules). At Cornell, we have chosen the following hierarchy:
Techie Tip: a detailed explanation of loan component order can be found in GitHub documentation: https://github.com/folio-org/mod-circulation/blob/master/doc/circulationrules.md#criterium-type-priority
The order in which the circ rules are listed determines how FOLIO applies the rules. The rules are hierarchical (from top down). FOLIO evaluates the rules for a given transaction in the order that the rules are presented. The first rule that matches the combination of factors in a transaction will be the rule that’s applied. If something doesn’t match, FOLIO will keep going until it finds the rule that does match. If no rule matches, the fallback rule is applied.
The overarching rules (highest priority rules) are at the top of the list – this includes the fallback rule (the one that is applied if no other rule matches the combination of factors of a loan) and rules for SPEC and Carrel cards.
Techie Tip: a detailed explanation of rule order can be found in GitHub documentation: https://github.com/folio-org/mod-circulation/blob/master/doc/circulationrules.md#line-number-priority
If you have permissions to view Settings, the entire list of circ rules can be found at: https://cornell.folio.ebsco.com/settings/circulation/rules
Here is a screen capture of the first few lines of the circ rule set (as of 10/8/21, there are 274 lines of circ rules, including blank lines inserted for clarity):
NOTE: You will find grayed-out lines throughout the circ rules. These are just comments to make the encoded rules more understandable to mere humans.
For any given circ rule, you can specify exceptions by indenting the next line (with one tab space) and then spelling out the loan components that make the exception (and indicating what policies to apply in that circumstance).
It’s important to remember that the lines above the exception will be followed until the exception circumstance is encountered.
This is how FOLIO decides what rule to apply to a loan. The rule priority is from top to bottom, meaning that rules at the top of the page will override the ones below it; even if they match the same criteria.
Example:
1: All Staff are allowed to check out items for 1-year
2: All students are allowed to check out items for 6-months
3: All staff are allowed to check out items for 2-years
Lines 1 and 3 would both match an item being checked out to a staff member, but FOLIO would use the rule on line 1 because it is before the third rule.
FOLIO allows rules to be nested by indenting a new rule below it. When we do this the second rule further narrows the scope of the first rule, but also applies new policies. Think of the indent as adding ‘AND’ to the criteria of the first rule. Here is an example in plain text.
1: All items with the material type of ‘Circulating’ should have a loan period of 0
2: Staff should have a loan period of 1-year
In line 1 we are setting a rule that would apply to all items with a material type of ‘Circulating’. This rule is very restrictive as it does not allow the item to circulate. Because line two is indented it is narrowing the scope of the first rule and applying new policies. In this example, line two would be interpreted by FOLIO as:
All items with the material type of “Circulating” AND patrons categorized as staff should get a loan period of 1-year.
Rules can use two special filters as part of their criteria; all and !.
How to Read Circ Rules
Rules are written using the nesting function as described above. The first rule added is for the Loan type followed by Patron group, Material type, and finally special exceptions.
The first part of the rule is the filter, the second half is the polices applied to items that match that filter. Rules are separated from the polices using ‘:’.
To figure what rule is being applied you need to know three pieces of information:
For our example let’s look for an item that has a Loan type of ‘3-hour loan’, a material type of Laptop and is being checked out to a Faculty member.
The policies listed after this rule will be the ones that are applied to the loan.
Q: What if there is no rule listed for that Material type, or Patron group.
A: Using the example above instead of looking for the Material type of ‘Laptop’ we are now looking for the Material type ‘Book’. Since there is no rule for ‘m book’ listed under the Patron group rule FOLIO would apply the last rule it was able to match. In this example that would be #2 the Patron group.
Techie Tip: if you copy and paste the circ rules into a Word document, you can use Ctrl-F to search by keyword (e.g. find every instance of loan type “3-hour-loan”
Each rule has five polices that are applied:
n; Notice policy – What notices will be sent during the life of the loan*.
o; Overdue fine policy – What overdue fines should be charged, including overdue recall fines.
i; Lost item fee policy- Replacement cost, and processing costs to be applied to items aged to lost or marked as lost
r; Request Policy – If a patron can recall, place a hold on or page an item.
l (L); Loan policy – What loan policy should be applied, including: loan period, renewals allowed, calendar to be used etc.
*Notices are scheduled when a loan is created, or renewed. If you change a notice policy for a rule it will only apply to items checked out or renewed after the policy was changed.
The majority of the rules are written using the method describe above. There are a few rules at that use compound filters where multiple criteria are stringed together using +. For example:
1: t all + m all + g carrel : policies to be applied
This filter is the same as:
1: t all : policies to be applied
2: m all : policies to be applied
3: g carrel: policies to be applied
Q: So why aren’t all the rules written this way if FOLIO will interoperate them the same?
A: The main reason for the difference is readability. Although the two rules above would result in the same polices the second method is more readable. This method also allows new polices to be added more easily.
Using the directions above locate rule you wish to change. Using the chart above locate the policy you wish to change; in this example we will change the (n) notice policy. Delete the policy name represented in purple.
Delete the policy name leaving only the key; n in this case. You will notice a small floating dialog below your course while removing the old name and in the previous step. The names in this dialog represent all the possible policy names that can be applied for the policy type you are entering.
Simply select one of the policy names and FOLIO will enter that name for you.
After you have updated the policy you should update the note above the policy so it matches. When you are finished click on the ‘Save’ button.
Q: Can I enter more than one policy for a given type, for example can I enter two notice policies?
A: No, you can only enter a single policy for each category.
Creating New Circ Rules
Now that you know how to read rules and add change policies you have the tools to write a new rule. If possible you should add the new rule as a filter to another rule. For example we created a new equipment Material type called ‘Adapters’. Instead of creating a bunch of new layers it would be easier to just insert it under the other equipment rules. Remember we want to keep the rules as readable as possible for others that may have to read them.
The first part of the rule we enter is the filter, so using our new Material type from above we would add the following:
221:
222:
223: m adapters :
224:
In this example m tells FOLIO we want to filter on a Material type and ‘adapters’ is the name of that material type.
As for the policies lets apply the same policies as we used for supplies. The new rule would look like this:
221:
222:
223: m adapters : n hourly-loan-notices o no-fine-default i equipment-repl-25 r no-requests l 3-hours-due-3-hrs-after-opening
224:
Please refer above to the five different policy types that need to be assigned to each rule. FOLIO does not require polices to be added in a specific order although for readability we enter polices in the following order:
m – Notice policy, o – Overdue fine policy, I – Lost item fee policy, r – Request policy, l – Loan policy
Finally, we want to add a note to the policy. This is done by starting a line with /. We want to describe the filter being applied and the polices being used for that rule.
221:
222: / (m) Equipment – Adapters set to (l) 3-hours due 3-hrs after open, (r) no requests, (i) $25 equipment replacement fine
223: m adapters : n hourly-loan-notices o no-fine-default i equipment-repl-25 r no-requests l 3-hours-due-3-hrs-after-opening
224:
The last step is to hit ‘Save’.
“The Policy n does not exist” – This error is given when you try to save Circulation rules but there is a policy referred to that does not exist in FOLIO. The error message will appear after the rule in question and in this example ‘n’ referrers to the Notice policy piece of the rule.
*If there is an error the new Circulation rules will not be saved.
The policy isn’t highlighted – If a policy is entered correctly it will be highlighted in purple. If this is not happening it usually means that the policy name is not correct. In the example below the policy name has been accidently combined with the key (n)
“Must contain one of each policy type, missing type ..” - This warning will appear if one or more of the required polices are missing from a rule. Remember from above all five polices must be assigned to a filter in-order for it to work correctly. In this example the Notice policy (n) is missing.
Instead of a name there is random test – This happens when a policy has been removed from the system and is still being referenced by a circulation rule. There are safeguards in place to help prevent this, and if you notice this sort of error it should be brought to attention.