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.

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 Item Status as Reference Records - UXPROD-1927#impacts that would have to be worked through in order for this change to occur.

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

Background and Current Data Structure

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. Some libraries want to allow item status transitions that other libraries don't - e.g., allow staff to mark an item with status X as available from the Inventory app, when that is not allowed by default.
  
• 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. 

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 (link to Github). 

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.

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):

{
	“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:

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

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 .

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:

{
	“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?