RA-Collections Use Cluster
API reference documentation for all modules located at: https://dev.folio.org/reference/api/
This report satisfies the requirements for the Collection Use Cluster, UXPROD-1915 - Getting issue details... STATUS .
Reports included in cluster:
- REP-103 - Getting issue details... STATUS (covered by Circulation Item Detail Report Prototype)
- REP-107 - Getting issue details... STATUS
- REP-145 - Getting issue details... STATUS (maybe need to be reclustered; more of a list of items than a total count of collections use)
- REP-194 - Getting issue details... STATUS
- REP-195 - Getting issue details... STATUS
- REP-204 - Getting issue details... STATUS
Data Elements Required:
- loans
- loan id | loans
- patron group (don't use users, use loans -> patron_group_id_at_checkout) | loans
- loan policy | loans, but go ahead and join in loan_policies to get name
- service point (checkout) | loans
- loan_policies
- name
- items
- material type | items, but join to material_types to get name
- item owning library (can be at item level, but more often at holding level) - item permanent, temporary, and effective location | items, or loans if using item effective location at checkout
- loan type | items, which has both permanent and temporary loan types (hard to tell what loan type was in place at time of loan, so do not include this)
- loan_types
- name
- material_types
- name
- holdings
- holdings owning library - holdings permanent and temporary location | holdings
userspatron status (users -> active) - is this necessary? or just another way of saying patron group? | users, but hopefully not necessary
- loan history
- renewal count (requires loan history)
- parameters
- transaction date range (parameter that users will set)
holds/requests? (out of scope for this cluster)
The purpose of this report is for stats, so what would be best is to get totals broken down by the categories included here (e.g., patron group, loan policy). For debugging purposes, might occasionally want it broken down to see each loan as a separate row, but for normal time period for this query (full year), that would be overwhelming.
Joins:
- loans → items
loans → users (possibly not necessary)- items → material types
- loans → loan policy
- loans → loan history
- items → holdings (possibly not necessary)
| Folio Attribute (Module/Path:Object) | Folio Data Element Description | Parameters/Query |
|---|---|---|
| Loans table | ||
| User ID (mod-circulation-storage/loan-storage/loans/anonymize/{userId}:userID) | The UUID of the user to whom an item is loaned | Provides a join point between mod-circulation-storage and mod-users - connects with: mod-users/users/{userID}:patronGroup |
| Patron Group ID (mod-users/users/{userID}:patronGroup) | The UUID corresponding to the group the user belongs to | Provides a join point between mod-users/users and mod-users/groups - connects with: mod-users/users/groups:group |
| Patron Group Name (mod-users/users/groups:group) | The unique name of this group | |
| Item Status (mod-inventory-storage/item-storage/items:status) | The item's status (e.g. Available, Checked out, In transit, etc.) | Where status.name="checked-out" |
Item Call Number (mod-inventory-storage/item-storage/items:itemLevelCallNumber) | The call number listed within the item record of the loaned item | Both item call number and holdings call number will be listed within this report for the sake of comprehensiveness. |
| Holdings Call Number (mod-inventory-storage/holdings-storage:callNumber) | The call number listed within the holdings record of the loaned item | Both item call number and holdings call number will be listed within this report for the sake of comprehensiveness. |
| Item ID (mod-circulation-storage/loan-storage/loans:itemId) | The UUID of the loaned item | Provides a join point between mod-circulation-storage and mod-inventory-storage. This allows us to pull all pertinent details for the circulated item (as identified by its ID). Connects with: mod-inventory-storage/item-storage/items/{itemId}:id |
| Holdings ID (mod-inventory-storage/holdings-storage/holdings:id) | The UUID for the holdings record | Provides a join point between mod-inventory-storage/item-storage and mod-inventory-storage/holdings-storage. This allows us to pull the holdings-level call number. Connects with: mod-inventory-storage/holdings-storage/holdings/{holdingId}:id |
| Item Title (mod-inventory-storage/holdings-storage/holdings:shelvingTitle) | The title of the item loaned | |
| Item Barcode (mod-inventory-storage/item-storage/items/{itemId}:barcode) | The barcode of the item | Item ID provided from mod-circulation-storage/loan-storage/loans:itemId |
Item Permanent Location ID (mod-inventory-storage/item-storage/items:permanentLocationId) | UUID for the item's permanent location. Note: I believe 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 |
| 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 |
| Loan Date (mod-circulation-storage/loan-storage/loans:loanDate) | The date an item was loaned | This data element provides the main filter point for this report (where loanDate Between [start] And [end]) |
| Item Enumeration (mod-inventory-storage/item-storage/items:enumeration) | Item enumerator (e.g., vol. 1, No. 2, etc.) | |
| Item Copy Number (mod-inventory-storage/item-storage/items:copyNumbers) | Item copy number (e.g., copy 1, copy 2, etc.) | |
| 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). | The UUID provided by mod-inventory-storage/item-storage/items:permanentLocationId will determine what name is shown here. |
Material Type Name (mod-inventory-storage/item-storage/material-types:name) | Label for the material type (e.g., "book") | This element is pulled into the report using the materialTypeId found in mod-inventory-storage/item-storage |
| Material Type ID (mod-inventory-storage/item-storage:materialTypeId) | UUID associated with any 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 |
| Loan ID (mod-circulation-storage/loan-storage:id) | UUID generated by a loan (identifies a specific circulation transaction) | This element is not needed as a join point, since all loans within a specific date range are pulled by default. However, the addition of this element provides needed information within some contexts. |
| Location Unit Name (mod-inventory-storage/location-units/institutions:name) | Name of item location at the "institutions" level (i.e., lowest location level). | This element provides the ability to identify circulation levels for reserve items. Within the FOLIO API documentation, reserves are defined at the institution location level. However, this will not necessarily be the way reserves are established at all libraries. Generally speaking, reserves can be established within the context of locations or material types. Currently, this report pulls both elements. Therefore, filtering to derive reserves circulations levels is possible within the context of either scenario. |