Technical Designs and Decisions
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata
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

Dennis Bridges

Initial version
v2.0

 

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

 

Andrei Makaranka

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



  • No labels

6 Comments

  1. Dennis Bridges

    Re: Ann-Marie Breaux in JIRA

    Good to know, Andrei Makaranka. Dennis Bridges let's talk this through before moving this story out of draft.

    1. If GOBI uses different fields for fund and expense class, then some dev work would be required on the GOBI side to concatenate them into one output field in the API data
    2. If GOBI uses the fund field for the entire value (e.g. SCIENCE-ELECTRONIC), then
      • we'll need to map out all the possible combinations that need to be in the fund code list, e.g. each fund by itself (if that's allowed), plus each fund and its allowed expense classes. That may make the GOBI fund list much longer
      • And the current character limit for GOBI funds in 10 characters. We have a workaround for this - we make the version that displays in GOBI only 10 characters long, and then expand it after the order button is place, as the API data is being compiled. I've attached a chart that we set up for another library showing the GOBI funds on the left and the expanded funds on the right.
      • And lastly, we should confirm with GOBI that a colon in a fund code does not cause any validation or mainframe issue

  2. Dennis Bridges

    Thanks Ann-Marie Breaux! Is there a specific reason why GOBI would want to provide separate fields for these two data points? This will require the GOBI system to understand the relationship between Fund and Expense class in FOLIO. Given that relationship can change and that there could be many expense classes that only relate to 1 Fund. If there is no logic built into GOBI to help narrow down expense class selection by Fund it could make things more difficult rather than less difficult for the user.

    If the library provides one list of codes GOBI could parse them and display them in separate fields if desired. This way they also have information about what Funds relate to what expense classes.

    If GOBI uses a combined list we just need to give the user a quick way of exporting that list so they can share it with GOBI or any other third-party. We could even build an API that external systems could use to retrieve the list of Funds in real-time.

    Regarding the character limit it seems that because FOLIO allows more than 10 characters already GOBI will need to normalize the data for some customers regardless.

    I've asked a few GOBI folks about the character restriction and will add a note here when I get a response.

  3. Ann-Marie Breaux

    Hi Dennis BridgesRight - I'm not worried about the number of characters, because GOBI already has a way to deal with that. We just need to be sure that we end up with a consistent solution for fund + expense class, so that all GOBI customers are set up in the same way. Let's have a quick chat about it at some point in the next few days

  4. Dennis Bridges

    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>

  5. Dennis Bridges

    Hopping we can define an Approach 2 and get it estimated.

    GOBI sends expense class name or code in a "Local data" field. GOBI allows libraries to configure 4 possible local data fields. In this case they would use one for expense class. We would need the ability to accept this in mod-gobi and use it to lookup the expense class ID so order lines could be created with Fund and expense class

  6. Andrei Makaranka

    Ticket for the second approach created MODGOBI-125 - Getting issue details... STATUS