Skip to end of metadata
Go to start of metadata

This script fixes several issues in encumbrances related to the fiscal year rollover for FOLIO Lotus. In particular, after a fiscal year rollover in Lotus, there can be a mismatch between budget encumbrances and purchase order encumbrances.

Do I need to run this script?

If you know one or more of the following things to be true about your system you will want to run this script.

  • The system was rolled over while running the Kiwi or Lotus flower versions
  • Our system contains one or more encumbrance transactions with an amount >0, but an encumbrance status of Released. These will generally be associated with ongoing orders based on how libraries generally use the Rollover function, but this issue could have occurred with any order type.
  • There are encumbrances in the system related to closed orders that have an order status of Open. This status is captured in the encumbrance data but is not shown in the UI so it would be difficult to notice.

Script logic

  • Fix the orderStatus property of encumbrances for closed orders. In order to do this, the encumbrances have to be unreleased first and released afterwards because it is not possible to change this property for released encumbrances.
  • Change the encumbrance status to Unreleased for all open orders' encumbrances with non-zero amounts
  • Recalculate the encumbered property for all the budgets related to these encumbrances by summing the related unreleased encumbrances.
  • Release all unreleased encumbrances for closed orders


  • python3 with required packages that can be installed via pip (asyncio, requests)
  • user with required permissions
    • finance.budgets.collection.get
    • finance.encumbrances.item.put
    • finance.fiscal-years.collection.get
    • finance.order-transaction-summaries.item.put
    • finance.transactions.collection.get
    • finance.transactions.item.get
    • finance-storage.budgets.item.put
    • orders.collection.get

Before running

  1. The script should not be used before a rollover in Lotus (because if it was, encumbrances would not be created for closed orders, and they could not be reopened - see MODORDERS-706). It can be used after a rollover for all ledgers, or just before migration to Morning Glory. If necessary it could also be used in Morning Glory.
  2. Make backup
  3. Expect the script to take a long time with a large number of orders. (for 25-30k orders it took ~30 minutes)
  4. Operations affecting order encumbrances or budgets should be avoided while the script is running.
  5. Disable Optimistic Locking (for Lotus and Morning Glory only, do not re-enable after running script)
    ALTER TABLE {tenant}_mod_finance_storage.transaction DISABLE TRIGGER set_transaction_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.budget DISABLE TRIGGER set_budget_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.budget_expense_class DISABLE TRIGGER set_budget_expense_class_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.expense_class DISABLE TRIGGER set_expense_class_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.fiscal_year DISABLE TRIGGER set_fiscal_year_ol_version_trigger;
    ALTER TABLE {tenant} DISABLE TRIGGER set_fund_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.fund_type DISABLE TRIGGER set_fund_type_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.group_fund_fiscal_year DISABLE TRIGGER set_group_fund_fiscal_year_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.groups DISABLE TRIGGER set_groups_ol_version_trigger;
    ALTER TABLE {tenant}_mod_finance_storage.ledger DISABLE TRIGGER set_ledger_ol_version_trigger;
  6. Delete records from temporary transactions table 
    DELETE FROM {tenant}_mod_finance_storage.temporary_order_transactions;

Script execution


  • Fiscal year code
  • Okapi URL
  • Tenant
  • Username
  • User password is required as a command-line input.


python3 ./ 'FY2022' 'http://localhost:9130/' 'diku' 'diku_admin'

Script Source Code


This script fixes encumbrance statuses and budget values, but not links between order line and new encumbrances created during rollover. After running this script you may have POLs that still reference an encumbrance from a previous fiscal year. If so you will want to use a separate script that will be create to fix these links. see MODFISTO-350 - Getting issue details... STATUS  for more details

  • No labels