Prebill

Creates a billing case, resolves charge items, builds a draft claim, and runs validation rules. Typically triggered when an encounter reaches finished status. Idempotent — safe to re-run (deletes old planned/draft resources before creating new ones).

Input

Activity tree

Blue = built-in activities. Grey = project-specific activities.

Activities

1. snapshot-billing-case (built-in)

Finds or creates a BillingCase for the encounter. On first run, snapshots all clinical resources (Patient, Encounter, Procedures, Coverages, Practitioners, Organizations) as contained resources. Idempotent — returns the existing BillingCase if one already exists.

Output: billingCaseId, created

2. fetch-context (built-in)

Loads the full BillingCaseContext from the BillingCase: patient, encounter, procedures, practitioners, coverages, organizations, conditions, and any previously created claims/charge items.

Output: BillingCaseContext object

3. select-coverage (project-specific)

Picks the coverage to bill against. The selection strategy is client-specific — typically prefers the coverage with order: 1 and status: active. Accepts an optional coverageId override for resubmissions.

Output: coverage, selectionReason, hasCoverage, noCoverage

4a. resolve-charge-items (project-specific, conditional)

Runs only when select-coverage.hasCoverage is truthy.

Fetches ChargeItemDefinition resources, evaluates applicability, and creates planned ChargeItem resources for each matched (procedure, definition) pair. Handles deletion of stale charge items from previous runs.

Output: chargeItems, chargeItemDefinitions, bundle, hasChargeItems, noChargeItems

4b. save-no-coverage (project-specific, conditional)

Runs only when select-coverage.noCoverage is truthy.

Persists the BillingCase with a no-coverage status. Terminates this branch.

5a. build-draft-claim (built-in, conditional)

Runs only when resolve-charge-items.hasChargeItems is truthy.

Assembles a FHIR Claim in draft status from charge items, ChargeItemDefinition pricing, and the BillingCaseContext. Generates a Patient Control Number (PCN) identifier. Embeds clinical context as contained resources.

Output: context (augmented with chargeItems), claim, bundle

5b. save-no-charges (project-specific, conditional)

Runs only when resolve-charge-items.noChargeItems is truthy.

Persists the BillingCase with a no-charges status. Terminates this branch.

6. evaluate-rules (built-in)

Reads validation-rules/manifest.yaml, runs each rule against the BillingCaseContext, and returns BillingTask resources for failed rules. Does not persist anything — tasks are saved downstream.

Output: taskBundle, passed, summary, assignedDashboard, assignedWorklist

7. assert-no-errors (project-specific)

Checks whether evaluate-rules.passed is true. If errors were found, records the error summary on the BillingCase but does not fail the workflow — claim submission will be blocked until errors are resolved via the billing worklist.

Output: blocked, summary

8. save (project-specific)

Persists all resources to Aidbox in a single FHIR transaction: charge items, draft claim, BillingCase update, and BillingTask records. Updates the BillingCase status.

Output: billingCaseId, claimId, chargeItemsCount, status

Outcomes

On successful completion (with coverage and charge items):

• A BillingCase resource linked to the encounter exists in Aidbox.
• ChargeItem resources for each matched procedure.
• A Claim in draft status with a PCN, ready for the Claim Submission workflow.
• BillingTask resources for any validation warnings or errors.

Common issues

See also