Tender states and commands
Status: Insurance Broker Core version 1.0.0 is repo-ready; Tender commands are API-only and nothing is sent to carriers.
The tender lifecycle is defined by a state machine contract. This page lists its states and commands and then lists, line by line, where the API contract that you actually call differs from it. Read the second table before you plan any work, because those differences change what a user can do.
Today (API)
States
| State | Meaning in the lifecycle | Terminal |
|---|---|---|
draft | Initial state of a new tender. | No |
preparing | Preparation has started. | No |
invitations_sent | Invitations are marked as sent; nothing leaves the system. | No |
responses_open | Carrier answers are being recorded. | No |
comparison | A comparison exists and is under review. | No |
recommended | A recommendation was made. | No |
decided | The customer decision is in place. | No |
closed | The tender is closed. | Yes |
cancelled | The tender was cancelled. | Yes |
no_result | The tender ended without a result. | Yes |
legal_review_required | The tender was stopped for legal review. | Yes |
Commands in the state machine
The contract is tender_v1.json. It has 22 allowed transitions. Capability means that a validated capability admission is required for the transition. Approval means that the contract requires a maker-checker approval with the proof type core_local_approval_proof_v1.
| From | Command | To | Role named by the state machine | Capability | Approval |
|---|---|---|---|---|---|
draft | prepare | preparing | Insurance Broker Advisor | Yes | No |
preparing | send_invitations | invitations_sent | Insurance Broker Advisor | Yes | No |
invitations_sent | open_responses | responses_open | Insurance Broker Advisor | Yes | No |
responses_open | start_comparison | comparison | Insurance Broker Advisor | Yes | No |
comparison | recommend | recommended | Insurance Broker Advisor | Yes | Yes |
recommended | decide | decided | Insurance Broker Advisor | Yes | Yes |
decided | close | closed | Insurance Broker Operations | No | No |
draft, preparing, invitations_sent, responses_open, comparison, recommended | cancel | cancelled | Insurance Broker Advisor | No | No |
invitations_sent, responses_open, comparison | mark_no_result | no_result | Insurance Broker Advisor | No | No |
draft, preparing, invitations_sent, responses_open, comparison, recommended | require_legal_review | legal_review_required | Insurance Broker Compliance | No | No |
Every transition requires evidence and carries the compensation value manual_review.
Forbidden transitions
Every other pair of state and command is forbidden: the contract declares all 110 pairs of 11 states and 10 commands, 22 allowed and 88 forbidden, and each forbidden pair has its own error code. In words: nothing leaves a terminal state; from decided only close is allowed, so cancelling, marking no result, and legal review are no longer possible; and a command cannot skip a step, for example send_invitations is forbidden from draft. The full matrix is on State machines.
Where the API differs from the state machine
You do not call the state machine directly. You call insurance_broker_core.api.tender.execute_tender_command with the command transition_tender, and that function reads its own contract, tender_command_api_v1.json. For the commands below the states and roles of the API contract equal the state machine; the API adds the requirements in the last column.
| Command | State machine | API contract | Consequence for you |
|---|---|---|---|
mark_no_result | From invitations_sent, responses_open, and comparison. | The same three states, role Insurance Broker Advisor. | From any other state the API answers IBC-TENDER-COMMAND-TRANSITION-001. |
require_legal_review | From six states, role Insurance Broker Compliance. | The same six states (draft, preparing, invitations_sent, responses_open, comparison, recommended), role Insurance Broker Compliance. | A user without the Compliance role gets IBC-TENDER-COMMAND-ROLE-001; every other state is rejected with IBC-TENDER-COMMAND-TRANSITION-001. |
recommend and decide | Maker-checker approval required. | The API always reports that no approval is present. | Both end with IBC-STATE-APPROVAL-001. See Recommendation and decision. |
cancel, mark_no_result, require_legal_review | The contract has no reason field; the transition code requires a Cancellation Reason. | The call must carry the field cancellation_reason (the API contract lists it as required for these three commands). | A missing field is answered with IBC-TENDER-COMMAND-PAYLOAD-002, an empty one with IBC-TENDER-COMMAND-PAYLOAD-003. The server stores the reason on the tender as part of the transition; you do not save it in the form first. |
close | Role Insurance Broker Operations. | Same role, plus a read permission check on the tender document. | Insurance Broker Operations holds read only on the Tender DocType and cannot edit the tender in the form; the state change happens only through this endpoint, after the company, role, and state checks. |
The commands prepare through decide also pass a capability check in the API under the process name comparison.
How an API call is built
The call takes two arguments, command and payload. For a state change, command is transition_tender and the payload has these fields.
| Field | Type | Required | Meaning |
|---|---|---|---|
company | text | Yes | The company scope of the tender. |
tender | text | Yes | The tender name. |
command | text | Yes | One of the ten commands above. |
expected_version | whole number | Yes | The value of the Aggregate Version field on the tender; a different value gives IBC-STATE-VERSION-001. |
After a successful transition the response carries the new status, the new aggregate version, and the name of the emitted event. Reload the form to see the new status. Details of each command follow on the next pages.
Errors on this page
| Code | When |
|---|---|
IBC-TENDER-COMMAND-UNKNOWN-001 | The command name is not in the API allowlist. |
IBC-TENDER-COMMAND-PAYLOAD-001, IBC-TENDER-COMMAND-PAYLOAD-002, IBC-TENDER-COMMAND-PAYLOAD-003 | The payload is not an object, a required field is missing, or a field is invalid. |
IBC-TENDER-COMMAND-SCOPE-001 | The company scope is missing, wrong, or not authorized. |
IBC-TENDER-COMMAND-ROLE-001 | You lack the role the API contract names. |
IBC-TENDER-COMMAND-TRANSITION-001 | The command is not allowed from the current state. |
IBC-STATE-VERSION-001 | The expected version differs from the stored version. |
Related pages
Planned Desk workflow
A Desk workflow for tender commands is planned. This page does not describe it and gives no date and no scope.