Apply expense classes to orders and invoices through API integrations
Author | Andrei Makaranka |
---|---|
JIRA task | |
Business Requirements | |
Architects Review | IN PROGRESS |
PO review | IN PROGRESS |
Revision History
Version | Date | Owner | Description | Reason |
---|---|---|---|---|
v1.0 | Initial version | |||
v2.0 |
| Updates with design | ||
v2.1 | Andrei Makaranka | Change API URL | Old already exists | |
v3.0 |
| 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?
- Could impact expense class limits feature?
- 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?
- 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 ":".
- Yes, whatever character we choose must be invalid as an entry when creating Fund code or expense class code
- 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 ] |
Sample
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 |
---|---|
| |
| |
| |
| |
| |
GOBI sends expense class name or code in a "Local data" field. Approach 2 | |
|