AuthorAndrei Makaranka
JIRA task
Business Requirements

Architects Review
PO review

Revision History

VersionDateOwnerDescriptionReason
v1.007.27.2020Andrei MakarankaInitial version
v1.107.31.2020Andrei MakarankaFill gapsGrooming session 29.07.2020
v1.208.01.2020Andrei MakarankaDesign writing started. Activity diagram addedInternal grooming session 08.07.2020
v1.309.25.2020Andrei MakarankaUpdate model and API definition

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:

High-Level Requirements:

Constraints

Assumptions, dependencies

Out of Scope

Architecturally Significant Requirements

Solution Design

Rollover flows

Fiscal year rollover flows

Data Model

ledger_fiscal_year_rollover

PropertyTypeDefaultRequiredNotes

id

string


N

UUID - System generated if not specified

ledgerId

string


Y


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

Y

If true, imposes restrictions on encumbrances

restrictExpenditures

boolean

false

Y

If true, imposes restrictions on payments

budgetsRollover

array<budgets_rollover>


Y

encumbrancesRollover

array<encumbrances_rollover>


Y

ledgerRolloverStatus

ledger_fiscal_year_rollover_status


NCollecting rollover progress information

metadata

metadata

Generated by system

No

System generated record metadata

budgets_rollover

PropertyTypeDefaultRequiredNotes

fundTypeId

string


Y

UUID - UUID from fund_type table

rollover_allocation

boolean

true

Y

Should allocated amount needs to be rollovered 

adjust_allocation

number

0%

Y

How much should we increase the allocation

rollover_available

boolean

true

Y

Should available amount needs to be rollovered 

add_available_to

enum

Available

Y

Where to add available : Available or Allocation

allowableEncumbrance

number

100%

Y

The encumbrance percentage limit for this budget

allowableExpenditure

number

100%

Y

The expenditure percentage limit for this budget

encumbrances_rollover

PropertyTypeDefaultRequiredNotes

orderType

enum


Y

Ongoing, Ongoing-Subscription, One-time

basedOn

enum


Y

Expended, Remaining

increaseBy

number

0%

Y

How much should we increase the encumbrance amount based on "basedOn"

ledger_fiscal_year_rollover_status

PropertyTypeDefaultRequiredNotes

id

string


N

UUID - System generated if not specified

rollover_idstring
YUUID - Ledger rollover id 
overall_statusoverall_rollover_statusNot StartedYStatus of the rollover process : Not Started, In Progress, Error, Success
budgets_rollover_status
steps_rollover_statusNot StartedYStatus of budgets rollover process : Not Started, In Progress, Error, Success
encumbrances_rollover_statussteps_rollover_statusNot StartedYStatus of encumbrances rollover process : Not Started, In Progress, Error, Success
orders_rollover_statussteps_rollover_statusNot StartedYStatus of orders rollover process : Not Started, In Progress, Error, Success


APIs

Rollover Business API

Method

Path

Request

Response

Description

Interface

Notes

POST/finance/ledgers/{id}/rolloverledger_fiscal_year_rolloverledger_fiscal_year_rolloverCreate and start process ledger fiscal year rolloverfinance.ledgers.rolloverStatus : 201
GET/finance/ledgers/{id}/rolloverNAledger_fiscal_year_rolloverGET ledger fiscal year rolloverfinance.ledgers.rolloverStatus : 200

Rollover Storage API

Method

Path

Request

Response

Description

Interface

Notes

POST/finance-storage/ledgers/{id}/rolloverledger_fiscal_year_rolloverledger_fiscal_year_rolloverCreate and start process ledger fiscal year rolloverfinance-storage.ledgers.rolloverStatus : 201
GET/finance-storage/ledgers/{id}/rolloverNAledger_fiscal_year_rolloverGET ledger fiscal year rolloverfinance-storage.ledgers.rolloverStatus : 200
PUT/finance-storage/ledgers/{id}/rolloverledger_fiscal_year_rolloverNAUPDATE ledger fiscal year rollover if it not started or end. Alsofinance-storage.ledgers.rolloverStatus : 204
DELETE/finance-storage/ledgers/{id}/rolloverNANADELETE  ledger fiscal year rolloverfinance-storage.ledgers.rolloverStatus : 204

