Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents


Panel
borderColorblack
borderStylesolid
titleSupporting libraries

If your library would support prioritizing this work within for FOLIO, please edit this page and add your library name and at least one institutional contact below.



Summary and purpose of this wiki page

FOLIO has long planned to include functionality to support item level workflows through a three-part item state, but implementation has stalled since Fall 2020 and only one part is mostly completed.

In order to move this work forward, FOLIO needs to make significant changes to the data structure of the item status field, impacting multiple apps across the platform.

If we do not move this work forward, FOLIO will not be able to support functionality that libraries need in order to manage their physical collections, and will not be able to support integrations with workflow tools that are crucial for management of larger collections.

This page provides some background to the development of item state in FOLIO, outlines the basics of a proposed path forward, and lists the expected impacts that would have to be worked through in order for this change to occur.

We invite libraries that would support prioritizing this work across the project to edit this page and add their name to the list in the box at the top right.


Anchor
intro
intro
Background

FOLIO has a long-standing design plan to implement a three-part item state to provide different information about items and support library workflows.

The three parts include:

  • Availability. This indicates an item’s current circulation status and can provide information about whether an item is requested or can be loaned. This is currently implemented in FOLIO and labeled as Item status in the FOLIO UI. Item status is a required field; an item can have only one item status.
  • Needed for. (UXPROD-1530) This allows staff to indicate that an item needs to be sent into a particular process. An item can have more than one “Needed for” but it is not required. Libraries will be able to define their own list of “Needed for” values in FOLIO settings.
  • Process. (UXPROD-1590)This allows staff to indicate that an item is currently in a library workflow. An item can have one process value but it is not required. Libraries will be able to define their own list of “Process” values in FOLIO settings.

In addition to the 3-part item state, there has also been a long-standing plan to implement the ability to add item statuses and customize the behavior of system-implemented item statuses (UXPROD-1535).

