Custom Error Messages for Circ/Hold Matrix Matchpoints

I had some thoughts on doing something similar to this. My method was, however, going to be allowing custom failure codes (and removing the current script-based mappings to split up some combined ones). My main headache was defining those codes for use as all the descriptions and such currently live in the filesystem, not the database.

Overall, my thought was:

1. Add a "error code" field that, if circulate/holdable = false will be the failure reason. As we already return one *or more* rows we don't have to do much there. I was hoping to have this be a FK to a table containing code and description so they could be custom-defined.
2. Add a "override context" field that defines where the override permission for the error code needs to be granted at. I was thinking this would be a fixed list of values, such as "Context OU", "Item Owning OU", "Item Circ OU", "Patron Home OU".
3. Teach the find function to stop adding error codes/context locations when circulate/holdable would have been "true" (when fallthrough is involved, anyway) as beyond that point the answer would have been "yes, the item is circulatable/holdable" anyway.
4. Teach the circulation code to look for those codes and use them instead of just "the circ matrix said no" (which I would have as the default code when none is specified by a rule as that is what the current circulation code assumes anyway).

Note that we already return an array of matching rule IDs from find_circ_matrix_matchpoint, returning a matching array of failure codes/context location identifiers would be trivial (push nulls on for rows that don't have circulate set to false). And as I believe the circ/hold test functions return one or more rows already *anyway* we can iterate over the array(s) with the various reasons that came up.

A benefit of my method is that the list of reasons is better defined. A downside is that someone has to define a reason before it can be used.

I feel that the biggest benefit my method has is allowing custom override permissions to come into play. For example: "Local Use Only patrons can only check out items belonging to their library" could be set to be overridden by staff for their library's items but not for another library's items.

I don't know about another table defining all of the various codes for these, the intent is that these messages are specific to the rule causing the failure so the odds of them being reused would be very slim within a consortium and basically 0 between installations. I do see the value in custom overriding permissions/contexts, but that could be seen as a separate enhancement itself.

You're right about already returning an array of the matchpoint ids, I forgot about that. (Wasn't looking at the stored procs this morning, have since.)

My thought of the custom ones would be that there wouldn't be any by default and they would be added to local installs as needed. If they aren't made too specific (mentioning a specific library, for example) you could easily re-use the same basic message across multiple rules.

I know in our configs we could probably re-use something like "Local Use Only patrons can only circulate their home library's items at their home library" or similar across quite a large number of rules. I was also thinking about extending some of this to the limit set based restrictions as well, "Patron has reached the maximum number of DVD checkouts" could be different *numbers* of checkouts but still applied across multiple org units.

Using custom failure event codes has another benefit: The *frontend* of things doesn't have to look for new things at all, as multiple events should already be expected (patron level vs item level issues alone), so the changes are restricted to the backend code. Only cases where events have to come from a very specific list would need changing, if we have any code that acts like that.

Commenting on this to give the issue some more timeliness, since it's still an issue in 2023, v.3.8...

There is also a related bug, https://bugs.launchpad.net/evergreen/+bug/1974469, with specific examples of hold failure messages.

I'm wondering if, in the context of custom messages, if admin users could locally configure messages for different situations, particularly for patron-facing messages. For example, "Hold rules reject this item as unholdable" doesn't mean anything to anybody (except whoever creates hold rules.)

And another thought - as libraries move to third party discovery layers, the messages displayed to patrons for hold and renewal failures is also important.

For example, patrons find the message "Renewal attempt failed because the "hold/available copies" ratio exceeds the configured limit" off putting. FWIW, this is the staff interface message, the Evergreen OPAC displays this as "Item is needed for a hold".