Data Model & Schema

DB Schema Diagram: Lab Forms DB Schema

Process

Table: Process File: admin/account/models/coc/process.py

The root configuration entity. A Process defines a top-level form section scoped to a lab and form type.

Index: (lab, form_type) — primary lookup path for fetching all processes for a lab's form type.

Process Types Behaviour

SubProcess

Table: SubProcess File: admin/account/models/coc/subprocess.py

A section/group within a Process. Contains ordered questions.

Validation Rules:

• is_mandatory and is_hidden cannot both be true.
• for_communication=True is only valid for consent form type.
• Duplicate subprocess names within the same lab + form type are rejected.

LinkedSubProcess

Table: LinkedSubProcess File: admin/account/models/coc/linked_subprocess.py

Through-table between Process and SubProcess, with ordering.

Ordering: (subprocess_id, sequence)

Question

Table: Question File: admin/account/models/coc/question.py

An individual form field belonging to a SubProcess.

Ordering: sequence ASC

Supported Field Types

Reserved Communication Question Codes (Consent Only)

These codes are reserved for communication-preference subprocesses:

• sms_communication
• fax_communication
• communication_mode
• email_communication
• enable_communication
• address_communication
• whatsApp_communication

Questions in a for_communication=True subprocess must use one of these codes. Questions outside such subprocesses cannot use them.

QuestionAttribute

Table: QuestionAttribute File: admin/account/models/coc/question_attribute.py

Key-value metadata attached to a Question that controls rendering and validation behaviour.

Attribute Categories

Skip Logic

When allow_skipping=True, the question must have skip_to_conditions in its attributes. This is a dict keyed by answer value (or "default") mapping to:

{
  "<value>": {
    "skip_to_type": "Process | SubProcess | End Process | Abort Process | End Process & Resume | End Process & Restart",
    "skip_to": "<id>",
    "values_operation": "reset | iterate"
  }
}

• Process — skip to another process
• SubProcess — skip to another subprocess
• End Process — end current process, move to close-down if available
• Abort Process — abort and move to next instance
• End Process & Resume — end and resume previous process retaining old values
• End Process & Restart — end and restart previous process

Prefilling

When allow_prefilling=True, the question supports auto-population from external data sources:

Configuration:

{
  "prefilling_source": "Bill",
  "prefilling_options": {
    "source_field": "labBillId",
    "default_value": "",
    "requires_value_transformation": false
  }
}

ProcessLinkedInstances

Table: ProcessLinkedInstances File: admin/account/models/coc/process_linked_instances.py

Links a Process to specific entity instances (tests, profiles, promotions, store).

Unique constraint: (lab, process, instance_id)

Validation Rules:

• Only allowed for aoe, consent form types.
• Instance IDs are validated against the corresponding model (via PROCESS_TYPE_MODEL_META_MAPPER).

LabForm

Table: LabForm File: admin/account/models/coc/lab_form.py

A runtime form instance tied to a specific patient + bill. Currently used primarily for consent forms but structured to support all form types.

Lifecycle:

1. Created via LabForm.create_consent() — identifies applicable processes, creates form, links processes, generates QR code, sends email.
2. Processes linked/unlinked via link_process() / unlink_process().
3. Revoked via revoke_consent() — marks all linked processes as revoked, revokes patient communication consent.

LabFormLinkedProcesses

Table: LabFormLinkedProcesses File: admin/account/models/coc/lab_form_linked_processes.py

Through-table linking LabForm to Process with status tracking.

QuestionValue

Table: QuestionValue File: admin/account/models/coc/question_value.py

Captured answer for a single question.

Ordering: (subprocess_sequence, question_sequence, iteration)

Index: created_at (used for MIS time-range queries)

Value Levels

Question values are organized into levels based on process type:

PatientConsent

Table: PatientConsent File: admin/account/models/coc/patient_consent.py

Stores per-patient communication preference flags, derived from consent form answers.

Communication flags are auto-updated when consent QuestionValues are saved (via PatientConsent.prepare_and_save_communication()).

AdditionalPatientInfo

Table: AdditionalPatientInfo File: patient/models/additional_patient_info.py

Stores captured patient answers for additional_patient_info forms. Unlike QuestionValue (which is bill-scoped), this is patient-scoped — answers are tied to a patient, not a billing record. This is the key architectural difference: patient demographic/clinical info persists across bills.

Key difference from QuestionValue: There is no bill_id or report_id — data is stored at the patient level, not the bill level.

Key Operations:

AdditionalPatientInfoSettings

Table: AdditionalPatientInfoSettings File: admin/account/models/additional_patient_info_settings.py

Configuration model that controls which additional_patient_info form processes are shown on which UI pages.

DB constraints:

1. unique_lab_page_process — unique combination of (lab, page, custom_page, process)
2. unique_default_settings — only one is_default=True per (lab, page, custom_page)

Key Operations:

Additional Patient Info — Entity-Relationship Summary

Labs ──┐
       ├── Process (form_type="additional_patient_info")
       │     ├── LinkedSubProcess (max 1 for this form type)
       │     │     └── SubProcess
       │     │           └── Question (field_type, sequence)
       │     │                 └── QuestionAttribute (options, validators, etc.)
       │     └── ProcessLinkedInstances (tests linked to the form)
       │
       ├── AdditionalPatientInfoSettings (page config)
       │     ├── page (appointment | registration | home_collection | cc_registration)
       │     ├── process → Process
       │     └── custom_page → CustomPage (optional)
       │
       └── UserDetails (patient)
             └── AdditionalPatientInfo (captured values)
                   ├── process → Process
                   ├── question → Question
                   └── edited_by → LabUser

PromotionLinkedProcesses

Table: PromotionLinkedProcesses File: crm/promotion/models/promotion_linked_processes.py

Links Processes to CRM Promotions with ordering. This is a CRM-side through-table that complements ProcessLinkedInstances — while ProcessLinkedInstances tracks the form-config-level link (which instances a process applies to), PromotionLinkedProcesses tracks the promotion-side relationship (which processes are shown when a promotion is selected), along with display sequencing.

Unique constraint: (lab, process, promotion)

DB constraints:

• UniqueConstraint(promotion, sequence) — no two processes share the same sequence within a promotion.
• CheckConstraint(sequence >= 1) — sequence must be positive.

Index: (lab, promotion) — fast lookup of all processes for a given lab + promotion.

Key Operations:

Interaction with ProcessLinkedInstances: When create_process_linked_instances=True (default), linking a Promotion-type process also creates ProcessLinkedInstances records so the form config layer can resolve which processes apply to a given promotion. Deletion mirrors this — removing the CRM-side link also cleans up form-config-side links and invalidates Redis cache.

StoreLinkedProcesses

Table: StoreLinkedProcesses File: crm/store/models/store_linked_processes.py

Links Processes to CRM Stores with ordering. Analogous to PromotionLinkedProcesses but for the Store entity — tracks which form processes are presented when a store is selected.

Unique constraint: (lab, process, store)

DB constraints:

• UniqueConstraint(store, sequence) — no two processes share the same sequence within a store.
• CheckConstraint(sequence >= 1) — sequence must be positive.

Index: (lab, store) — fast lookup of all processes for a given lab + store.

Key Operations:

Scoped Process Types: Only processes with process_type in store_supported_process_types (Bill, Store) can be linked to a store. This is validated during link_processes_to_store.