Skip to Content
Baseera Docs

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 blockOnWarnings is 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

  1. Sends the queued trail events, so the trail reaches Baseera before the finish does.
  2. Records the finish with Baseera: the open blocking check ids and the override reason, if any. Baseera answers with a receipt, fin_....
  3. 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:

CodeMeaningYour answer
receipt_not_foundUnknown, malformed, or another agent's receipt.Refuse (409).
entity_mismatchThe receipt was recorded for another record.Refuse (409).
receipt_expiredOlder than 10 minutes.Refuse. The person finishes again.
receipt_usedAlready verified once.Refuse. Never process twice.
override_requiredA blocking check was open, and the override does not cover it.Refuse (409).
unavailableNetwork 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 openBlocking from 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>
  • reason is 10 to 1,000 characters after trimming. Outside that range nothing is sent and finishError is reason_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 override event, and your server gets it back from verifyFinish.
  • 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

On this page