Rollover progress business API

Method

Path

Request

Response

Description

Interface

Notes

POST/finance/ledgers/{id}/rollover/status

ledger_fiscal_year_rollover_status

ledger_fiscal_year_rollover_statusCreate rollover processfinance.ledgers.rollover.statusStatus : 201
GET/finance/ledgers/{id}/rollover/statusNAledger_fiscal_year_rollover_statusGET rollover processfinance.ledgers.rollover.statusStatus : 200
PUT/finance/ledgers/{id}/rollover/statusledger_fiscal_year_rollover_statusNAUPDATE rollover processfinance.ledgers.rollover.statusStatus : 204

Rollover progress storage API

Method

Path

Request

Response

Description

Interface

Notes

POST/finance-storage/ledgers/{id}/rollover/statusledger_fiscal_year_rollover_statusledger_fiscal_year_rollover_statusCreate rollover processfinance-storage.ledgers.rollover.statusStatus : 201
GET/finance-storage/ledgers/{id}/rollover/statusNAledger_fiscal_year_rollover_statusGET rollover processfinance-storage.ledgers.rollover.statusStatus : 200
PUT/finance-storage/ledgers/{id}/rollover/statusledger_fiscal_year_rollover_statusNAUPDATE rollover processfinance-storage.ledgers.rollover.statusStatus : 204
DELETE/finance-storage/ledgers/{id}/rollover/statusNANADELETE rollover processfinance-storage.ledgers.rollover.statusStatus : 204

Design

Solution will be based on stored procedures in PostgreSQL and this is followed from 3d item from "Architecturally Significant Requirements".

The following PostgreSQL procedures are required :

  1. Budget rollover procedure
  2. Encumbrances rollover procedure
  3. Change cost in the processed orders  

Stages and sequence of execution fiscal year rollover:

Open Items

QuestionAnswer

Andrei Makaranka : How many users can start rollover at the same time?

Dennis Bridges Each ledger could rollover independently but most would roll one at a time. Generally there is one user that handles the rollover at each institution. However, for a multi library instance each Ledger could be rolled over by a different user.

Andrei Makaranka: Could you clarify what "unfinished orders" are and what encumbrances should we choose for a rollover?

Dennis Bridges Any "Open" orders should be considered in the rollover. However, some may not have encumbrances. Closed and pending orders will not need encumbrances created during rollover for the new fiscal year.

Andrei Makaranka: There are to approaches how to rollover budgets:

  1.  After the start of the rollover all selected active budgets will be blocked(Status = "Closed") for any operations and then all new budgets start to be created.
  2.  After the start of the rollover, the budgets are blocked(Status = "Closed") and new ones are created for them one by one.

Example : Block first budget and then create new budget. Block second budget and then create new budget.

What is the right approach from business view?

Dennis Bridges This process is generally done while all other system activity is frozen. Meaning the expectation would be that if I am rolling over Ledger A no one can spend money against any of the budgets assigned to Ledger A. Option 1 seems like the appropriate approach.

Andrei Makaranka: Do we need set "Active" status for new budgets immediately after creation or only when rollover will be finished?

Dennis Bridges So long as the system can still create the necessary encumbrances I believe we should activate the budget last. So the users can be sure no one is able to order or invoice against them during rollover.

Andrei MakarankaWe need set of checks which we can use for building error report.

Also it's needed for estimating the scope an effort what we need for implementing a rollover check process.

Could you please provide this set of checks? 

Dennis Bridges The checks would include:

Were budgets closed successfully for previous fiscal year?

Were budgets created successfully for new fiscal year?

Were budgets activated successfully for new fiscal year? Note: if Fund status is Frozen, then new budget should be created in status Frozen.

Were allocations created against all new budgets successfully for new fiscal year?

