ILLDEV-316 primaryAction

broker/oapi/open-api.yaml

@@ -678,6 +678,10 @@ components:
           enum:
             - REQUESTER
             - SUPPLIER
+        primaryAction:
+          type: string
+          description: Name of the primary action for this state.
+            Must be one of the actions defined in the actions array and is only meaningful when actions is present.
         actions:
           type: array
           description: List of all actions that may be performed on the request when in this state

broker/patron_request/service/statemodel.go

@@ -135,6 +135,12 @@ func ValidateStateModel(stateModel *proapi.StateModel) error {
 				}
 			}
 		}
+		if state.PrimaryAction != nil && (state.Actions == nil || !slices.ContainsFunc(*state.Actions, func(a proapi.ModelAction) bool {
+			return a.Name == string(*state.PrimaryAction)
+		})) {
+			return fmt.Errorf("primary action %s undefined in state %s side %s", *state.PrimaryAction, state.Name, state.Side)
+		}
+
 		if state.Events != nil {
 			for _, event := range *state.Events {
 				if !slices.Contains(allowedEvents, event.Name) {

broker/patron_request/service/statemodel_test.go

@@ -35,6 +35,93 @@ func TestBuiltInStateModelCapabilities(t *testing.T) {
 	assert.True(t, slices.Contains(c.SupplierMessageEvents, string(SupplierCancelRejected)))
 }
 
+func TestValidateStateModelWithPrimaryAction(t *testing.T) {
+	s := "validate"
+	model := &proapi.StateModel{
+		Type:    proapi.StateModelTypeStateModel,
+		Name:    "test",
+		Version: "1.0.0",
+		States: []proapi.ModelState{
+			{
+				Name: "NEW",
+				Side: proapi.REQUESTER,
+				Actions: &[]proapi.ModelAction{
+					{Name: s},
+				},
+				PrimaryAction: &s,
+			},
+		},
+	}
+
+	err := ValidateStateModel(model)
+	assert.NoError(t, err)
+}
+
+func TestValidateStateModelWithoutPrimaryAction(t *testing.T) {
+	s := "validate"
+	model := &proapi.StateModel{
+		Type:    proapi.StateModelTypeStateModel,
+		Name:    "test",
+		Version: "1.0.0",
+		States: []proapi.ModelState{
+			{
+				Name: "NEW",
+				Side: proapi.REQUESTER,
+				Actions: &[]proapi.ModelAction{
+					{Name: s},
+				},
+			},
+		},
+	}
+
+	err := ValidateStateModel(model)
+	assert.NoError(t, err)
+}
+
+func TestValidateStateModelPrimaryActionUndefined(t *testing.T) {
+	s := "other"
+	model := &proapi.StateModel{
+		Type:    proapi.StateModelTypeStateModel,
+		Name:    "test",
+		Version: "1.0.0",
+		States: []proapi.ModelState{
+			{
+				Name: "NEW",
+				Side: proapi.REQUESTER,
+				Actions: &[]proapi.ModelAction{
+					{Name: "validate"},
+				},
+				PrimaryAction: &s,
+			},
+		},
+	}
+
+	err := ValidateStateModel(model)
+	assert.Error(t, err)
+	assert.Equal(t, "primary action other undefined in state NEW side REQUESTER", err.Error())
+}
+
+func TestValidateStateModelPrimaryActionNoActionsDefined(t *testing.T) {
+	s := "other"
+	model := &proapi.StateModel{
+		Type:    proapi.StateModelTypeStateModel,
+		Name:    "test",
+		Version: "1.0.0",
+		States: []proapi.ModelState{
+			{
+				Name:          "NEW",
+				Side:          proapi.REQUESTER,
+				Actions:       nil,
+				PrimaryAction: &s,
+			},
+		},
+	}
+
+	err := ValidateStateModel(model)
+	assert.Error(t, err)
+	assert.Equal(t, "primary action other undefined in state NEW side REQUESTER", err.Error())
+}
+
 func TestValidateStateModelInvalidRequesterAction(t *testing.T) {
 	model := &proapi.StateModel{
 		Type:    proapi.StateModelTypeStateModel,

broker/patron_request/service/statemodels/returnables.json

@@ -9,6 +9,7 @@
       "display": "New",
       "desc": "Initial state after Patron Request is created (POST)",
       "side": "REQUESTER",
+      "primaryAction": "validate",
       "actions": [
         {
           "name": "validate",
@@ -25,6 +26,7 @@
       "display": "Validated",
       "desc": "Patron Request is valid",
       "side": "REQUESTER",
+      "primaryAction": "send-request",
       "actions": [
         {
           "name": "send-request",
@@ -73,6 +75,7 @@
       "display": "Supplier Located",
       "desc": "After receiving ISO ExpectToSupply",
       "side": "REQUESTER",
+      "primaryAction": "cancel-request",
       "actions": [
         {
           "name": "cancel-request",
@@ -105,6 +108,7 @@
       "display": "Condition Pending",
       "desc": "Received supply conditions",
       "side": "REQUESTER",
+      "primaryAction": "accept-condition",
       "actions": [
         {
           "name": "accept-condition",
@@ -127,6 +131,7 @@
       "display": "Will Supply",
       "desc": "Received ISO18626 WillSupply (without condition)",
       "side": "REQUESTER",
+      "primaryAction": "cancel-request",
       "actions": [
         {
           "name": "cancel-request",
@@ -154,6 +159,7 @@
       "display": "Shipped",
       "desc": "After receiving ISO18626 Loaned",
       "side": "REQUESTER",
+      "primaryAction": "receive",
       "actions": [
         {
           "name": "receive",
@@ -169,6 +175,7 @@
       "display": "Received",
       "desc": "Item received and accepted into local ILS.",
       "side": "REQUESTER",
+      "primaryAction": "check-out",
       "actions": [
         {
           "name": "check-out",
@@ -184,6 +191,7 @@
       "display": "Checked Out",
       "desc": "Item is checked out to patron",
       "side": "REQUESTER",
+      "primaryAction": "check-in",
       "actions": [
         {
           "name": "check-in",
@@ -199,6 +207,7 @@
       "display": "Checked In",
       "desc": "Item is checked back in to the local ILS",
       "side": "REQUESTER",
+      "primaryAction": "ship-return",
       "actions": [
         {
           "name": "ship-return",
@@ -266,6 +275,7 @@
       "display": "New",
       "desc": "Item is created on the supplier side for local fulfillment",
       "side": "SUPPLIER",
+      "primaryAction": "validate",
       "actions": [
         {
           "name": "validate",
@@ -282,6 +292,7 @@
       "display": "Validated",
       "desc": "Request is valid",
       "side": "SUPPLIER",
+      "primaryAction": "will-supply",
       "actions": [
         {
           "name": "will-supply",
@@ -319,6 +330,7 @@
       "display": "Will Supply",
       "desc": "After manual will-supply or successful auto-responder",
       "side": "SUPPLIER",
+      "primaryAction": "ship",
       "actions": [
         {
           "name": "add-condition",
@@ -355,6 +367,7 @@
       "display": "Condition Pending",
       "desc": "Conditions are sent with a special ISO WillSupply",
       "side": "SUPPLIER",
+      "primaryAction": "cannot-supply",
       "actions": [
         {
           "name": "cannot-supply",
@@ -387,6 +400,7 @@
       "display": "Condition Accepted",
       "desc": "After receiving conditions accepted notification",
       "side": "SUPPLIER",
+      "primaryAction": "ship",
       "actions": [
         {
           "name": "ship",
@@ -442,6 +456,7 @@
       "display": "Shipped Return",
       "desc": "After receiving ISO ShippedReturn message",
       "side": "SUPPLIER",
+      "primaryAction": "mark-received",
       "actions": [
         {
           "name": "mark-received",
@@ -457,6 +472,7 @@
       "display": "Cancel Requested",
       "desc": "After receiving ISO18626 Cancel from requester",
       "side": "SUPPLIER",
+      "primaryAction": "accept-cancel",
       "actions": [
         {
           "name": "accept-cancel",

misc/returnables.yaml

@@ -9,6 +9,7 @@ states:
     display: New
     desc: Initial state after Patron Request is created (POST)
     side: REQUESTER
+    primaryAction: validate
     actions:
       - name: validate
         desc: Validate the request (e.g. check patron via NCIP LookupUser, if enabled)
@@ -20,6 +21,7 @@ states:
     display: Validated
     desc: Patron Request is valid
     side: REQUESTER
+    primaryAction: send-request
     actions:
       - name: send-request
         desc: Send ISO18626 request to the supplier or broker
@@ -51,6 +53,7 @@ states:
     display: Supplier Located
     desc: After receiving ISO ExpectToSupply
     side: REQUESTER
+    primaryAction: cancel-request
     actions:
       - name: cancel-request
         desc: Send ISO18626 Cancel request to supplier
@@ -71,6 +74,7 @@ states:
     display: Condition Pending
     desc: Received supply conditions
     side: REQUESTER
+    primaryAction: accept-condition
     actions:
       - name: accept-condition
         desc: Accept supplier conditions (ISO18626 Notification)
@@ -85,6 +89,7 @@ states:
     display: Will Supply
     desc: Received ISO18626 WillSupply (without condition)
     side: REQUESTER
+    primaryAction: cancel-request
     actions:
       - name: cancel-request
         desc: Send ISO18626 Cancel to supplier
@@ -102,6 +107,7 @@ states:
     display: Shipped
     desc: After receiving ISO18626 Loaned
     side: REQUESTER
+    primaryAction: receive
     actions:
       - name: receive
         desc: Receive and accept item in local ILS (via NCIP AcceptItem if enabled); send ISO18626 Received
@@ -112,6 +118,7 @@ states:
     display: Received
     desc: Item received and accepted into local ILS.
     side: REQUESTER
+    primaryAction: check-out
     actions:
       - name: check-out
         desc: Check out item to patron (NCIP CheckOutItem)
@@ -122,6 +129,7 @@ states:
     display: Checked Out
     desc: Item is checked out to patron
     side: REQUESTER
+    primaryAction: check-in
     actions:
       - name: check-in
         desc: Check the item back-in (NCIP CheckInItem)
@@ -132,6 +140,7 @@ states:
     display: Checked In
     desc: Item is checked back in to the local ILS
     side: REQUESTER
+    primaryAction: ship-return
     actions:
       - name: ship-return
         desc: Send ISO18626 ShippedReturn and delete the temporary item (NCIP DeleteItem)
@@ -182,6 +191,7 @@ states:
     display: New
     desc: Item is created on the supplier side for local fulfillment
     side: SUPPLIER
+    primaryAction: validate
     actions:
       - name: validate
         desc: Validate the request, e.g institutional patron via NCIP LookupUser, if enabled
@@ -193,6 +203,7 @@ states:
     display: Validated
     desc: Request is valid
     side: SUPPLIER
+    primaryAction: will-supply
     actions:
       - name: will-supply
         desc: Indicate supplier will supply and send ISO18626 WillSupply
@@ -216,6 +227,7 @@ states:
     display: Will Supply
     desc: After manual will-supply or successful auto-responder
     side: SUPPLIER
+    primaryAction: ship
     actions:
       - name: add-condition
         desc: Add conditions and notify requester
@@ -238,6 +250,7 @@ states:
     display: Condition Pending
     desc: Conditions are sent with a special ISO WillSupply
     side: SUPPLIER
+    primaryAction: cannot-supply
     actions:
       - name: cannot-supply
         desc: Indicate cannot supply
@@ -258,6 +271,7 @@ states:
     display: Condition Accepted
     desc: After receiving conditions accepted notification
     side: SUPPLIER
+    primaryAction: ship
     actions:
       - name: ship
         desc: Mark shipped; send ISO Loaned; NCIP CheckOutItem
@@ -294,6 +308,7 @@ states:
     display: Shipped Return
     desc: After receiving ISO ShippedReturn message
     side: SUPPLIER
+    primaryAction: mark-received
     actions:
       - name: mark-received
         desc: Mark returned item received and complete (CheckInItem if configured)
@@ -304,6 +319,7 @@ states:
     display: Cancel Requested
     desc: After receiving ISO18626 Cancel from requester
     side: SUPPLIER
+    primaryAction: accept-cancel
     actions:
       - name: accept-cancel
         desc: Confirm cancellation

misc/state-model.json

@@ -63,6 +63,10 @@
                         "SUPPLIER"
                     ]
                 },
+                "primaryAction": {
+                    "type": "string",
+                    "description": "Indicates the primary action for the state, i.e., the most common or recommended action to be performed when in the state. The value must match the name of one of the actions defined for the state."
+                },
                 "actions": {
                     "type": "array",
                     "description": "List of all actions that may be performed on the request when in this state",