These would all support use cases such as the following:

  • Providing a discovery display name. For example, a library may want to have the item statuses “Missing” and “Long missing” both show to patrons as “Item not found - see staff.”
  • Supporting library-defined workflows. The two values of “Needed for” and “Process” can allow libraries to indicate when items have entered and left workflows, as well as provide a way for libraries to prioritize certain types of work. For example, a library may prioritize a “Needed for” value of Course reserves over an individual patron request. This is work that likely would need to be done before full implementation of a workflow engine app or integration(s) with external tools.
  • Deactivate item statuses that aren’t in use. Some FOLIO-provided item statuses won’t be used by all libraries, such as “Intellectual item” or “Awaiting delivery.” Supporting custom item statuses could include marking a status as inactive, which could then lead to it not being displayed in the user interface, reducing errors.
  • Changing default behavior for item statuses. Some libraries want to use default item statuses but change their behavior. For example, by default, FOLIO allows holds to be placed on items with a status of missing, but some libraries do not want those items to be able to be requested at all.
  • Support innovative new services and workflows. Being able to add new item statuses is crucial for some use cases that would introduce new services to libraries. Some libraries want to be able to extend their collections by implementing a Controlled Digital Lending service (https://controlleddigitallending.org/) - to do so, they would want to create a custom item status to use for physical items that are sequestered. Other libraries may want to introduce purchase-on-demand services to faculty, and use a special item status to track when those items are created. We also want FOLIO to be prepared for new library technology that hasn't even been envisioned yet. 

Current data structure

When FOLIO first implemented item records, the item status was defined simply as a string attribute on the item record, without a controlled vocabulary or other defined values.

In January 2020, developers implemented a restricted list (MODINVSTOR-283) that defined item values as a list, enumerated in the item schema

That is the current state of the data model: we have a list of acceptable values that can be stored in the “status” attribute on an item record.

Note
In order to address the use cases and needed functionality that FOLIO implementers want, we need the ability to create new item statuses and modify existing item statuses without having to reload the inventory modules. That is not possible with the current data model.

Anchor
pathforward
pathforward
Possible solution - Implement Item Status as Reference Record

One possible path forward is to change the item status data model to use reference records.

In FOLIO, reference records are loaded as part of installing a FOLIO module, and are generally used to specify controlled vocabularies. If you install FOLIO and view an app’s settings, the values that are already there are usually loaded from reference records.

What would using reference records look like? Well, instead of the string value “Missing”, you would have a json record called “missing.json” that might be defined like this (ref. UX-369):


Code Block
languagejs
{
	“id”: some_long_folio_UUID,
	“name”: “Missing”,
	“source”: “FOLIO”
}


On the item record, we would store the UUID of the status instead of the name. 

Then, future feature development would build off of those records by adding attributes that could then be used in workflows. For example, in order for FOLIO to support customization of allowed request types (UIREQ-475), developers could add an attribute to the reference record, resulting in a record like this:

Code Block
languagejs
{
	“id”: some_long_folio_UUID,
	“name”: “Missing”,
	"allowedRequestTypes": [
		"hold"
	],
	“source”: “FOLIO”
}

Anchor
impacts
impacts
Scope of work

An introductory analysis suggests the following work, at a minimum, would be required. There may be other areas of FOLIO also impacted that aren’t listed .

Inventory










Front-end?

Back-End?

Description

Stub jiras (if created)


Y

Work in mod-inventory and mod-inventory-storage to support new data model, including API updates


TBD

Y

Work in mod-search to support search by item status


Y


Update item view, item edit, action menus, search filtering, instance record view

UIIN-2220, UIIN-2221, UIIN-2224, UIIN-2225

Y

TBD

Update “in-transit items” in-app report

UIIN-2222

TBD

Y

Assess item status deletion dependencies to ensure they still work as expected (maybe tie to an attribute?)



Data import and Data export


Front-end?

Back-End?

Description

Stub jiras (if created)


Y

Work in data-import modules to support new data model, including API updates


Y

TBD

Updates to UI to support field-mapping profiles with item status

UIDATIMP-1286


Y

Work in data-export modules to support new data model, including API updates


Y


Support being able to query data with item status values;

UIDEXP-295


Circulation / Resource Access


Front-end?

Back-End?

Description

Stub jiras (if applicable)


Y

Updates to record schemas to support new data model (loans, requests, others?)



Y

Update check-out-by-barcode and other APIs (including notice workflows)



Y

Update request workflows (item- and title-) (including notice workflows)


Y


Update check in app UI


Y


Update requests view UI


Y

TBD

Update hold shelf clearance report in requests app

UIREQ-833

TBD

Y

Updates to circulation log app


TBD

Y

Updates to RTAC (real time availability checker) to support the new data model



Bulk Edit


Front-end?

Back-End?

Description

Stub jiras (if created)


Y

Updates to support item status bulk edits (available in Nolana)


Y


Updates to support item status display in UI



Orders and Receiving

(serials app is in early development, so possible development needs cannot be scoped yet)


Front-end?

Back-End?

Description

Stub jiras (if applicable)

TBD

Y

Support physical order workflows that create item records


TBD

Y

Support “Order closed” workflows that change item records


TBD

Y

Support being able to set item status in receiving workflows



Other areas (Export manager, Users, INN-Reach, Courses, LDP, Dashboard)


App/functional area

Front-end?

Back-End?

Description

Stub jiras (if applicable)

Export Manager


Y

Support export of item status value in export manager jobs


Users

Y

TBD

Updated Users in-app reports — overdue loans, claim returned, cash drawer reconciliation, financial transaction detail, refunds to process manually

UIU-2708, UIU-2709, UIU-2710, UIU-2711, UIU-2712

Users

Y


Updates to Users loans modal / UI

UIU-2706

Users

Y


Update to Users manual fee/fine modals.

UIU-2707

INN-Reach

TBD

TBD

Unsure - requires discussion with developers.


LDP

TBD

TBD

Unsure - requires discussion with developers.


Courses

Y


Updates to the reserve list UI on the course view pane

UICR-172

Dashboard

TBD

TBD

Whether anything is required would likely depend on the status of UXPROD-3794 whenever actual development on this began.



Considering how item status reference records could or could not be changed

Even in this new model, some item statuses could not be changed without potentially breaking FOLIO functionality.

For example, suppose that Liontamer Library is using FOLIO and has inventory and circulation to support a physical collection.

We can say certain things about their item statuses:

  • The item status that has a label of "Aged to lost" has a UUID of "some-long-string-of-numbers". Circulation apps must always be able to know that if an item has status "some-long-string-of-numbers" that that means that it was loaned and not returned by the specified time frame in the lost item policy.
  • If Liontamer Library wants to change the label of "Aged to lost" to "Never returned" because they think "Aged to lost" is too much library speak, FOLIO likely doesn't care. 
  • FOLIO would care if Liontamer Library wanted to do something like allow items with an "Aged to lost" status to be paged. FOLIO's circulation apps would not understand what that meant, and the built-in request functionality would break.
  • That probably means that the only thing Liontamer Library could do with that item status is change the label in the FOLIO UI.

On the other hand, suppose Liontamer Library creates a brand new item status that they want to use to indicate that an item is being moved from one library to another. They don't want to use FOLIO transit functionality because they aren't loaning the items, and they don't want to have to check the items in to make them available. So, they create a brand new item status that has a label of "Building Migration" and a UUID of "this-long-string-of-numbers", and then turn off options for that item to be requested.

We can say certain things about this use case:

  • The item status with a label of "Building migration" has a UUID of "this-long-string-of-numbers".
  • This item status is managed manually - there is no automated transaction in the Check in app, for example, that changes an item status to "Building migration."
  • Because there are no automated workflows, FOLIO does not care if you set this item status to allow a request type, or decide to deactivate it once you're done using it.

Approaches to deciding how to change or not change a reference record

One possible approach to these scenarios would be to define an attribute to signal to FOLIO that only the item status label can change - perhaps "systemDefined". If "systemDefined" = true, than you can only rename the item status, and the discovery layer name. If "systemDefined" = false, then you can change more parts of the reference record. 

A challenge with this is that there are use cases where you could want to allow some parts of a reference record to change and some not, and FOLIO doesn't necessarily determine as a platform which is which. For example, suppose a library wants to be able to allow a hold to be placed on a claimed returned item. Because claimed returned is system defined, you may have systemDefined = true, but want to  allow a library to do that.

Perhaps a record then might have controls at different levels of an item status record, e.g. an attribute called "protected" that meant that you could change the request behavior, like so:

Code Block
languagejs
{
	“id”: some_long_folio_UUID,
	"systemDefined": true,
	“name”: “claimedReturned”,
	"requestingControls": {
		"protected": false,
		"requestTypesAllowed": "hold"
	},
	“source”: “FOLIO”
}

If protected = false, you are allowed to change that setting. (Or perhaps protected is an array value, providing additional configuration options.)

Or, this might be an opportunity to break more functionality for item status out of inventory. Perhaps inventory contains the name definition of the item status, but controls for how the item status works live in the relevant module. That means that if a library used Inventory but not circulation, their item status record wouldn't contain information about circulation functionality since they don't need it.


Potential order of work

This page outlines a significant structure change to FOLIO, and we would want to investigate how to order the work to minimize impact on implemented and implementing libraries.

You would need to do inventory work first, but then could potentially think about follow-on work in multiple phases, such as

  • Phase 1: Inventory
  • Phase 2: Orders and receiving
  • Phase 3: Circulation and Users
  • Phase 4: Other functions (LDP. Dashboard...)

This needs to be outlined further with technical resources to determine the best order to do implementation.


Questions to be answered

  • How would libraries running on FOLIO now migrate to the new model?
  • What would be the impacts on integrations? How would the project communicate information about this change in a way that gives developers time to make needed changes?
  • How would this impact reporting workflows?