How-To Do This

How to build CaseFlow

Build controlled case stages, intake, work queues, documents, decisions, approvals, SLAs, and replayable history.

CaseFlow is a case and process management pattern. This guide turns the product concept into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Define the outcome before the screens

Move a case through a defined process while accumulating participants, documents, messages, work, decisions, and approvals—with every transition explainable and properly authorized.

1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

Relationship rule: Make the case the coordination record while participants, files, conversations, and business records remain canonical and permissioned in their native models.

2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

• Role-aware case queue with SLA and stage filters.
• Structured intake form.
• Case 360 with timeline, parties, files, messages, and tasks.
• Reviewer checklist and evidence workspace.
• Decision/approval and audit replay views.

Use Puck for the normal visual experience. Keep stable block identity when using Monaco advanced JSON mode so future template upgrades can merge safely.

3. Set access before adding automation

• Scope case visibility by type, role, customer, geography/location, and sensitivity.
• Protect sensitive fields/documents independently from case access.
• Define who may transition, decide, approve, reopen, and export.

User Type menus establish eligible page routes for each audience. They do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

4. Add the core workflows

• Intake → validate required identity/data → triage.
• Stage transition → expected-state and required-check validation.
• Missing document → request and timer; receipt → review task.
• SLA threshold → escalation and ownership event.
• Recommendation → authorized decision/approval → immutable transition evidence.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

5. Connect channels and outside systems

• Accept forms, messages, documents, and authenticated API submissions.
• Use managed notifications and signature/identity connectors where required.
• Export only bounded authorized case data through reviewed APIs.

Use managed connections, OAuth connectors, inbound endpoints, and webhooks. Put specialized SDKs or private processing behind a declared appliance endpoint; never expose provider credentials to a page.

6. Add AI as a governed layer

Use AI to summarize long histories, identify missing information, and prepare next actions. It must cite permitted case evidence and cannot make regulated or material decisions unless an explicit policy and authorized action allow it.

• Assemble context from the case and accessible related records.
• Distinguish facts, missing data, and recommendations.
• Bind suggestions to the case/activity version so changed evidence makes them stale.
• Capture reviewer corrections as evaluation evidence.

AI and retrieval must apply CanAiReadRecords, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

7. Ship one complete vertical slice

Recommended first release: Submit one case type, route it to triage, request and receive one document, complete a review checklist, and record one authorized decision.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

8. Validate, package, and operate

• Test invalid and out-of-order stage transitions.
• Test SLA clocks, pause rules, and escalation fixtures.
• Prove sensitive evidence is absent for restricted reviewers.
• Replay the case timeline into the same explainable final state.

Publish a reviewed exact version as a template when the pattern is reusable. If you sell it, complete the marketplace preparation checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

Built-in data path: React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.