Apply expense classes to orders and invoices through API integrations

AuthorAndrei Makaranka
JIRA task

UXPROD-3096 - Getting issue details... STATUS

Business Requirements

UXPROD-3096 - Getting issue details... STATUS

Architects Review

IN PROGRESS

PO review

IN PROGRESS

Revision History

VersionDateOwnerDescriptionReason
v1.0
Initial version
v2.0

 

Updates with design
v2.1
Andrei MakarankaChange API URLOld already exists
v3.0

 

Update API and schemaBased on grooming session 22.06.2021

Overview:

Given a FOLIO tenant is using expense classes in their Fund structure. Third party systems must be able to indicate which Fund and Expense classes should be associated with the order line.

Constraints

Just adding a note here that AM and I were able to confirm with the GOBI team that they should be able to accommodate the following special characters in Fund codes.

This may influence what is used as a separator in our combined list of Fund and expense class.

HIST.AP

Supported

<FundCode>HIST.AP</FundCode>

HIST:AP

Supported

<FundCode>HIST:AP</FundCode>

HIST;AP

Supported

<FundCode>HIST;AP</FundCode>

HIST|AP

Supported

<FundCode>HIST|AP</FundCode>

HIST-AP

Supported

<FundCode>HIST-AP</FundCode>

HIST%AP

Supported

<FundCode>HIST%AP</FundCode>

HIST_AP

Supported

<FundCode>HIST_AP</FundCode>

HIST/AP

Supported

<FundCode>HIST/AP</FundCode>

HIST!AP

Supported

<FundCode>HIST!AP</FundCode>

HIST AP

Supported

<FundCode>HIST AP</FundCode>

Acceptance criteria:

External systems (eg GOBI) can apply fund and expense class when creating orders through the edge API

Decision making:

Option 1: Allow for external systems to send the fund-expense class concatenated as one data element.

  • Pros:
    • External systems only need to be provided the complete list of concentrated IDs
  • Cons:
    • More complex mapping in Folio
    • More information in a single field in third-party system
    • Any character that is used as a separator would need to be a restricted character in the fund code field

Option 2: Have external systems send fund and expense class as 2 separate data elements.

  • Pros:
    • Simple mapping on FOLIO side
  • Cons:
    • More information to collect in third party system
    • Difficult for that system to understand dependancies (Ie. what fund has what expense class)


The following is a workflow diagram outlining a possible approach


Questions to answer:

  1. Should FOLIO allow user to apply funds without expense classes even if the current budget has available expense classes. If we let external systems do this why would we restrict users?
    1. Could impact expense class limits feature?
    2. Would this make expenditure numbers for expense classes difficult to calculate? Would we need to represent these as an expense class called "Unassigned" or "No class" etc?
      1. Note: this would just be a frontend change as the backend for Order and Invoices does not require Expense class - DB to speak to user group
  2. If we implement a combined Fund code index does the separator we use need to be disallowed from Fund code and Expense class code fields? In the example above the separator is a colon ":".
    1. Yes, whatever character we choose must be invalid as an entry when creating Fund code or expense class code
    2. Both Fund code and Expense class code already must be unique in FOLIO


Information:
External systems generally only support Fund codes and the sending of a fund code. For this reason it might make sense to use expense class codes as extensions and maintain a list of all fund code+extentions that can be used to Map Fund codes and expense classes when creating orders.
External systems (eg GOBI) may have customizable fields that could be used to send the additional expense class information separately from Fund code.

Solution design

Data Model

fund_code_vs_expense_classes_type

PropertyTypeReadonlyDefaultRequiredNotesExample

fundCode

string

N

Y

Code of the FOLIO fund
ledgerCodestringN
YCode of the ledger

activeFundCodeVsExpClasses

array of String

NEmpty array

Y

Combination of the fund code and active expense classes 

FUND1:ExpClassPrn
inactiveFundCodeVsExpClassesarray of StringNEmpty arrayYCombination of the fund code and inactive expense classes FUND1:ExpClassElec

fund_code_vs_expense_classes_type_collection

PropertyTypeReadonlyDefaultRequiredNotesExample

delimiter

string pattern

N:

Y

Special character to separate Fund Code and Expense class code.

Allowed characters :  ":"

":"

fundCodeVsExpClassesTypes

array of the fund_code_vs_expense_classes_type

N

Y

Pairs of the fund code and expense classes

[FUND1:ExpClassPrn, FUND1:ExpClassElec ]

Sample

{
"delimiter" : ":",
"fundCodeVsExpClassesTypes" : [
	{
		"fundCode" : "Fund1",
		"ledgerCode" : "Ledger1",
		"activeFundCodeVsExpClasses" : ["Fund1:ExpClassPrn"],
		"inactiveFundCodeVsExpClasses":[]
	},
	{
		"fundCode" : "Fund2",
		"ledgerCode" : "Ledger2",
		"activeFundCodeVsExpClasses" : ["Fund2:ExpClassPrn"],
		"inactiveFundCodeVsExpClasses": ["Fund2:ExpClassElec"]
	}
]
}


APIs

Funds Vs Expense Classes Business API

Method

Path

Request

Response

Description

Interface

Notes

GET

/finance/fund-codes-expense-classes?fiscalYearCode=<fiscal year code>

NA

fund_code_vs_expense_class_collection

Return collection of the pairs  <fund code, expense classes>. If parameter "fiscalYear" is not provided, then retrieve pair for current fiscal yearfinance.funds.expense-classesStatus : 200



Design

Work Breakdown:

TaskJira ticket
  • Update Finance schema

MODFISTO-243 - Getting issue details... STATUS

  • Create combined code list API

MODFIN-199 - Getting issue details... STATUS

  • Update logic in mod-GOBI

MODGOBI-123 - Getting issue details... STATUS

  • Update logic in mod-EBSCONET

MODEBSNET-13 - Getting issue details... STATUS

  • Add validation for special character to Fund Code and Expense class code
  • Migration script for Expense class code (Any empty codes will be populated with expense class name)
  • Migration script for Fund code (Remove separator if it is being used in any code)

MODFISTO-244 - Getting issue details... STATUS

GOBI sends expense class name or code in a "Local data" field. Approach 2

MODGOBI-125 - Getting issue details... STATUS

  • Update Form validation on UI