Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 65 additions & 42 deletions misc/returnables.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ states:
actions:
- name: validate
desc: Validate the request (e.g. check patron via NCIP LookupUser, if enabled)
transitions: [VALIDATED]
transitions:
success: VALIDATED

- name: VALIDATED
display: Validated
Expand All @@ -21,7 +22,8 @@ states:
actions:
- name: send-request
desc: Send ISO18626 request to the supplier or broker
transitions: [SENT]
transitions:
success: SENT

- name: SENT
display: Sent
Expand All @@ -30,19 +32,19 @@ states:
events:
- name: expect-to-supply
desc: Supplier indicates an intention to supply (ISO18626 ExpectToSupply)
transitions: [SUPPLIER_LOCATED]
transition: SUPPLIER_LOCATED
- name: will-supply
desc: Supplier will supply without conditions (ISO18626 WillSupply)
transitions: [WILL_SUPPLY]
transition: WILL_SUPPLY
- name: will-supply-conditional
desc: Supplier will supply with conditions (ISO18626 WillSupply with conditions)
transitions: [CONDITION_PENDING]
transition: CONDITION_PENDING
- name: loaned
desc: Supplier shipped the item (ISO18626 Loaned)
transitions: [SHIPPED]
transition: SHIPPED
- name: unfilled
desc: Supplier cannot supply (ISO18626 Unfilled)
transitions: [UNFILLED]
transition: UNFILLED

- name: SUPPLIER_LOCATED
display: Supplier Located
Expand All @@ -51,17 +53,18 @@ states:
actions:
- name: cancel-request
desc: Send ISO18626 Cancel request to supplier
transitions: [CANCEL_PENDING]
transitions:
success: CANCEL_PENDING
events:
- name: will-supply
desc: Supplier will supply without conditions (ISO18626 WillSupply)
transitions: [WILL_SUPPLY]
transition: WILL_SUPPLY
- name: will-supply-conditional
desc: Supplier will supply with conditions (ISO18626 WillSupply with conditions)
transitions: [CONDITION_PENDING]
transition: CONDITION_PENDING
- name: unfilled
desc: Supplier cannot supply (ISO18626 Unfilled)
transitions: [UNFILLED]
transition: UNFILLED

- name: CONDITION_PENDING
display: Condition Pending
Expand All @@ -70,10 +73,12 @@ states:
actions:
- name: accept-condition
desc: Accept supplier conditions (ISO18626 Notification)
transitions: [WILL_SUPPLY]
transitions:
success: WILL_SUPPLY
- name: reject-condition
desc: Reject supplier conditions (ISO18626 Cancel)
transitions: [CANCEL_PENDING]
transitions:
success: CANCEL_PENDING

- name: WILL_SUPPLY
display: Will Supply
Expand All @@ -82,14 +87,15 @@ states:
actions:
- name: cancel-request
desc: Send ISO18626 Cancel to supplier
transitions: [CANCEL_PENDING]
transitions:
success: CANCEL_PENDING
events:
- name: loaned
desc: Supplier shipped the item (ISO18626 Loaned)
transitions: [SHIPPED]
transition: SHIPPED
- name: unfilled
desc: Supplier cannot supply (ISO18626 Unfilled)
transitions: [UNFILLED]
transition: UNFILLED

- name: SHIPPED
display: Shipped
Expand All @@ -98,7 +104,8 @@ states:
actions:
- name: receive
desc: Receive and accept item in local ILS (via NCIP AcceptItem if enabled); send ISO18626 Received
transitions: [RECEIVED]
transitions:
success: RECEIVED

- name: RECEIVED
display: Received
Expand All @@ -107,7 +114,8 @@ states:
actions:
- name: check-out
desc: Check out item to patron (NCIP CheckOutItem)
transitions: [CHECKED_OUT]
transitions:
success: CHECKED_OUT

