mod-finance-storage version v1
https://github.com/folio-org/mod-finance-storage
mod-finance-storage (Fiscal year hierarchy)
Read-only API for retrieving the ledger/group/fund/budget/expense-class hierarchy for a fiscal year
/finance-storage/fiscal-year-hierarchy
get
Get the ledger/group/fund/budget/expense-class hierarchy for a fiscal year, one entry per ledger
get /finance-storage/fiscal-year-hierarchy
Get the ledger/group/fund/budget/expense-class hierarchy for a fiscal year, one entry per ledger
Query Parameters
- fiscalYearId: required(string)
UUID of the fiscal year to build the hierarchy for
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A collection of fiscal year hierarchies, one per ledger",
"type": "object",
"properties": {
"fiscalYearHierarchies": {
"description": "The list of fiscal year hierarchy objects contained in this collection",
"type": "array",
"id": "fiscalYearHierarchies",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A hierarchical rollup, for one fiscal year, of a ledger and its groups, funds, budgets and budget expense classes",
"javaName": "FiscalYearHierarchy",
"properties": {
"fiscalYearId": {
"description": "UUID of the fiscal year this hierarchy is scoped to",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"fiscalYearCode": {
"description": "The code of the fiscal year",
"type": "string"
},
"ledgerId": {
"description": "UUID of the ledger",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"ledgerCode": {
"description": "The code of the ledger",
"type": "string"
},
"ledgerName": {
"description": "The name of the ledger",
"type": "string"
},
"groups": {
"description": "The groups associated, for this fiscal year, with funds belonging to this ledger",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A group and the funds within it for a fiscal year, as it appears in the fiscal year hierarchy",
"javaName": "FiscalYearHierarchyGroup",
"properties": {
"groupId": {
"description": "UUID of the group",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"groupCode": {
"description": "The code of the group",
"type": "string"
},
"groupName": {
"description": "The name of the group",
"type": "string"
},
"funds": {
"description": "The funds belonging to this ledger that are associated with this group for this fiscal year",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A fund and its budget for a fiscal year, as it appears in the fiscal year hierarchy",
"javaName": "FiscalYearHierarchyFund",
"properties": {
"fundId": {
"description": "UUID of the fund",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"fundCode": {
"description": "A unique code associated with the fund",
"type": "string"
},
"fundName": {
"description": "The name of the fund",
"type": "string"
},
"budget": {
"description": "The budget for this fund in this fiscal year, if one exists",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"javaName": "FiscalYearHierarchyBudget",
"properties": {
"budgetId": {
"description": "UUID of the budget",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"budgetName": {
"description": "The name of the budget",
"type": "string"
},
"budgetStatus": {
"description": "The status of the budget",
"type": "string"
},
"initialAllocation": {
"description": "The amount of the first allocation made to this budget",
"type": "number"
},
"allocated": {
"description": "The amount currently allocated to this budget",
"type": "number"
},
"available": {
"description": "The amount currently available for this budget",
"type": "number"
},
"budgetExpenseClasses": {
"description": "The expense classes associated with this budget",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "An expense class associated with a budget, as it appears in the fiscal year hierarchy",
"javaName": "FiscalYearHierarchyExpenseClass",
"properties": {
"expenseClassId": {
"description": "UUID of the expense class",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"expenseClassCode": {
"description": "The code of the expense class",
"type": "string"
},
"expenseClassName": {
"description": "The name of the expense class",
"type": "string"
},
"status": {
"description": "The status of this expense class within the budget",
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"funds": {
"description": "The funds belonging to this ledger that are not associated with any group for this fiscal year",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A fund and its budget for a fiscal year, as it appears in the fiscal year hierarchy",
"javaName": "FiscalYearHierarchyFund",
"properties": {
"fundId": {
"description": "UUID of the fund",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"fundCode": {
"description": "A unique code associated with the fund",
"type": "string"
},
"fundName": {
"description": "The name of the fund",
"type": "string"
},
"budget": {
"description": "The budget for this fund in this fiscal year, if one exists",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"javaName": "FiscalYearHierarchyBudget",
"properties": {
"budgetId": {
"description": "UUID of the budget",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"budgetName": {
"description": "The name of the budget",
"type": "string"
},
"budgetStatus": {
"description": "The status of the budget",
"type": "string"
},
"initialAllocation": {
"description": "The amount of the first allocation made to this budget",
"type": "number"
},
"allocated": {
"description": "The amount currently allocated to this budget",
"type": "number"
},
"available": {
"description": "The amount currently available for this budget",
"type": "number"
},
"budgetExpenseClasses": {
"description": "The expense classes associated with this budget",
"type": "array",
"items": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "An expense class associated with a budget, as it appears in the fiscal year hierarchy",
"javaName": "FiscalYearHierarchyExpenseClass",
"properties": {
"expenseClassId": {
"description": "UUID of the expense class",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"expenseClassCode": {
"description": "The code of the expense class",
"type": "string"
},
"expenseClassName": {
"description": "The name of the expense class",
"type": "string"
},
"status": {
"description": "The status of this expense class within the budget",
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false,
"required": [
"fiscalYearId",
"ledgerId"
]
}
},
"totalRecords": {
"description": "The number of objects contained in this collection",
"type": "integer"
}
},
"additionalProperties": false,
"required": [
"fiscalYearHierarchies",
"totalRecords"
]
}Example:
{
"fiscalYearHierarchies": [
{
"fiscalYearId": "123e4567-e89b-12d3-a456-426614174004",
"fiscalYearCode": "FY2023",
"ledgerId": "123e4567-e89b-12d3-a456-426614174015",
"ledgerCode": "LED001",
"ledgerName": "Main Library Ledger",
"groups": [
{
"groupId": "123e4567-e89b-12d3-a456-426614174025",
"groupCode": "GRP001",
"groupName": "Materials",
"funds": [
{
"fundId": "123e4567-e89b-12d3-a456-426614174000",
"fundCode": "FND001",
"fundName": "General Fund",
"budget": {
"budgetId": "123e4567-e89b-12d3-a456-426614174001",
"budgetName": "Annual Budget",
"budgetStatus": "Active",
"initialAllocation": 1000000,
"allocated": 1000000,
"available": 950000,
"budgetExpenseClasses": [
{
"expenseClassId": "123e4567-e89b-12d3-a456-426614174030",
"expenseClassCode": "PRINT",
"expenseClassName": "Print materials",
"status": "Active"
}
]
}
}
]
}
],
"funds": [
{
"fundId": "123e4567-e89b-12d3-a456-426614174002",
"fundCode": "FND002",
"fundName": "Research Fund",
"budget": {
"budgetId": "123e4567-e89b-12d3-a456-426614174003",
"budgetName": "Research Budget",
"budgetStatus": "Planned",
"initialAllocation": 500000,
"allocated": 500000,
"available": 450000,
"budgetExpenseClasses": []
}
}
]
}
],
"totalRecords": 1
}
HTTP status code 400
Bad request, e.g. missing or malformed fiscalYearId parameter
Body
Media type: text/plain
Type: any
Example:
unable to process request -- malformed parameter 'fiscalYearId'HTTP status code 500
Internal server error, e.g. due to misconfiguration
Body
Media type: text/plain
Type: any
Example:
internal server error, contact administrator