Page tree
Skip to end of metadata
Go to start of metadata


API reference documentation for all modules located at:  https://dev.folio.org/reference/api/


Example of this report coming from Voyager (not yet available)


Report Description Detail

These reports are modeled on ID111 (Association of College and Research Libraries Reporting) and ID104 (Association of Research Libraries statistics). These reports also utilize elements of the ID433 (Circulation Report) and ID226 (E-Resource Counts for ARL, ACRL, NCES). These reports are used for pulling data that are reported on an annual basis to organizations such as the Association of College & Research Libraries (ACRL), the Association of Research Libraries (ARL), and the National Center for Education Statistics (NCES). 

The manner in which these reports are constructed can vary greatly from one library to the next. Therefore, a host of filter-point data elements must be included here in support of the widest variety of need within the FOLIO community. 


Report Criteria

  • A sum of total volumes
  • A sum of total titles, broken down into the categories of "tangible" and "electronic."
  • A sum of total expenditures, broken down into the categories of "one-time" and "ongoing."

Volume Count:

Volume counts typically entail counting the total number of item records within the ILS. However, there is typically a need to filter out records that are "suppressed." A library may also want to filter out certain types of materials, which can be done via MARC coding found in the leader and 008 fields. In the case of FOLIO tenants that are shared by multiple institutions or libraries, filtering by location my be necessary.  

Folio Attribute (Module/Path:Object)Folio Data Element DescriptionParameters/Query

Item ID (mod-inventory-storage/item-storage/items:id)

* Notated as itemId in other branches of the module

Unique ID of the item recordA volume count is derived by counting item IDs
Item Suppression Status (mod-inventory-storage/item-storage/items:discoverySuppress)Indicates that the item record is "suppressed" and should not be displayed in a discovery system

Used to filter (if necessary)

This element provides a means of excluding suppressed item records from the total title count

A library may count all non-suppressed item IDs to derive their title count. However, there may be instances where some filter mechanism must be used in order to select a subset of total volumes. In such cases, one will typically filter by material type, location, or both. Therefore, the following elements are being included in this report prototype to support this type of query refinement. 
Material Type ID (mod-inventory-storage/item-storage:materialTypeId)UUID for a particular material type

Provides a join point between mod-inventory-storage/item-storage and mod-inventory-storage/material-type - connects with:

mod-inventory-storage/material-type

Material Type Name (mod-inventory-storage/item-storage/material-types:name)


Label for the material type (e.g., "book")

Used to filter (if necessary)

Provides a means to filter by material type. This element is pulled into the report using the materialTypeId found in mod-inventory-storage/item-storage. This element provides a human-readable material type that is easier to work than the materialTypeId, which takes the form of a long machine-readable UUID. 