Were encumbrances created for all POLs against new budgets for new fiscal year?

Andrei Makaranka: Library will want to release all remaining encumbrances in the fiscal year that is being closed?

Dennis Bridges No, I have confirmed that the encumbrances should remain as they are in the fiscal year being closed, for reporting purposes. 

Andrei Makaranka: What field need to be included in the error report?

Dennis Bridges 

Order error table

POL Number (Hyperlink)

Failed action(s) (Eg. Create Encumbrance)

Amount (Eg. $104.03)

Fund Code (Eg. ECON) (Hyperlink)

Error message (Eg. Not enough money available in the Fund to create encumbrance)

Fund error table

Fund Code (Hyperlink)

Failed action(s) (Eg. Create allocation)

Amount (Eg. $1000)

Error message (Eg. System error: server could not be reached)



Aliaksandr Pautau : What should happen to invoices during a rollover, specifically with Pending payments?

Dennis Bridges : 
Any invoice with a pending payment that IS NOT in the workflow state "Approved" should be moved into the next fiscal year (Note: Currently this is not an issue, but we will be implementing a feature in the future that will mean creating pending payments for all invoices that are Open).

Any invoice with pending payment(s) that are in the workflow state "Approved" should NOT rollover pending payments into the next fiscal year. Important: Also, any payment or credit for the invoice should be created for the FY during which the invoice was approved.

  • Eg. Invoice 1234 is approved in FY2020. The ledger is rolled over into FY2021 and then the invoice is transitioned to paid. Payments are created for FY2020 budget.


Andrei Makaranka In what order should we process orders during rollover?
Exampleы: 

  1. We can start from the very first in time to the last created order.
  2. We can start with the orders with the least encumbered amount of money booked or vice versa.

Dennis Bridges

We will start from the oldest orders and finish with the newest orders.

Andrei Makaranka Is not clear how to create new fiscal year rollover? 

In mockup https://drive.google.com/drive/u/0/folders/1OGnJNiNVgm6c6qifjDf-ZXnAhlv54JTV

  • FY20 - Is this the fiscal year code? If yes why the use can't edit the code?

Dennis Bridges

Mockup has been updated so the user will not need to edit the Fiscal year at this time. They can select an existing year or create a new one during rollover.

https://drive.google.com/file/d/15i9H9JM6Tk6DDv9M2ubkzincxN4xep2t/view?usp=sharing


Andrei Makaranka Is not clear how to change costs in mixed POL?

How to split percentage between different types physical and e-resource?

Dennis Bridges

We are not really concern with cost being updated it might be ideal not to update the cost. Particularly when basing the increase on amount expended which could be higher OR lower than current cost of POL.

We may need to discuss what mechanism could be added to handle these changes. I have often times considered that it could make sense to have a Cost FY for the POL so an order can have a clear cost history from one year to the next. I have created a visual to describe use cases and help us discuss the solution. FYRO Encumbrance visual.pdf

Aliaksandr Pautau In case of an error of lack of money in the fund: Should we skip the creation all encumbrances for the order, or only for a fund where there is no money?

Dennis Bridges

In this case the order should be skipped. Essentially it should appear in the error report after rollover as having failed because the encumbrances could not be made. Because there was not enough money available in FUND XYZ

Andrei Makaranka How to be in a situation if in the same POL we have funds from different ledgers and then the cost changing affects the ledger who did not rollover?

Dennis Bridges

In this case the order should be skipped as well. Essentially it should appear in the error report after rollover as having failed because the encumbrances could not be made. Because there was not enough money available in FUND XYZ. Ideally IF the other ledger was rolled over already, at which time this order failed to encumber. Then rolling over this ledger would make another attempt and this time it would be successful encumbering both funds as they would now have allocations. So again either the order is entirely successful or not and if not it is flagged for the user in the report.

Andrei Makaranka Should user has specific permissions for starting rollover? (the similar like we done for approve order)

Dennis Bridges Yes, note the permission reference in UIF-168. "Finance: Execute fiscal year rollover" permission.