What Are Circulation Rules?

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:

• The groups of patrons that can borrow items.
• The rules for items in different locations, libraries, campuses, or institutions.
• The types of items (material types or loan types) that can be borrowed.
• How many of a particular type of item can be borrowed.
• The notices that are sent to patrons.
• The fines and fees that are charged.

Techie Tip: A much more detailed (and very technical) description of circ rules can be found in the FOLIO GitHub Circulation Rules documentation.

Who Can Edit Circ Rules?

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.

Circ Rule Components

A circ rule is made up of:

• Seven loan components related to libraries, patron groups, material types, loan types, locations, institutions and campuses; and
• Five policy components related to loan policies, notice policies, overdue fine policies, lost item fee policies, and request policies.

Each loan or policy component is represented by a letter code, shown in the charts below. (Unfortunately, the letter codes are not intuitive.)

Loan components:

Policy components:

Loan Component Order:

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:

1.     Loan Type (t)
2.     Patron group (g)
3.     Material type (m)
4.     Location (s)
5.     Library (c)
6.     Campus (b)
7.     Institution (a)

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

Circ Rule Order:

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

What Do Circ Rules Look Like?

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):

•   Line 1 tells Folio how the loan components are arranged, and what the rule hierarchy is (in our case, top down).
•   Line 6 lays out the default circ rule (called the “fallback” rule). This says that for ANY combination of loan components, apply the policy components named. ‘Any’ loan component is assumed because no loan components are named.
•   Lines 10, 11 and 12 spell out how to deal with SPEC and Carrel patron group transactions.

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.

How to specify exceptions to a circ rule:

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.

Can you enter multiple component values when writing rules and exceptions?

• Yes. Component values just need to be separated by spaces. For example, if you wanted to specify a certain rule for Library Card and Privilege Card holders, you could specify “g Library Card <…space…> Privilege Card.”
• You can use a “not” logical operator (“!”) to write a rule to exclude a given value (or values) for a loan component.
• After all the loan components are named, enter a colon to enter the policy components
• When naming locations (“s”) as part of a circ rule, you have to name the full location hierarchy (Institution, Campus, Library, Location). For example, this segment of a circ rule names the locations Mann Special Collections and Asia Rare Annex. “CU” is for institution, “IT” is for Ithaca campus, “MA” is for Mann Library and “ANX” is for Annex Library; “mnsc” is the location code for Mann Special Collections; and “asia-ranx” is for the location Asia Rare Annex:
  • + s CU>IT>MA>mnsc CU>IT>ANX>asia-ranx.
    • The right angle bracket separates the location hierarchy components, and a space (between ‘mnsc’ and ‘CU’) separates the locations themselves.

Rule Priority:

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.

Rule Nesting:

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.

Special filters:

Rules can use two special filters as part of their criteria; all and !.

•   The all filter means that all types should be excepted. For example ‘m all’ means ‘all material types’.
•   The ! filter means all types except the one listed. For example ‘p !staff’ means ‘all patron groups EXCEPT staff’

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 ‘:’.

How to find a rule being applied:

To figure what rule is being applied you need to know three pieces of information:

1.     The item’s Loan type
2.     The Patron group
3.     The item’s Material type

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.

1.     Starting with the Loan type look for the ‘t’ tag followed by the Loan type’s name. Is should not be indented or should be the first argument in a rule.
2.     Looking at the indented rules under this line find the Patron group (g).
3.     Next looking at the next level of indented rules look for the Material type (m).

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”

Reading a Policy:

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.

Compound Filters:

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. 

Editing Circ Rules

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’.

Troubleshooting

“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.