- name: CHECKED_OUT
display: Checked Out
Expand All @@ -116,7 +124,8 @@ states:
actions:
- name: check-in
desc: Check the item back-in (NCIP CheckInItem)
transitions: [CHECKED_IN]
transitions:
success: CHECKED_IN

- name: CHECKED_IN
display: Checked In
Expand All @@ -125,7 +134,8 @@ states:
actions:
- name: ship-return
desc: Send ISO18626 ShippedReturn and delete the temporary item (NCIP DeleteItem)
transitions: [SHIPPED_RETURNED]
transitions:
success: SHIPPED_RETURNED

- name: SHIPPED_RETURNED
display: Shipped Returned
Expand All @@ -134,7 +144,7 @@ states:
events:
- name: completed
desc: Supplier/broker signals loan/copy completion
transitions: [COMPLETED]
transition: COMPLETED

- name: CANCEL_PENDING
display: Cancel Pending
Expand All @@ -143,7 +153,7 @@ states:
events:
- name: cancel-accepted
desc: Supplier accepts cancellation
transitions: [CANCELLED]
transition: CANCELLED

- name: COMPLETED
display: Completed
Expand Down Expand Up @@ -171,7 +181,8 @@ states:
actions:
- name: validate
desc: Validate the request, e.g institutional patron via NCIP LookupUser, if enabled
transitions: [VALIDATED]
transitions:
success: VALIDATED

- name: VALIDATED
display: Validated
Expand All @@ -180,17 +191,20 @@ states:
actions:
- name: will-supply
desc: Indicate supplier will supply and send ISO18626 WillSupply
transitions: [WILL_SUPPLY]
transitions:
success: WILL_SUPPLY
- name: cannot-supply
desc: Indicate cannot supply and send ISO18626 Unfilled
transitions: [UNFILLED]
transitions:
success: UNFILLED
- name: add-condition
desc: Indicate will supply with conditions and send ISO18626 WillSupply
transitions: [CONDITION_PENDING]
transitions:
success: CONDITION_PENDING
events:
- name: cancel-request
desc: Requester sent ISO18626 Cancel
transitions: [CANCEL_REQUESTED]
transition: CANCEL_REQUESTED

- name: WILL_SUPPLY
display: Will Supply
Expand All @@ -199,17 +213,20 @@ states:
actions:
- name: add-condition
desc: Add conditions and notify requester
transitions: [CONDITION_PENDING]
transitions:
success: CONDITION_PENDING
- name: ship
desc: Mark shipped; send ISO Loaned; NCIP CheckOutItem
transitions: [SHIPPED]
transitions:
success: SHIPPED
- name: cannot-supply
desc: Indicate cannot supply
transitions: [UNFILLED]
transitions:
success: UNFILLED
events:
- name: cancel-request
desc: Requester sends ISO Cancel
transitions: [CANCEL_REQUESTED]
transition: CANCEL_REQUESTED

- name: CONDITION_PENDING
display: Condition Pending
Expand All @@ -218,17 +235,18 @@ states:
actions:
- name: cannot-supply
desc: Indicate cannot supply
transitions: [UNFILLED]
transitions:
success: UNFILLED
events:
- name: conditions-accepted
desc: Requester accepts conditions
transitions: [CONDITION_ACCEPTED]
transition: CONDITION_ACCEPTED
- name: condition-rejected
desc: Requester rejects conditions (auto-responder may mark unfilled)
transitions: [UNFILLED]
transition: UNFILLED
- name: cancel-request
desc: Requester sends ISO Cancel
transitions: [CANCEL_REQUESTED]
transition: CANCEL_REQUESTED

- name: CONDITION_ACCEPTED
display: Condition Accepted
Expand All @@ -237,14 +255,16 @@ states:
actions:
- name: ship
desc: Mark shipped; send ISO Loaned; NCIP CheckOutItem
transitions: [SHIPPED]
transitions:
success: SHIPPED
- name: cannot-supply
desc: Indicate cannot supply
transitions: [UNFILLED]
transitions:
success: UNFILLED
events:
- name: cancel-request
desc: Requester sends ISO Cancel
transitions: [CANCEL_REQUESTED]
transition: CANCEL_REQUESTED

