Fiscal year rollover
Author | Andrei Makaranka |
|---|---|
JIRA task | |
Business Requirements | https://folio-org.atlassian.net/browse/UXPROD-772 |
Architects Review | Done |
PO review | Done |
- 2 Revision History
- 3 Overview
- 3.1 Constraints
- 3.2 Assumptions, dependencies
- 3.3 Out of Scope
- 4 Architecturally Significant Requirements
- 5 Solution Design
- 5.1 Rollover flows
- 5.2 Data Model
- 5.3 APIs
- 5.4 Design
- 5.4.1 Stages and sequence of execution fiscal year rollover
- 5.4.1.1 1. Create rollover structures and close budgets for previous fiscal year
- 5.4.1.2 2. Invoke procedure "budget_encumbrances_rollover.sql" (Encumbrance procedure logic)
- 5.4.1.3 3. Rollover orders
- 5.4.1.4 4. Collect errors in the DB table and convert to CSV if user request report.
- 5.4.1.4.1 budget_encumbrances_rollover.sql
- 5.4.1 Stages and sequence of execution fiscal year rollover
- 6 Open Items
Revision History
Version | Date | Owner | Description | Reason |
|---|---|---|---|---|
v1.0 | 07.27.2020 | Andrei Makaranka | Initial version | |
v1.1 | 07.31.2020 | Andrei Makaranka | Fill gaps | Grooming session 29.07.2020 |
v1.2 | 08.01.2020 | Andrei Makaranka | Design writing started. Activity diagram added | Internal grooming session 08.07.2020 |
v1.3 | 09.25.2020 | Andrei Makaranka | Update model and API definition | |
v1.4 | 10.13.2020 | Andrei Makaranka | Detailed rollover logic added | Internal feature telling |
Overview
In order to start the next fiscal year the user must be able to transfer or close outstanding encumbrances for orders that have not yet been resolved. This is generally done based on order type.
Use cases:
Library has ongoing orders that must be re-encumbered in the upcoming fiscal year. The library will want to encumber money next year based on what was spent in the current year and potentially increase it by a specific percentage.
Library has ongoing orders that must be re-encumbered in the upcoming fiscal year. The library will want to encumber money differently for continuations that for subscription orders. Increasing them by different percentages.
Library has one-time orders that could not be close and must be re-encumbered in the upcoming fiscal year. The method of encumbrance may differ from that of on-going orders. For one-time orders the library would rollover remaining encumbrances.
High-Level Requirements:
Adjust the date of encumbrances without affecting monies that have already been expended against this encumbrance.
Release encumbrances without affecting the monies that have already been expended.
Capture the original amount encumbered based on the purchase order line.
Track the amount expended against this encumbrance.
Track the current encumbrance.
Constraints
The fund must contain only one active budget.
Assumptions, dependencies
API for changing and creating a budget is ready.
API for changing, creating and releasing encumbrances is ready.
API for re-encumbered is ready. (Confirmed by @Dennis Bridges on grooming 29.07.2020)
It is likely that we will be creating upwards of 75000 - 100000 encumbrances during this process. (statistics from Library)
Out of Scope
Automatically trying to resolve issues which occurred in rollover time.
Support exchange rate.
Ledger fiscal year rollover preview.
Store ledger fiscal year rollover history.
Architecturally Significant Requirements
Fiscal year rollover is a process which must happen for all ledgers separately and this process started manually by user.
Ledger rollover includes : Budgets rollover and encumbrances rollover and those rollovers are independent processes.
The system after rollover must be in a consistent state. All budgets and encumbrances must be processed and as result rollover end successfully or with errors.
An error report will be generated after the process completes.
Must be compatible with PostgreSQL 10.x
Solution Design
Rollover flows
Data Model
ledger_fiscal_year_rollover
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
id | string | N | UUID - System generated if not specified | |
ledgerId | string | Y | Ledger UUID for which rollover was started | |
fromFisclaYearId | string | Y | UUID of the fiscal year from which rollover will be happened | |
toFisclaYearId | string | Y | UUID of the fiscal year to which rollover will be happened | |
restrictEncumbrance | boolean | false | N | If true, imposes restrictions on encumbrances |
restrictExpenditures | boolean | false | N | If true, imposes restrictions on payments |
needCloseBudgets | boolean | true | N | If true, then all budget must be closed in rollover time https://folio-org.atlassian.net/browse/UIF-175 |
budgetsRollover | array<budgets_rollover> | Y | ||
encumbrancesRollover | array<encumbrances_rollover> | Y | ||
metadata | metadata | Generated by system | No | System generated record metadata |
budgets_rollover
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
fundTypeId | string | UUID - UUID from fund_type table. It can be possible when fund don't have Type | ||
rolloverAllocation | boolean | true | N | Should allocated amount needs to be rollovered |
adjustAllocation | number | 0% | N | How much should we increase the allocation |
rolloverAvailable | boolean | true | N | Should available amount needs to be rollovered |
addAvailableTo | enum | Available | N | Where to add available : Available or Allocation |
allowableEncumbrance | number | 100% | N | The encumbrance percentage limit for this budget |
allowableExpenditure | number | 100% | N | The expenditure percentage limit for this budget |
encumbrances_rollover
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
orderType | enum | Y | Ongoing, Ongoing-Subscription, One-time | |
basedOn | enum | Y | Expended, Remaining | |
increaseBy | number | 0% | N | How much should we increase the encumbrance amount based on "basedOn" |
ledger_fiscal_year_rollover_progress
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
id | UUID | N | UUID - System generated if not specified | |
ledgerRolloverId | UUID | Y | Ledger UUID for which rollover was started | |
overallRolloverStatus | Enum | Not Started | N | Progress of the rollover process : Not Started, In Progress, Error, Success |
budgetsClosingRolloverStatus | Enum | Not Started | N | Progress of budgets closing rollover process : Not Started, In Progress, Error, Success |
| Enum | Not Started | N | Progress of new budgets and encumbrance creation rollover process : Not Started, In Progress, Error, Success |
ordersRolloverStatus | Enum | Not Started | N | Progress of orders rollover process : Not Started, In Progress, Error, Success |
ledger_fiscal_year_rollover_error
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
id | UUID | N | UUID - System generated if not specified | |
ledgerRolloverId | UUID | Y | Ledger rollover UUID for which rollover was started | |
errorType | Enum | Y | FUND, ORDER | |
failedAction | string | Y | Example: Create Encumbrance, Create allocation | |
errorMessage | string | Y | Example: Not enough money available in the Fund to create encumbrance, System error: server could not be reached | |
details | Map<String, Object> | Y |
order_rollover_error_details
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
purchaseOrderId | UUID | Y | ||
poLineId | UUID | Y | UUID of the POL. Need for link building | |
polNumber | string | |||
amount | number | Wrong amount | ||
fundId | UUID | Y | UUID of the fund | |
fundCode | string | Fund code |
fund_rollover_error_details
Property | Type | Default | Required | Notes |
|---|---|---|---|---|
fundId | UUID | Y | UUID of the fund | |