state-models.yaml

stateModels:
  returnables:
    type: StateModel
    name: CrossLink Returnables State Model
    desc: "Requester/Supplier workflow per ISO18626, including NCIP integration and ISO status events."
    version: 1.0.0
    selector:
      serviceType: [Copy, Loan, CopyOrLoan]
    states:
      # ── REQUESTER states ──────────────────────────────────────────────────────
      - name: NEW
        display: New
        desc: Initial state after Patron Request is created (POST)
        side: REQUESTER
        initial: true
        primaryAction: validate
        actions:
          - name: validate
            desc: "Validate the request (e.g. check patron via NCIP LookupUser, if enabled)"
            transitions:
              success: VALIDATED
              review: NEEDS_REVIEW
            trigger: auto

      - name: VALIDATED
        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
            transitions:
              success: SENT
              duplicate: CLOSED_DUPLICATE
            trigger: auto

      - name: NEEDS_REVIEW
        display: Needs review
        desc: Request is valid but needs staff review before sending
        side: REQUESTER
        primaryAction: send-request
        needsAttention: true
        editable: true
        actions:
          - name: send-request
            desc: Send ISO18626 request to the supplier or broker
            transitions:
              success: SENT
              duplicate: CLOSED_DUPLICATE

      - name: LOCAL_SUPPLY
        display: Local Supply
        desc: The requested item is available locally
        side: REQUESTER
        primaryAction: fill-locally
        needsAttention: true
        editable: true
        # Audit-only events emitted by local-supply actions. Do not configure
        # transitions as they are ignored, use action transitions instead.
        events:
          - name: completed-local
            desc: Local-supply completion recorded for audit
          - name: cancelled-local
            desc: Local-supply cancellation recorded for audit
          - name: unfilled-local
            desc: Local-supply failure recorded for audit
        actions:
          - name: fill-locally
            desc: Fill the request locally
            transitions:
              success: COMPLETED
          - name: cancel-local-supply
            desc: Cancel the local supply
            transitions:
              success: CANCELLED
          - name: cannot-supply-locally
            desc: Cannot supply locally
            transitions:
              success: SENT

      - name: SENT
        display: Sent
        desc: Request is sent
        side: REQUESTER
        events:
          - name: expect-to-supply
            desc: "Supplier indicates an intention to supply (ISO18626 ExpectToSupply)"
            transition: SUPPLIER_LOCATED
          - name: expect-to-supply-local
            desc: "Local supplier indicates an intention to supply (ISO18626 ExpectToSupply)"
            transition: LOCAL_SUPPLY
          - name: will-supply
            desc: "Supplier will supply without conditions (ISO18626 WillSupply)"
            transition: WILL_SUPPLY
          - name: will-supply-conditional
            desc: "Supplier will supply with conditions (ISO18626 WillSupply with conditions)"
            transition: CONDITION_PENDING
          - name: loaned
            desc: "Supplier shipped the item (ISO18626 Loaned)"
            transition: SHIPPED
          - name: unfilled
            desc: "Supplier cannot supply (ISO18626 Unfilled)"
            transition: UNFILLED
          - name: retry-conditional
            desc: Received retry from supplier
            transition: RETRY_PENDING

      - name: SUPPLIER_LOCATED
        display: Supplier Located
        desc: After receiving ISO ExpectToSupply
        side: REQUESTER
        primaryAction: cancel-request
        actions:
          - name: cancel-request
            desc: Send ISO18626 Cancel request to supplier
            transitions:
              success: CANCEL_PENDING
        events:
          - name: will-supply
            desc: "Supplier will supply without conditions (ISO18626 WillSupply)"
            transition: WILL_SUPPLY
          - name: will-supply-conditional
            desc: "Supplier will supply with conditions (ISO18626 WillSupply with conditions)"
            transition: CONDITION_PENDING
          - name: retry-conditional
            desc: Received retry from supplier
            transition: RETRY_PENDING
          - name: loaned
            desc: "Supplier shipped the item (ISO18626 Loaned)"
            transition: SHIPPED
          - name: unfilled
            desc: "Supplier cannot supply (ISO18626 Unfilled)"
            transition: UNFILLED

      - name: CONDITION_PENDING
        display: Condition Pending
        desc: Received supply conditions
        side: REQUESTER
        primaryAction: accept-condition
        needsAttention: true
        actions:
          - name: accept-condition
            desc: "Accept supplier conditions (ISO18626 Notification)"
            transitions:
              success: WILL_SUPPLY
          - name: reject-condition
            desc: "Reject supplier conditions (ISO18626 Cancel)"
            transitions:
              success: CANCEL_PENDING
        events:
          - name: will-supply-conditional
            desc: Supplier updates/extends conditions while still pending
            transition: CONDITION_PENDING
          - name: unfilled
            desc: "Supplier cannot supply (ISO18626 Unfilled)"
            transition: UNFILLED

      - name: RETRY_PENDING
        display: Retry Pending
        desc: "Received ISO18626 RetryPossible from supplier (may include updated metadata/conditions)"
        side: REQUESTER
        primaryAction: accept-retry
        needsAttention: true
        actions:
          - name: accept-retry
            desc: Requester accepts supplier retry request
            transitions:
              success: RETRY_ACCEPTED
          - name: reject-retry
            desc: Requester rejects supplier retry request
            transitions:
              success: RETRY_REJECTED

      - name: WILL_SUPPLY
        display: Will Supply
        desc: "Received ISO18626 WillSupply (without condition)"
        side: REQUESTER
        primaryAction: cancel-request
        actions:
          - name: cancel-request
            desc: Send ISO18626 Cancel to supplier
            transitions:
              success: CANCEL_PENDING
        events:
          - name: will-supply-conditional
            desc: "Supplier adds conditions after initial WillSupply (ISO18626 WillSupply with conditions)"
            transition: CONDITION_PENDING
          - name: retry-conditional
            desc: Received retry from supplier
            transition: RETRY_PENDING
          - name: loaned
            desc: "Supplier shipped the item (ISO18626 Loaned)"
            transition: SHIPPED
          - name: unfilled
            desc: "Supplier cannot supply (ISO18626 Unfilled)"
            transition: UNFILLED

      - name: SHIPPED
        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"
            transitions:
              success: RECEIVED
          - name: send-notification
            desc: Send email notification when item is shipped
            trigger: auto
            params:
              sendTo:
                - patron
              templateLabel: shipped-notification

      - name: RECEIVED
        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)
            transitions:
              success: CHECKED_OUT

      - name: CHECKED_OUT
        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)
            transitions:
              success: CHECKED_IN

      - name: CHECKED_IN
        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)"
            transitions:
              success: SHIPPED_RETURNED

      - name: SHIPPED_RETURNED
        display: Shipped Returned
        desc: Item is in return shipment
        side: REQUESTER
        events:
          - name: completed
            desc: Supplier/broker signals loan/copy completion
            transition: COMPLETED

      - name: CANCEL_PENDING
        display: Cancel Pending
        desc: ISO18626 Cancel action is sent to supplier/broker
        side: REQUESTER
        events:
          - name: cancel-accepted
            desc: Supplier accepts cancellation
            transition: CANCELLED
          - name: cancel-rejected
            desc: Supplier rejects cancellation
            transition: WILL_SUPPLY

      - name: COMPLETED
        display: Completed
        desc: Received LoanCompleted or CopyCompleted from the supplier/broker
        side: REQUESTER
        terminal: true

      - name: CANCELLED
        display: Cancelled
        desc: Cancel response is received
        side: REQUESTER
        terminal: true

      - name: UNFILLED
        display: Unfilled
        desc: Unfilled response is received
        side: REQUESTER
        terminal: true
        actions:
          - name: send-notification
            desc: Send email notification when item is unfilled
            trigger: auto
            params:
              sendTo:
                - patron
              templateLabel: unfilled-notification

      - name: RETRY_ACCEPTED
        display: Retry Accepted
        desc: Requester accepted supplier retry request with new metadata
        side: REQUESTER
        terminal: true

      - name: RETRY_REJECTED
        display: Retry Rejected
        desc: Requester rejected supplier retry request
        side: REQUESTER
        terminal: true

      - name: MANUALLY_CLOSED
        display: Manually closed
        desc: Closed manually by staff
        side: REQUESTER
        terminal: true
        manualClose: true

      - name: CLOSED_DUPLICATE
        display: Closed Duplicate
        desc: Closed due to duplicate request
        side: REQUESTER
        terminal: true

      # ── SUPPLIER states ──────────────────────────────────────────────────────
      - name: NEW
        display: New
        desc: Item is created on the supplier side for local fulfillment
        side: SUPPLIER
        initial: true
        primaryAction: validate
        actions:
          - name: validate
            desc: "Validate the request, e.g institutional patron via NCIP LookupUser, if enabled"
            transitions:
              success: VALIDATED
            trigger: auto

      - name: VALIDATED
        display: Validated
        desc: Request is valid
        side: SUPPLIER
        primaryAction: will-supply
        closingAction: cannot-supply
        actions:
          - name: will-supply
            desc: Indicate supplier will supply and send ISO18626 WillSupply
            transitions:
              success: WILL_SUPPLY
            trigger: auto
          - name: cannot-supply
            desc: Indicate cannot supply and send ISO18626 Unfilled
            transitions:
              success: UNFILLED
          - name: add-condition
            desc: Indicate will supply with conditions and send ISO18626 WillSupply
            transitions:
              success: CONDITION_PENDING
          - name: ask-retry
            desc: Ask requester to retry with new ISO18626 metadata
            transitions:
              success: COMPLETED_WITH_RETRY
          - name: send-notification
            desc: Send email notification when item is validated
            trigger: auto
            params:
              sendTo:
                - patron
              templateLabel: validated-notification
        events:
          - name: cancel-request
            desc: Requester sent ISO18626 Cancel
            transition: CANCEL_REQUESTED

      - name: WILL_SUPPLY
        display: Will Supply
        desc: After manual will-supply or successful auto-responder
        side: SUPPLIER
        primaryAction: ship
        closingAction: cannot-supply
        actions:
          - name: add-condition
            desc: Add conditions and notify requester
            transitions:
              success: CONDITION_PENDING
          - name: ship
            desc: "Mark shipped; send ISO Loaned; NCIP CheckOutItem"
            transitions:
              success: SHIPPED
          - name: cannot-supply
            desc: Indicate cannot supply
            transitions:
              success: UNFILLED
          - name: ask-retry
            desc: Ask requester to retry with new ISO18626 metadata
            transitions:
              success: COMPLETED_WITH_RETRY
        events:
          - name: cancel-request
            desc: Requester sends ISO Cancel
            transition: CANCEL_REQUESTED

      - name: CONDITION_PENDING
        display: Condition Pending
        desc: Conditions are sent with a special ISO WillSupply
        side: SUPPLIER
        primaryAction: cannot-supply
        closingAction: cannot-supply
        actions:
          - name: add-condition
            desc: Add additional conditions and notify requester
            transitions:
              success: CONDITION_PENDING
          - name: cannot-supply
            desc: Indicate cannot supply
            transitions:
              success: UNFILLED
        events:
          - name: conditions-accepted
            desc: Requester accepts conditions
            transition: CONDITION_ACCEPTED
          - name: condition-rejected
            desc: Requester rejects conditions
            transition: CANCEL_REQUESTED
          - name: cancel-request
            desc: Requester sends ISO Cancel
            transition: CANCEL_REQUESTED

      - name: CONDITION_ACCEPTED
        display: Condition Accepted
        desc: After receiving conditions accepted notification
        side: SUPPLIER
        primaryAction: ship
        closingAction: cannot-supply
        actions:
          - name: add-condition
            desc: Add additional conditions and notify requester
            transitions:
              success: CONDITION_PENDING
          - name: ship
            desc: "Mark shipped; send ISO Loaned; NCIP CheckOutItem"
            transitions:
              success: SHIPPED
          - name: cannot-supply
            desc: Indicate cannot supply
            transitions:
              success: UNFILLED
        events:
          - name: cancel-request
            desc: Requester sends ISO Cancel
            transition: CANCEL_REQUESTED

      - name: SHIPPED
        display: Shipped
        desc: "After marking shipped and sending ISO Loaned; NCIP CheckOutItem"
        side: SUPPLIER
        events:
          - name: received
            desc: Requester sends ISO Received
            transition: RECEIVED

      - name: RECEIVED
        display: Received
        desc: Requester has received the shipped item
        side: SUPPLIER
        events:
          - name: shipped-return
            desc: Requester sends ISO ShippedReturn
            transition: SHIPPED_RETURN

      - name: SHIPPED_RETURN
        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)"
            transitions:
              success: COMPLETED

      - name: CANCEL_REQUESTED
        display: Cancel Requested
        desc: After receiving ISO18626 Cancel from requester
        side: SUPPLIER
        needsAttention: true
        primaryAction: accept-cancel
        actions:
          - name: accept-cancel
            desc: Confirm cancellation
            transitions:
              success: CANCELLED
          - name: reject-cancel
            desc: Resume supplying despite cancel request
            transitions:
              success: WILL_SUPPLY

      - name: COMPLETED
        display: Completed
        desc: "After marking received and successful NCIP CheckInItem (if configured)"
        side: SUPPLIER
        terminal: true

      - name: CANCELLED
        display: Cancelled
        desc: After marking cancelled or automatically if auto-cancellation is on
        side: SUPPLIER
        terminal: true

      - name: UNFILLED
        display: Unfilled
        desc: After manual cannot-supply or automatically if auto-responder is on
        side: SUPPLIER
        terminal: true

      - name: COMPLETED_WITH_RETRY
        display: Completed with Retry
        desc: After sending retry to requester
        side: SUPPLIER
        terminal: true

      - name: MANUALLY_CLOSED
        display: Manually closed
        desc: Closed manually by staff
        side: SUPPLIER
        terminal: true
        manualClose: true

