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

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