Fee/Fines - Data Structures

Definitions

In Folio, fee/fine information is stored as accounts and actions. An account is the umbrella object that is created with a particular charge. An action is always associated with an account, and is where transactions related to a particular charge are stored.

The Account json schema can be found here: https://github.com/folio-org/mod-feesfines/blob/master/ramls/accountdata.json

The Action json schema can be found here: https://github.com/folio-org/mod-feesfines/blob/master/ramls/feefineactiondata.json

With Orchid, FOLIO begins supporting Actual cost for lost items, which introduces a new record type of the Actual Cost Record, which allows library staff to review the list of actual cost items and apply the appropriate charge:

https://github.com/folio-org/mod-feesfines/blob/master/ramls/actual-cost-record.json

Example

For example, suppose patron Julia Smith fails to return a book on time before it ages to lost. Julia is charged $100 as an automated fee/fine. They come in and pay $50 by cash, and the library elects to waive the other $50. In the underlying fee/fine data, that looks like this:

One account object, representing the $100 charge, and containing links to Julia's record in Users, the fee/fine owner and fee/fine type, and item information.
Three action objects, that would look like this:
- Action #1 represents the $100 charge to Julia, with an action type of "Outstanding"
- Action #2 represents the Julia paying $50, with an action type of "Paid Partially."
- Action #3 represents the library waiving the final $50, with an action type of "Waived partially." This final action results in an amount owed of $0, and when the action occurs, it charges the account's status to Closed.

If the library waived $50 first, and then Julia paid the $50 after that, action #2 and #3 would be flipped in order, but the result would still change the Account to closed.

Things to know about Accounts

An individual account record has a required userId - that's how it's linked to the user record
An individual user may have zero, one, or more accounts - e.g., if they've never had a fine charged, they would have no account records.
Accounts have feeFineId and ownerId - this links to the fee fine owner, and the type of fee/fine that was charged. Types of fines are configurable for manual charges in Settings → Users → Fee Fines. For automatic charges, they are configured in FOLIO itself. Types of fee/fines in the system can be retrieved via an API call (GET /feefines)
Note that as of Honeysuckle, a materialTypeId and itemId must be provided, even if you are not trying to tie a fee/fine to an individual item. When creating a fee/fine, you will have to set a value for those attributes no matter what. The FOLIO UI uses "0" as a value if no item is provided. See UIU-2070 - Creating a manual fee/fine requires an itemId and materialTypeId even if the manual fee/fine is not being associated with an item OPEN for the status of this issue.
Hardcoded attributes (with allowed values) include:
- Status
  - Open
  - Closed
- Payment Status
  - Outstanding
  - Paid partially
  - Paid fully
  - Waived partially
  - Waived fully
  - Transferred partially
  - Transferred fully
  - Refunded partially
  - Refunded fully
  - Cancelled as error

Things to know about Actions

Accounts will always have at least one action, created when the account was created.
If an account has been paid, it will have at least two actions - the one created that shows the initial charge (with a type of "Outstanding",) and then the one that resolves the charge ("______ fully").
A feefineactiondata record has a required attribute of accountId which links it to the account.
Hardcoded attributes (with allowed values) include
- TypeAction
  - Outstanding
  - Paid partially
  - Paid fully
  - Waived partially
  - Waived fully
  - Transferred partially
  - Transferred fully
  - Refunded partially
  - Refunded fully
  - Cancelled as error
  - Staff info only