batchActionDefaults:
  - actionName: email-pullslips
    titleKey: email-pullslips
    title: Email pull slips ready to ship
    batchQuery: side = lending and state = WILL_SUPPLY
    schedule: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=6;BYMINUTE=0"
    actionParams:
      to:
        - staff@example.com
      templateLabel: pullslip-email
      includePdf: true

  - actionName: request-aging
    titleKey: request-aging-express
    title: Request aging of express requests
    batchQuery: "side = lending and (state = VALIDATED or state = WILL_SUPPLY or state = CONDITION_PENDING or state = CONDITION_ACCEPTED) and service_level = Express"
    schedule: "FREQ=MINUTELY;INTERVAL=15"
    actionParams:
      interval: 2h

  - actionName: request-aging
    titleKey: request-aging-rush
    title: Request aging of rush requests
    batchQuery: "side = lending and (state = VALIDATED or state = WILL_SUPPLY or state = CONDITION_PENDING or state = CONDITION_ACCEPTED) and service_level = Rush"
    schedule: "FREQ=HOURLY;BYMINUTE=0"
    actionParams:
      interval: 24h

  - actionName: request-aging
    titleKey: request-aging-all
    title: Request aging of all requests
    batchQuery: "side = lending and (state = VALIDATED or state = WILL_SUPPLY or state = CONDITION_PENDING or state = CONDITION_ACCEPTED)"
    schedule: "FREQ=DAILY;BYHOUR=5;BYMINUTE=0"
    actionParams:
      interval: 72h

templateDefaults:
  - title: Scheduled pullslips email template
    labels:
      - pullslip-email
    subject: "Scheduled pullslips"
    contentType: html
    audience: staff
    purpose: email
    body: |
      <p>This is an automated pull slip summary.</p>
      <p>
        <strong>Query:</strong> {{batchQuery}}<br>
        <strong>Matching requests:</strong> {{actualCount}} (of {{fullCount}} total)
      </p>
      <p>Please process the attached pull slips at your earliest convenience.</p>