Author	Andrei 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

Version	Date	Owner	Description	Reason
v1.0		Dennis Bridges	Initial version
v2.0	01 Jun 2021	Andrei Makaranka	Updates with design
v2.1		Andrei Makaranka	Change API URL	Old already exists
v3.0	23 Jun 2021	Andrei Makaranka	Update API and schema	Based 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:

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
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

Property	Type	Readonly	Default	Required	Notes	Example
fundCode	string	N		Y	Code of the FOLIO fund
ledgerCode	string	N		Y	Code of the ledger
activeFundCodeVsExpClasses	array of String	N	Empty array	Y	Combination of the fund code and active expense classes	FUND1:ExpClassPrn
inactiveFundCodeVsExpClasses	array of String	N	Empty array	Y	Combination of the fund code and inactive expense classes	FUND1:ExpClassElec

fund_code_vs_expense_classes_type_collection

Property	Type	Readonly	Default	Required	Notes	Example
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 ]

Property

Type

Readonly

Default

Required

Notes

Example

delimiter

string pattern

Special character to separate Fund Code and Expense class code.

Allowed characters : ":"

":"

fundCodeVsExpClassesTypes

array of the fund_code_vs_expense_classes_type

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 year	finance.funds.expense-classes	Status : 200

Design

Work Breakdown:

Task	Jira 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

Browser not supported