Recommendation and decision

Status: Insurance Broker Core version 1.0.0 is repo-ready; Tender commands are API-only and nothing is sent to carriers.

This page covers the end of the tender lifecycle. Read the limits first: the two commands recommend and decide cannot be completed through the tender API today, so a tender cannot reach recommended or decided that way. The commands that end a tender early work within the narrower rules of the API contract.

Today (API)

Who does this

Insurance Broker Advisor runs recommend, decide, cancel, and the API versions of mark_no_result and require_legal_review. The state machine names Insurance Broker Operations for close and Insurance Broker Compliance for require_legal_review; see the differences in Tender states and commands.

Current limits

Command	What the state machine wants	What happens through the API
recommend	From comparison, with a maker-checker approval of the proof type core_local_approval_proof_v1.	The API always reports that no approval is present. After the check for a linked quote comparison, the call ends with IBC-STATE-APPROVAL-001.
decide	From recommended, with the same approval.	The tender cannot reach recommended. The command first checks the decision evidence described below (IBC-TENDER-004) and then also ends with IBC-STATE-APPROVAL-001.
close	From decided, role Insurance Broker Operations.	Only decided tenders can be closed, and none can reach decided through the API.

This is deliberate in the code: the API function never passes an approval, and the repository script scripts/verify_tender_command_api.py fails if the API source contains an approval flag set to true. The end-to-end test does not reach decided: it checks that recommend ends with IBC-STATE-APPROVAL-001 and that decide is refused, and the tender stays in comparison. No other way for a user to approve a tender is evidenced in the repository.

Steps: customer decision and remuneration disclosure

The evidence for a decision is stored in the Desk. These records are checked whenever a tender in decided is saved or commanded, and by decide.

1. Create an Insurance Broker Customer Decision. Required: Company, Advice Case, Decision (accept_recommendation, choose_alternative, decline, or defer), Decided At, Decision Maker, and Delivery Evidence. Selected Quote names the chosen quote. The name uses the series IB-DECISION- plus five digits.
2. Create an Insurance Broker Remuneration Disclosure. Required: Party Identity, Advice Case Reference, Agreement, Mode (commission, client_fee, or mixed), Amount Description, Content Digest, Customer Confirmation, and Status (draft, confirmed, or superseded). The roles Insurance Broker Operations and Insurance Broker Administrator can create it; Insurance Broker Compliance can edit it.
3. Open the tender, fill the fields Customer Decision and Remuneration Disclosure, and save.

Check	Code
The customer decision and the disclosure exist and are linked on the tender.	IBC-TENDER-004
Both belong to the advice case of the tender.	IBC-TENDER-004
The disclosure has status confirmed and a Customer Confirmation.	IBC-TENDER-004

Steps: cancel a tender

The cancellation reason is part of the API call. The server stores it on the tender when the transition succeeds; do not write it into the form yourself.

1. Call transition_tender with company, tender, the command cancel, expected_version, and cancellation_reason (a non-empty text).
2. Reload the form. Status is cancelled and Cancellation Reason shows the stored text.

Without the field the call fails with IBC-TENDER-COMMAND-PAYLOAD-002; with an empty text it fails with IBC-TENDER-COMMAND-PAYLOAD-003. The command is allowed from draft, preparing, invitations_sent, responses_open, comparison, and recommended, and does not need a capability admission.

Steps: end a tender without a result

1. Call transition_tender with company, tender, the command mark_no_result, expected_version, and cancellation_reason.

This works from invitations_sent, responses_open, and comparison, for the Advisor role. From any other state the API answers IBC-TENDER-COMMAND-TRANSITION-001.

Steps: stop a tender for legal review

1. Call transition_tender with company, tender, the command require_legal_review, expected_version, and cancellation_reason. The reason is mandatory for this command.

This works from draft, preparing, invitations_sent, responses_open, comparison, and recommended, and asks for the Compliance role. The tender ends in legal_review_required, a terminal state. Insurance Broker Compliance holds read only on the Tender DocType; the state change happens only through the endpoint after the company, role, and state checks.

Commands on this page

Command	Required fields	Role	Effect
recommend	company, tender, command, expected_version	Insurance Broker Advisor	Intended comparison to recommended; ends with IBC-STATE-APPROVAL-001.
decide	same four fields	Insurance Broker Advisor	Intended recommended to decided; not reachable.
close	same four fields	Insurance Broker Operations, plus read permission on the tender; the state change runs only through the endpoint	decided to closed; not reachable.
cancel	same four fields plus cancellation_reason	Insurance Broker Advisor	Six states to cancelled.
mark_no_result	same four fields plus cancellation_reason	Insurance Broker Advisor	invitations_sent, responses_open, and comparison to no_result.
require_legal_review	same four fields plus cancellation_reason	Insurance Broker Compliance	Six states to legal_review_required.

After a tender is decided

According to the state machine only close leaves decided. Cancelling, ending without a result, and legal review are forbidden from that state. Because decided cannot be reached through the API, no tender follows this path in the API today.

What the system checks

Code	Meaning
IBC-TENDER-004	Customer decision or confirmed remuneration disclosure missing or not matching.
IBC-TENDER-007	A terminal command or terminal state without a saved Cancellation Reason.
IBC-TENDER-008	recommend without a linked quote comparison.
IBC-STATE-APPROVAL-001	The transition needs an approval that the API does not supply.
IBC-TENDER-COMMAND-TRANSITION-001	The command is not allowed from the current state in the API contract.
IBC-TENDER-STATUS-COMMAND-001	A form save tried to change the Status.

Capability status

The capability matrix lists the process quote_comparison with default status model_only and no validated claims. The commands recommend and decide ask the admission check for the process named comparison. Only validated capabilities may be asserted publicly, and this page asserts none.

Related pages

• Tender overview
• Tender states and commands
• Responses and comparison
• Core domains

Planned Desk workflow

A Desk workflow for tender commands is planned. This page does not describe it and gives no date and no scope.