- name: SHIPPED
display: Shipped
Expand All @@ -253,7 +273,7 @@ states:
events:
- name: shipped-return
desc: Requester sends ISO ShippedReturn
transitions: [SHIPPED_RETURN]
transition: SHIPPED_RETURN

- name: SHIPPED_RETURN
display: Shipped Return
Expand All @@ -262,7 +282,8 @@ states:
actions:
- name: mark-received
desc: Mark returned item received and complete (CheckInItem if configured)
transitions: [COMPLETED]
transitions:
success: COMPLETED

- name: CANCEL_REQUESTED
display: Cancel Requested
Expand All @@ -271,10 +292,12 @@ states:
actions:
- name: mark-cancelled
desc: Confirm cancellation
transitions: [CANCELLED]
transitions:
success: CANCELLED
- name: will-supply
desc: Resume supplying despite cancel request
transitions: [WILL_SUPPLY]
transitions:
success: WILL_SUPPLY

- name: COMPLETED
display: Completed
Expand Down
36 changes: 26 additions & 10 deletions misc/state-model.json
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,7 @@
"Action": {
"type": "object",
"additionalProperties": false,
"description": "Declares an action available while in this state.",
"properties": {
"name": {
"type": "string",
Expand All @@ -121,11 +122,28 @@
"type": "string",
"description": "Description of the action"
},
"trigger": {
"type": "string",
"description": "Trigger for the action",
"enum": [
"auto",
"manual"
],
"default": "manual"
Comment on lines +131 to +132
Copy link

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The trigger field in the Action schema has a default value of "manual", but JSON Schema's default keyword is only advisory for documentation purposes - it doesn't actually set default values during validation or parsing.

If you want actions to have a default trigger of "manual", you'll need to handle this in the application code that reads the state model. Alternatively, if the trigger field should be required, add it to the required array on line 150.

Suggested change
],
"default": "manual"
]

Copilot uses AI. Check for mistakes.
},
Comment on lines +125 to +133
Copy link

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new trigger field is added to the Action schema but is not currently used anywhere in the codebase. The field distinguishes between "auto" (automatically triggered) and "manual" (manually triggered by a user) actions.

Since this field is not currently utilized, consider:

  1. Adding documentation or comments explaining the intended use case for this field
  2. Ensuring that when this field is eventually used, the default value of "manual" is properly applied in the code that reads the state model (as JSON Schema defaults are not automatically enforced during deserialization)
  3. Whether any existing actions should be marked as "auto" to reflect their intended behavior

If this is being added for future functionality, that's fine, but it should be clearly documented.

Copilot uses AI. Check for mistakes.
"transitions": {
"type": "array",
"description": "List of all possible state transitions after performing the action. When no transitions are defined, the action is considered to be non-state-changing.",
"items": {
"type": "string"
"type": "object",
"description": "Action outcome to state transition mapping. When no transition is defined, the action is considered to be non-state-changing.",
"additionalProperties": false,
"properties": {
"success": {
"type": "string",
"description": "Target state when the action succeeds."
},
"failure": {
"type": "string",
"description": "Target state when the action fails."
}
}
}
},
Expand All @@ -137,6 +155,7 @@
"Event": {
"type": "object",
"additionalProperties": false,
"description": "Declares an event considered for transition while in this state.",
"properties": {
"name": {
"type": "string",
Expand All @@ -146,12 +165,9 @@
"type": "string",
"description": "Description of the event"
},
"transitions": {
"type": "array",
"description": "List of all possible state transitions after triggering the event. When no transitions are defined, the event is considered to be non-state-changing.",
"items": {
"type": "string"
}
"transition": {
"type": "string",
"description": "State transition after event has occurred. When no transition is defined, the event is considered to be non-state-changing."
}
},
"required": [
Expand Down