Institution Location ID (mod-inventory-storage/location-units/institutions:id

* Notated as institutionId in other branches of the module

Unique ID for item location at the "institutions" level (i.e., highest location level).

Provides a join point between mod-inventory-storage/location-units/institutions and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations

Campus Location ID (mod-inventory-storage/location-units/campuses:id)

* Notated as campusId in other branches of the module

Unique ID for item location at the "campuses" level (i.e., second-highest location level).

Provides a join point between mod-inventory-storage/location-units/campuses and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations

Library Location ID (mod-inventory-storage/location-units/libraries:id)

* Notated as libraryId in other branches of the module

Unique ID for item location at the "libraries" level (i.e., lowest location level).

Provides a join point between mod-inventory-storage/location-units/libraries and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations

Institution Location Name (mod-inventory-storage/location-units/institutions:name)

Name of item location at the "institutions" level (i.e., highest location level).

Used to filter (if necessary)

Provides a means to filter by institutional location. This element provides a human-readable institutional location name that is easier to work than the institutionId, which takes the form of a long machine-readable UUID. 

Campus Location Name (mod-inventory-storage/location-units/campuses:name)

Name of item location at the "campuses" level (i.e., second-highest location level).

Used to filter (if necessary)

Provides a means to filter by campus location. This element provides a human-readable campus location name that is easier to work than the campusId, which takes the form of a long machine-readable UUID. 

Library Location Name (mod-inventory-storage/location-units/libraries:name)

Name of item location at the "libraries" level (i.e., lowest location level).

Used to filter (if necessary)

Provides a means to filter by library location. This element provides a human-readable library location name that is easier to work than the libraryId, which takes the form of a long machine-readable UUID. 

Item Permanent Location ID (mod-inventory-storage/item-storage/items:permanentLocationId)


UUID for the item's permanent location.

Note: The permanentLocationId is a UUID that can be used to designate a "permanent location" as defined within one of the system's three levels of locations (i.e., institution, campus, and library locations).

*Needed to calculate Effective Location

Provides a join point between mod-inventory-storage/item-storage/items and mod-inventory-storage/locations. Connects with:

mod-inventory-storage/locations

At this time, the API documentation implies that an item location can be set to any location ID at any of the three location-unit levels (i.e., institution, campus, or library). 

Item Temporary Location ID (mod-inventory-storage/item-storage/items:temporaryLocationId)UUID for the item's temporary location.

Provides a join point between mod-inventory-storage/item-storage/items and mod-inventory-storage/locations. Connects with:

mod-inventory-storage/locations

Item Location (mod-inventory-storage/locations:name)

Location where the item is held.

The name element can refer to the descriptive name of the item's location at any of the three location-unit levels currently defined within the system (i.e., institution, campus, library).

Used to filter (if necessary)

Provides a means to filter by item location. The UUID provided by mod-inventory-storage/item-storage/items:permanentLocationId will determine what name is shown here.

Title Count:

Title counts are typically associated with bibliographic/instance, rather than item, records. However, traditional query approaches may differ in cases where a single FOLIO tenant hosts data for multiple institutions, or libraries that cross multiple lines of administrative authority. In such cases, the API architecture of FOLIO necessitates the involvement of item-relevant data elements for filtering purposes. 

For the ACRL and NCES annual survey, title counts will be broken down into the top-level categories of "tangible" and "electronic."

Folio Attribute (Module/Path:Object)Folio Data Element DescriptionParameters/Query

Instance ID (mod-inventory-storage/instance-storage/instances:id)

* Notated as instanceId in other branches of the module

UUID of the instance record

A title count is derived by counting instance IDs

Also provides a join point between mod-inventory-storage/instance-storage and mod-inventory-storage/holdings-storage - connects with:

mod-inventory-storage/holdings-storage:instanceId

Instance Suppression Status (mod-inventory-storage/instance-storage/instances:discoverySuppress)Indicates that the instance record is "suppressed" and should not be displayed in a discovery system

Used to filter (if necessary)

This element provides a means of excluding suppressed instance records from the total title count

A library may count all non-suppressed instance IDs to derive their title count. However, there may be instances where some filter mechanism must be used in order to select a subset of total titles. In such cases, one will typically filter by various bibliographic codings. In FOLIO these codings relate to instance format and type. There may also be a need for additional filtering by item-specific location, item-specific format, or both. Therefore, the following elements are being included in this report prototype to support this type of query refinement. 
Instance ID 2 (mod-inventory-storage/holdings-storage/holdings:instanceId)UUID for the instance record (found on holdings record)

Acts as a bridge between instance and holdings records. Provides a join point between mod-inventory-storage/holdings-storage and mod-inventory-storage/instance-storage. Connects with:

mod-inventory-storage/instance-storage:id

This join makes all holdings-level filtering possible.

Instance Format ID (mod-inventory-storage/instance-storage/instances:instanceFornatIds)

UUID associated with a particular instance format

Provides a join point between mod-inventory-storage/instance-storage and mod-inventory-storage/instance-format. Connects with:

mod-inventory-storage/instance-format:id

Instance Format Name (mod-inventory-storage/instance-formats:name)


Label for the instance format (e.g., "audio disc, online resource, etc.")

This element is traditionally associated with coding found on the MARC 008 (i.e., "form of item" and "type of material")

Used to filter (if necessary)

Provides a means to filter by instance format. This element is pulled into the report using the instanceFormatIds found in mod-inventory-storage/instance-storage. This element provides a human-readable material type that is easier to work than the instanceFormatIds, which takes the form of a long machine-readable UUID. 

Instance Type ID (mod-inventory-storage/instance-storage/instances:instanceTypeId)

UUID for a particular instance type

Provides a join point between mod-inventory-storage/instance-storage and mod-inventory-storage/instance-types. Connects with:

mod-inventory-storage/instance-types:id

Instance Type Name (mod-inventory-storage/instance-types:name)


Label for the instance type (e.g., "still image, computer dataset, etc.")

This element is traditionally associated with coding found on the MARC Leader (i.e., "type of record" and "bibliographic level")

Used to filter (if necessary)

This element provides a means to filter the title count by material type. This element is pulled into the report using the instanceTypeId found in mod-inventory-storage/instance-storage. This element provides a human-readable material type that is easier to work than the instanceTypeId, which takes the form of a long machine-readable UUID. 

Holdings ID (mod-inventory-storage/item-storage/items:holdingsRecordId)UUID for the holdings record

Acts as the bridge between holdings and item records. Provides a join point between mod-inventory-storage/holdings-storage and mod-inventory-storage/item-storage. Connects with:

mod-inventory-storage/holdings-storage/holdings:id

This join makes all item-level filtering possible.

Item Permanent Location ID (mod-inventory-storage/item-storage/items:permanentLocationId)


UUID for the item's permanent location.

Note: The permanentLocationId is a UUID that can be used to designate a "permanent location" as defined within one of the system's three levels of locations (i.e., institution, campus, and library locations).

*Needed to calculate Effective Location

Provides a join point between mod-inventory-storage/item-storage/items and mod-inventory-storage/locations. Connects with:

mod-inventory-storage/locations:id

At this time, the API documentation implies that an item location can be set to any location ID at any of the three location-unit levels (i.e., institution, campus, or library). 

Item Temporary Location ID (mod-inventory-storage/item-storage/items:temporaryLocationId)UUID for the item's temporary location.

Provides a join point between mod-inventory-storage/item-storage/items and mod-inventory-storage/locations. Connects with:

mod-inventory-storage/locations:id

Item Location (mod-inventory-storage/locations:name)

Location where the item is held.

The name element can refer to the descriptive name of the item's location at any of the three location-unit levels currently defined within the system (i.e., institution, campus, library).

Used to filter (if necessary)

Provides a means to filter by item location. The UUID provided by mod-inventory-storage/item-storage/items:permanentLocationId will determine what name is shown here.

Institution Location ID (mod-inventory-storage/location-units/institutions:id

* Notated as institutionId in other branches of the module

UUID for item location at the "institutions" level (i.e., highest location level).

Provides a join point between mod-inventory-storage/location-units/institutions and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations:institutionId

Campus Location ID (mod-inventory-storage/location-units/campuses:id)

* Notated as campusId in other branches of the module

UUID for item location at the "campuses" level (i.e., second-highest location level).

Provides a join point between mod-inventory-storage/location-units/campuses and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations:campusId

Library Location ID (mod-inventory-storage/location-units/libraries:id)

* Notated as libraryId in other branches of the module

UUID for item location at the "libraries" level (i.e., lowest location level).

Provides a join point between mod-inventory-storage/location-units/libraries and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations:libraryId

Institution Location Name (mod-inventory-storage/location-units/institutions:name)

Name of item location at the "institutions" level (i.e., highest location level).

Used to filter (if necessary)

Provides a means to filter by institutional location. This element provides a human-readable institutional location name that is easier to work than the institutionId, which takes the form of a long machine-readable UUID. 

Campus Location Name (mod-inventory-storage/location-units/campuses:name)

Name of item location at the "campuses" level (i.e., second-highest location level).

Used to filter (if necessary)

Provides a means to filter by campus location. This element provides a human-readable campus location name that is easier to work than the campusId, which takes the form of a long machine-readable UUID. 

Library Location Name (mod-inventory-storage/location-units/libraries:name)

Name of item location at the "libraries" level (i.e., lowest location level).

Used to filter (if necessary)

Provides a means to filter by library location. This element provides a human-readable library location name that is easier to work than the libraryId, which takes the form of a long machine-readable UUID. 

Circulation:

The ACRL statistical survey asks for an accounting of initial circulation transactions. "Initial circulation" includes charges only (no renewals). Depending on the situation, libraries may need to filter these transactions by location or the item-based material type. This query provides for such filtering. 

Folio Attribute (Module/Path:Object)Folio Data Element DescriptionParameters/Query
Loan ID (mod-circulation-storage/loan-storage:id)UUID generated by a loan (identifies a specific circulation transaction)Counting Loan IDs within a specified period is how initial circulation is tabulated for that period. 
Loan Date (mod-circulation-storage/loan-storage/loans:loanDate)The date an item was loanedThis data element provides the main filter point for this report (where loanDate Between [start] And [end])
Item ID (mod-circulation-storage/loan-storage/loans:itemId)UUID for a specific loaned item

Provides a join point between mod-circulation-storage and mod-inventory-storage. Connects with:

mod-inventory-storage/item-storage/items:id

This join makes additional filtering possible (e.g., by material type, location, etc.)

A library may count all loan IDs within a specific period to derive their initial circulation count. However, there may be instances where some filter mechanism must be used in order to select a subset of total initial circulation. In such cases, one may wish to filter out certain non-collection materials (e.g., markers, calculators, keys, etc.). There may also be a need for additional filtering by item location. Therefore, the following elements are being included in this report prototype to support this type of query refinement. 

Item ID (mod-inventory-storage/item-storage/items:id)

* Notated as itemId in other branches of the module

UUID of the item record

Acts as the bridge between the circulation and collections modules. Provides a join point between mod-inventory-storage/item-storage/items and mod-circulation-storage/loan-storage/loans. Connects to:

mod-circulation-storage/loan-storage/loans:itemId

Material Type ID (mod-inventory-storage/item-storage:materialTypeId)UUID for a particular material type

Provides a join point between mod-inventory-storage/item-storage and mod-inventory-storage/material-type - connects with:

mod-inventory-storage/material-type:id

Material Type Name (mod-inventory-storage/item-storage/material-types:name)


Label for the material type (e.g., "book")

Used to filter (if necessary)

Provides a means to filter by material type. This element is pulled into the report using the materialTypeId found in mod-inventory-storage/item-storage. This element provides a human-readable material type that is easier to work than the materialTypeId, which takes the form of a long machine-readable UUID. 

Institution Location ID (mod-inventory-storage/location-units/institutions:id

* Notated as institutionId in other branches of the module

UUID for item location at the "institutions" level (i.e., highest location level).

Provides a join point between mod-inventory-storage/location-units/institutions and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations:institutionId

Campus Location ID (mod-inventory-storage/location-units/campuses:id)

* Notated as campusId in other branches of the module

UUID for item location at the "campuses" level (i.e., second-highest location level).

Provides a join point between mod-inventory-storage/location-units/campuses and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations:campusId

Library Location ID (mod-inventory-storage/location-units/libraries:id)

* Notated as libraryId in other branches of the module

UUID for item location at the "libraries" level (i.e., lowest location level).

Provides a join point between mod-inventory-storage/location-units/libraries and mod-inventory-storage/locations - connects with:

mod-inventory-storage/locations:libraryId

Institution Location Name (mod-inventory-storage/location-units/institutions:name)

Name of item location at the "institutions" level (i.e., highest location level).

Used to filter (if necessary)

Provides a means to filter by institutional location. This element provides a human-readable institutional location name that is easier to work than the institutionId, which takes the form of a long machine-readable UUID. 

Campus Location Name (mod-inventory-storage/location-units/campuses:name)

Name of item location at the "campuses" level (i.e., second-highest location level).

Used to filter (if necessary)

Provides a means to filter by campus location. This element provides a human-readable campus location name that is easier to work than the campusId, which takes the form of a long machine-readable UUID. 

Library Location Name (mod-inventory-storage/location-units/libraries:name)

Name of item location at the "libraries" level (i.e., lowest location level).

Used to filter (if necessary)

Provides a means to filter by library location. This element provides a human-readable library location name that is easier to work than the libraryId, which takes the form of a long machine-readable UUID. 

Item Location (mod-inventory-storage/locations:name)

Location where the item is held.

The name element can refer to the descriptive name of the item's location at any of the three location-unit levels currently defined within the system (i.e., institution, campus, library).

Used to filter (if necessary)

Provides a means to filter by item location. The UUID provided by mod-inventory-storage/item-storage/items:permanentLocationId will determine what name is shown here.

Library Location Name (mod-inventory-storage/location-units/libraries:name)

Name of item location at the "libraries" level (i.e., lowest location level).

Used to filter (if necessary)

Provides a means to filter by library location. This element provides a human-readable library location name that is easier to work than the libraryId, which takes the form of a long machine-readable UUID. 

Item Permanent Location ID (mod-inventory-storage/item-storage/items:permanentLocationId)


UUID for the item's permanent location.

Note: The permanentLocationId is a UUID that can be used to designate a "permanent location" as defined within one of the system's three levels of locations (i.e., institution, campus, and library locations).

*Needed to calculate Effective Location

Provides a join point between mod-inventory-storage/item-storage/items and mod-inventory-storage/locations. Connects with:

mod-inventory-storage/locations:id

At this time, the API documentation implies that an item location can be set to any location ID at any of the three location-unit levels (i.e., institution, campus, or library). 

Item Temporary Location ID (mod-inventory-storage/item-storage/items:temporaryLocationId)UUID for the item's temporary location.

Provides a join point between mod-inventory-storage/item-storage/items and mod-inventory-storage/locations. Connects with:

mod-inventory-storage/locations:id

Item Location (mod-inventory-storage/locations:name)

Location where the item is held.

The name element can refer to the descriptive name of the item's location at any of the three location-unit levels currently defined within the system (i.e., institution, campus, library).

Used to filter (if necessary)

Provides a means to filter by item location. The UUID provided by mod-inventory-storage/item-storage/items:permanentLocationId will determine what name is shown here.

User Group ID (mod-circulation-storage/loan-storage:patronGroupId)The UUID of the user (or "patron") group

Acts as a bridge between circulation and users modules. Provides a join point between mod-circulation-storage and mod-users/. Connects with:

mod-users/groups:id 

User Group Name (mod-users/groups:name)The name of the user (or "patron" groupProvides a means to filter by patron group

Collections Expenditures:

The approach one takes to building a query that sums all financial expenditures for a statistical survey, like ACRL's, will vary across libraries. ACRL asks for a separate accounting of "one-time" and "ongoing" expenditures. Some libraries will use FOLIO to track these expenditures, while others will rely on some other financial accounting system administered through their parent institution. 

The elemental hierarchy of the mod-finance-storage module is (from highest to lowest): Ledger → Fund → Budget → Transaction

All transactions are associated with an "amount" which can be broken down into the encumbered amount, expended amount, or the amount awaiting payment. Some transactions might also be associated with an allocation (e.g., in cases of ongoing expenditures). 

How one approaches the building of a financial query will depend on the accounting structure that has been established in FOLIO. For example, the separation between one-time and ongoing expenditures could be established at the ledger, fund, or budget levels. What's more, a FOLIO instance that is shared between multiple institutions will likely establish their accounting structure differently from a single institution tenant. For example, a multi-institution tenant would likely establish separate ledgers for each institution. They might then establish a separation between one-time and ongoing expenditures at fund or budget levels. 

This prototype is an attempt to account for the full variety of ways in which institutions might set up their financial module and, therefore, need to construct their financial query for the ACRL statistical survey. Filter points are provided for at the ledger, fund, and budget levels. While one might use the "fiscal year" data element found within the ledger level of the fund structure as their date range filter point, this prototype instead uses transaction dates, as they will tend to be more accurate. 

Folio Attribute (Module/Path:Object)Folio Data Element DescriptionParameters/Query
Transaction Amount (mod-finance-storage/finance-storage/transactions:amount)The expenditure amount associated with a particular financial transaction

The ACRL statistical survey asks libraries to report the sum of all expenditures within a given category (i.e., "ongoing" or "one-time"), for a specified time period (e.g., fiscal year 2019).

This report should return a sum of transaction amounts, as filtered by other elements.

Fiscal Year ID (mod-finance-storage/finance-storage/transactions:fiscalYearId)UUID for a specific fiscal year

Provides a join point between mod-finance-storage/finance-storage/transaction and mod-finance-storage/finance-storage/fiscal-year. Connects with:

mod-finance-storage/finance-storage/fiscal-year:id

Fiscal Year (mod-finance-storage/finance-storage/fiscal-year:name)The name of the fiscal year periodProvides a key time-based filter point for this report. ACRL reporting involves all transactions for a specific fiscal year period.
Transaction Type (mod-finance-storage/finance-storage/transactions:transactionType)Describes the type of transaction, based on the pre-defined categories of: allocation, credit, encumbrance, payment, and transfer.To account for expenditures, one would want to set their transactionType parameter=="Payment" (i.e., the label associated with expenditures).  One may wish to also include encumbrances, in which case the transactionType parameter=="Payment" OR "Encumbrance"

Fund ID (mod-finance-storage/finance-storage/transactions:fromFundId)

UUID for a specific fund

Acts as a bridge between transactions, budgets, and funds.

Provides a join between mod-finance-storage/finance-storage/transactions, mod-finance-storage/finance-storage/budgets, and mod-finance-storage/finance-storage/funds. Connects to:

mod-finance-storage/finance-storage/funds:id

and 

mod-finance-storage/finance-storage/budgets:fundId

Ledger ID (mod-finance-storage/finance-storage/funds:ledgerId)

UUID for a specific ledger

Provides a join between mod-finance-storage/finance-storage/fund and mod-finance-storage/finance-storage/ledger. Connects to:

mod-finance-storage/finance-storage/ledgers:id

Ledger Name (mod-finance-storage/finance-storage/ledgers:name)The name of the ledgerSupports filtering by ledger. 
  • No labels