Cases

cases tracks what goes wrong or needs changing in an organization, from the report to a verified close. A case has a kind (a nonconformity, a complaint, an incident), moves through its kind's pipeline, gets a root cause and actions, and closes only once nothing that its kind requires is missing.

better-supabase add cases

import { createCases } from "better-supabase/blocks/cases";

The module requires tenant, permissions, subjects and pipelines. With tasks a case's actions are work items. With numbering the number after a kind's prefix comes from a case sequence; without it the number is the case's position in the organization. With forms a public form opens cases, with relations and drive a case names the documents it affects, with notifications the owner hears about a due effectiveness check, with outbox it records the events, and with audit every change is audited.

TablesCopy Anchor Link

Members with cases.read read every table. Writes go through the functions below. A case is a subject of type case, so comments, attachments, tags and the other subject blocks work on it.

A case's owner may change and close their own case without cases.write or cases.close.

KindsCopy Anchor Link

Every organization starts with options.kinds. Each kind gets its own pipeline with the stages reported, investigating, acting, verifying, closed and canceled, so an organization can add or rename stages per kind.

saveKind adds a kind or, with kindId, changes one; it needs cases.manage. archiveKind stops new cases of a kind and keeps the old ones.

await db.cases
  .saveKind({
    key: "spill",
    name: "Chemical spill",
    prefix: "SPL",
    requiresEffectiveness: true,
    effectivenessAfterDays: 30,
  })
  .orThrow();

Opening and working a caseCopy Anchor Link

Server code calls the cases instance on db, in the caller's organization:

const opened = await db.cases
  .open({
    kind: "nonconformity",
    title: "Burr on housing edge",
    severity: "high",
    source: "inspection",
    ownerId,
  })
  .orThrow();
// opened.number starts with the kind's prefix: "NC-"

await db.cases.recordRootCause(opened.id, "Worn deburring tool").orThrow();

await db.cases
  .createAction(opened.id, {
    type: "corrective",
    title: "Replace the deburring tool and add it to maintenance",
    assigneeId,
  })
  .orThrow();

open needs cases.create and puts the case on the first stage of its kind's pipeline. The severity must be one of options.severities and the source one of options.sources. createAction adds a work item through the tasks block, and linkAction makes an existing one an action. An action is required by default: closing waits until its work item is completed or canceled.

move puts a case on another stage of its pipeline, which the case board recipe does when a card is dragged. A stage's outcome sets the case's status: open, closed or canceled.

The close guardCopy Anchor Link

blockers returns what still stops a case from closing, in this order:

close and a move to a closing stage fail with the first blocker's code, and every blocker in the error detail, while one remains. reopen takes a closed or canceled case back to its pipeline's first stage, and cancel ends an open case without the guard.

const blockers = await db.cases.blockers(opened.id).orThrow();

if (blockers.length === 0) {
  await db.cases.close(opened.id, "Tool replaced, no new burrs").orThrow();
}

The case detail recipe shows the blockers and enables its Close button once there are none.

Approval before closingCopy Anchor Link

With approvals, a tenant can require a decision before a case closes. Set a policy for the subject type case and the action close (a floor in options.policies, or a tenant policy). While that policy asks for a confirmation or an approver, the case has the blocker CASE_APPROVAL_REQUIRED. The case's owner, or anyone who writes cases, files the request with request_approval for the case subject, action close, and the approvers decide it in the usual way.

Once the request is approved the case moves to its first success stage, unless another blocker remains, in which case it stays open and the blockers show. An approval stays valid for the case, so a reopened case that closes again doesn't ask again.

VersionsCopy Anchor Link

With versions, closing a case freezes it as a version labeled Closed <number>, with the case as it closed: its root cause, status, effectiveness and close note. A later reopen and close adds another version.

EffectivenessCopy Anchor Link

A kind with effectivenessAfterDays sets a case's effectivenessDueOn that many days after its last required action is done. recordEffectiveness records whether the actions worked; false keeps the case from closing until a later check passes.

Run notifyDueEffectiveness daily with the service role; the block's effectiveness-due schedule does that at 06:00. It records case.effectiveness_date_reached once for each due check and notifies the owner.

Intake through formsCopy Anchor Link

case_from_submission is a forms submission handler. It opens a case from the answers kind (else options.intakeKind), title, description, severity, source, occurredAt, name, email and phone, also for an anonymous public form, and links the submission to the case.

blocks: {
  forms: {
    options: { handlers: { complaint: "better_supabase.case_from_submission" } },
  },
},

With medications and its missedCaseKind option, a missed dose opens a case of that kind.

MethodsCopy Anchor Link

list filters by kind, status, severity, source, owner, stage, overdue and search, with limit and cursor.

OptionsCopy Anchor Link

ErrorsCopy Anchor Link

The blocker codes above are errors too, from close and from a move to a closing stage; the error's detail lists every blocker.

EventsCopy Anchor Link

case_kind.created, case_kind.updated, case_kind.archived, case.created, case.updated, case.root_cause_recorded, case_action.created, case_action.deleted, case.effectiveness_recorded, case.effectiveness_date_reached, case.closed, case.reopened and case.cancelled. The events page lists their payloads.

Without the clientCopy Anchor Link

db.cases is this client. Code that does not go through bsb.db() builds it with a transport and an organization id:

const cases = createCases({ transport, tenant: organizationId });

const opened = await cases
  .open({ kind: "complaint", title: "Late delivery" })
  .orThrow();