Settings - Circulation - Circulation Rules Editor

Information in italics is intended to provide guidance while writing documentation and in general should be removed when a doc is at a v.1 stage.
The italics are suggestions to help guide what might go in a particular section. If you feel a section does not apply to the app or feature, please keep the section but just add that it does not apply.
If you feel it makes more sense for your documentation, you can move sections up and down.

Purpose

Library staff can write their rules through a built-in circulation rules editor, available to staff in the Settings app through the FOLIO user interface. 

FOLIO provides its own circulation rules system with defined criteria and logic, allowing libraries to decide how their items circulate. Libraries can write rules to specify:

• which groups of patrons can borrow which items;
• different rules for items in different locations, libraries, campuses or institutions;
• what types of items (material types) can be borrowed;
• what types of items (loan types) can be borrowed;
• how many of a particular type of item can be borrowed (configured within Loan Policies)
• what notices are sent to patrons;
• what fines and fees are charged.

When a defined set of criteria matches a circulation transaction, the policies that are attached to that criteria are then applied.

The circulation rules for the FOLIO installation exist in one file. Rules can be written in a nested format, to make them easier to read; libraries can use keywords to  match on all or none for a particular criteria; and libraries can specify priority order for criteria if more than one rule matches.

Documentation on how to write rules can be found in the Github module at Circulation Rules

Considerations for Implementation

Describe decisions or implications that need to be considered when implementing this feature. Include topics such as order of operations during implementation or affects of implementing in a certain way.

1. Libraries should read the Github module documentation first before beginning to write rules: Circulation Rules - it will save a lot of pain during the troubleshooting process.
2. Associated criteria should be defined and implemented before beginning to write circulation rules. This includes
   1. Patron Groups: Settings - Users - Patron Groups
   2. Locations: Settings - Tenant - Location Setup
   3. Loan Types: Defined in inventory
      
   4. Material Types: Defined in inventory
   5. Overdue Fine Policies:  Settings - Circulation - Overdue Fine Policies
      
   6. Lost Item Fee Policies: Settings - Circulation - Lost Item Fee Policies
3. Libraries may find that it is better for a rule to specify more criteria than strictly needed. Example: Location criteria.
   1. Item effective location drives fine accrual - effective location connects to service point connects to Fee/Fine Owner.
   2. Item effective location may also be how libraries are used to thinking about restrictions on items themselves (e.g., "you can't recall an item on reserves.")
   3. Given these two factors, a rule may be easier to understand if you write it to include item location information, even if the rule would still work as desired without the location criteria being listed.
   4. On the other hand, adding criteria that's not strictly necessary may change how rules are prioritized and not be desirable.
4. Libraries wishing to use automated item blocks should follow these guidelines.

Permissions

The Circulation Rules editor does not have to be limited to tenant administrators or library IT.

Applicable permissions for users:

• Settings (Circ): Can create, edit and remove circulation rules

No action-based permissions currently apply to this section of FOLIO. If any are added, or if this is incorrect, please add them to this documentation.

UX/UI

Describe out of the box fields, including designed purpose, data requirements and validation, dependencies between fields. 
Describe out of the box accordion menus, including purpose of the menus, customization options, and associated permission controls (if any)
Describe any workflows available through navigation menus, including purpose of the workflow, customization options, and associated permission controls.

The circulation rules for the FOLIO installation exist in one file per tenant, accessible through the circulation rules editor.

The UI displays a box for typing in your circulation rules. The editor has responsive features to help write the rules. For example, typing a criteria letter will then display options for the criteria value, which you can select from the drop-down that appears.

Commenting in the rules file is possible - a hash or slash starts a line comment.

When adding a criteria in the location tree, the Editor will provide a tool to allow staff to pick from the location hierarchy, and then pull in the code value for you. 

Searching

There is a search box available for the Editor, but it is not currently working. See UXPROD-877 - Getting issue details... STATUS  for the status of this feature.

No other search features for this area of FOLIO are currently implemented. if this changes, please update this documentation.

Functional workflows

Describe available tasks that can be conducted in the app. To document those tasks, create a new page and link it to this page.
Describe action-based permissions that are connected to these functional workflows, if any.

Library staff will use the Circulation rules editor to create, edit, and delete circulation rules.

Documentation on how the circulation rules work is currently in Github at Circulation Rules

Reporting

Describe available in-app reports, including parameters for the reports, and associated permissions.
If there are developed LDP reports/queries for this app / area of FOLIO, describe those reports as well.
List any fields that may not be available in the LDP (e.g., for privacy reasons.)

Integrations

Describe any APIs that interact with the app. Provide links to the API / module information in Github.
Describe integrations that individual libraries may wish to develop for this app / area of FOLIO, if relevant.
If existing integrations have been developed by adopting libraries, provide links to the integration in Github or wherever the information can be found.