Finish and overrides
When the Finish button is enabled, the single-use finish receipt, what verifyFinish proves and does not prove, and finishing anyway with a written reason.
Finishing is the one moment that matters: the invoice is sent, the claim is submitted, the order is released. Immersive mode puts a guard on it that you can enforce on your server.
When Finish is enabled
canFinish from useBaseeraImmersiveState() is true when all of these hold:
- No blocking check is open, including AI checks that can block the finish.
- No blocking check failed to run (a check that throws is unknown, not passing).
- No warning is open when
blockOnWarningsis true. Acknowledging a warning unblocks it. - The record is not closed.
finish: {
label: { ar: "إرسال الفاتورة", en: "Send invoice" },
closed: invoice.status === "sent",
blockOnWarnings: false,
action: ({ receipt, override }) => sendInvoice(invoice.id, receipt, override),
},Prop
Type
Closed records
Set closed from your own data. A closed record shows "This record is closed" in place of the button, and finish() does nothing. It is a UI state. Your server must still refuse to change a closed record.
Why the button says it is disabled
The default bar prints each reason under the button: "1 issue blocks Send invoice", "2 warnings block Send invoice" or "Checks couldn't run; finish is disabled." In your own UI, read counts, openBlocking, checksFailed and finishStatus.
What finish() does
- Sends the queued trail events, so the trail reaches Baseera before the finish does.
- Records the finish with Baseera: the open blocking check ids and the override reason, if any. Baseera answers with a receipt,
fin_.... - Only then calls your
finish.action({ receipt, override }).
If step 2 fails (offline, refused, no session), your action does not run, finishStatus is error and finishError is record_failed. If your action throws after the receipt was issued, finishError is action_failed. The person finishes again to get a new receipt.
finish() resolves to whether your action ran.
The receipt
A receipt is valid for 10 minutes and for one verification. It is stored with who finished (user id and tenant id), when, the open blocking ids, the override and the screen it came from. Send it to your server in your action. See the record call in Other endpoints.
Verify on your server
verifyFinish from @baseera/node asks Baseera whether the receipt is real, fresh, unused and for this record.
const result = await verifyFinish({
receipt,
entity: { type: "invoice", ref: id },
openBlocking: computeBlockingIds(invoice), // from your own data
agentId: process.env.BASEERA_AGENT_ID!,
secretKey: process.env.BASEERA_SECRET_KEY!,
baseUrl: process.env.BASEERA_RUNTIME_URL!,
});On success you get { ok: true, finish: { userId, tenantId, openBlocking, override, createdAt } }. Otherwise { ok: false, code } where code is one of:
| Code | Meaning | Your answer |
|---|---|---|
receipt_not_found | Unknown, malformed, or another agent's receipt. | Refuse (409). |
entity_mismatch | The receipt was recorded for another record. | Refuse (409). |
receipt_expired | Older than 10 minutes. | Refuse. The person finishes again. |
receipt_used | Already verified once. | Refuse. Never process twice. |
override_required | A blocking check was open, and the override does not cover it. | Refuse (409). |
unavailable | Network error, timeout (5 seconds), redirect, non-200, malformed answer, bad key, or a non-HTTPS baseUrl (except localhost). | Refuse (503). The person retries. |
verifyFinish never throws and fails closed. It signs a fresh 60-second server token for every call. The key and the token are never logged or put in an error. A successful call uses the receipt up: if your route fails after it, the person finishes again.
What it proves
- Baseera recorded this finish first, for this record and this agent.
- It happened once, in the last 10 minutes.
- It records who finished and when.
- It records the blocking checks the browser said were open, and the override reason (10 to 1,000 characters) that must cover each of them.
- If you passed
openBlockingfrom your server, the override covers those too. This is the part that does not depend on the browser.
What it does not prove
- That the browser's checks were run honestly or returned true. They run in the browser.
- That the record on screen is the record in your database. Recompute from your data.
- That the person looked at the flags. It proves they pressed finish, and wrote a reason if one was needed.
So always compute your blocking checks on the server and pass them. If you pass none, a person who clears the browser's checks needs no override. A route that never calls verifyFinish gets none of this.
Override with a reason
When blocking checks are open, canFinish is false and canOverride is true. The person can still finish by writing why.
const { canOverride, finish } = useBaseeraImmersiveState();
<button
disabled={!canOverride}
onClick={() => void finish({ override: { reason } })}
>
Finish anyway
</button>reasonis 10 to 1,000 characters after trimming. Outside that range nothing is sent andfinishErrorisreason_required.- The SDK sends every open blocking check id. You cannot narrow it: the override has to cover all of them.
- Baseera stores the reason in the receipt and in the trail as an
overrideevent, and your server gets it back fromverifyFinish. - Closed records, checks that failed to run and, with
blockOnWarnings, open warnings cannot be overridden.
In the default bar, Finish anyway appears while blocking checks are open. It opens a box labelled "Why are you finishing with open issues?" with a counter, the message "Write a reason of 10 to 1000 characters." when it is out of range, and Confirm and finish and Cancel buttons.
To draw it yourself, pass renderFinish to BaseeraSurface. It receives { label, canFinish, busy, reasons, counts, checksFailed, closed, canOverride, openBlocking, error, finish }. Pass finish({ source: "panel" }) from your own panel so the trail says where it came from. Without it, finish() records source: "host".
Store the override reason with the record in your own database. It is written by the person for your audit.
Next steps
Notices and focus
How Baseera speaks up when a person pauses, how Later and Got it behave, how it moves them to a field, and what is not available yet.
Trail and webhook
The per-record trail of flags, fixes, approvals, overrides and the finish: event types, the dashboard timeline and JSON export, and the signed immersive.record.finished webhook.