Product User Guide

Documentation and help for Medaius Clinic System

Custom Forms Domain - Workflow Narrative

A conversational guide to understanding dynamic form workflows

What is the Custom Forms Domain?

Every medical specialty has different documentation needs. An orthopedic surgeon needs to capture different data than a psychiatrist. A dermatologist documents differently than a cardiologist.

The Custom Forms domain provides a flexible solution - dynamic form templates that organizations can create, customize, and use to capture specialty-specific data. Instead of changing code for each specialty, you configure forms.

The Core Concepts

Form Templates

A form template is the definition - what fields exist, what types they are, what validations apply, how they should be displayed. Templates are reusable blueprints.

Form Responses

A response is a filled-out instance of a form. When a clinician completes a form for a patient, that creates a response linked to the template.

Resource Mapping

Here's where it gets powerful. Form fields can map to clinical resources. A "Blood Pressure" field might map to an Observation. A "Diagnosis" field might map to a Condition. When the form is finalized, these mappings create actual clinical records.

Form Template Structure

Field Definitions

The form template's form_config JSON defines fields:

{
  "fields": [
    {
      "id": "blood_pressure",
      "type": "observation",
      "label": "Blood Pressure",
      "required": true,
      "observation_type": "vital-signs",
      "observation_code": "85354-9"
    },
    {
      "id": "chief_complaint",
      "type": "text",
      "label": "Chief Complaint",
      "maxLength": 500
    },
    {
      "id": "diagnosis",
      "type": "condition",
      "label": "Primary Diagnosis",
      "icd10_searchable": true
    }
  ]
}

Field Types

Forms support various field types:

  • text - Free text input
  • number - Numeric values
  • select - Dropdown choices
  • checkbox - Boolean or multiple choice
  • date - Date picker
  • observation - Maps to Observation resource
  • condition - Maps to MedicalCondition
  • medication - Maps to Medication

Validation Rules

Each field can have validation:

  • required: true - Must be filled
  • minLength/maxLength - Text length constraints
  • min/max - Numeric range constraints
  • pattern - Regex validation

Creating Form Templates

Who Creates Forms

Typically, organization administrators or clinical informatics staff create form templates. This requires the medical_record.write permission.

The Creation Flow

When creating a form via POST /custom-forms:

  1. Validate the template structure
  2. Ensure field IDs are unique
  3. Validate resource mappings are valid types
  4. Create the CustomForm record
  5. Set initial version to 1
  6. Default status to "draft"

Form Lifecycle

  • draft - Being developed, not usable for responses
  • active - Live and can be used
  • archived - No longer in use, but existing responses remain

Versioning

When a form template is updated, the version increments. This tracks changes over time. Responses retain which version they were created with.

Using Forms (Responses)

Starting a Response

When a clinician opens a form to fill out:

  1. Select the form template
  2. Associate with a patient
  3. Optionally link to an encounter
  4. Create a new CustomFormResponse in "draft" status

The Response Object

{
  "id": "cfr_abc123",
  "form_id": "cf_cardiac_assessment",
  "patient_id": "pat_xyz",
  "encounter_id": "enc_456",
  "status": "draft",
  "response_data": {
    "blood_pressure": "120/80",
    "chief_complaint": "Chest pain, intermittent",
    "diagnosis": {
      "code": "I20.9",
      "display": "Angina pectoris, unspecified"
    }
  }
}

Status Progression

  • draft - Still being filled out
  • submitted - Completed and awaiting review
  • final - Locked and finalized
  • amended - Corrections made after finalization

Saving Progress

Draft responses can be updated at any time. The practitioner can partially fill out a form, save, and return later to complete it.

Finalizing Responses

The Finalization Trigger

When a response is finalized via POST /custom-forms/{form_id}/responses/{response_id}/finalize:

  1. Validate all required fields are filled
  2. Lock the response (status → "final")
  3. Create clinical resources from mapped fields
  4. Record finalized_by user and timestamp

Resource Mapping in Action

This is the magic. When a form with mapped fields is finalized, real clinical data is created:

  • Blood Pressure field → Creates an Observation record
  • Diagnosis field → Creates a MedicalCondition record
  • Medication field → Creates a Medication record

These resources are linked to the patient and encounter, just like manually-created clinical data.

Example Flow

  1. Cardiologist fills out "Cardiac Assessment" form
  2. Enters BP: 140/90, Diagnosis: I10 (Essential Hypertension)
  3. Clicks "Finalize"
  4. System creates:
    • Observation: BP 140/90, code 85354-9
    • MedicalCondition: I10, status active
  5. These appear in the patient's clinical record

Form Categories and Specialties

Organization by Specialty

Forms can be tagged with specialties:

  • Cardiology forms
  • Orthopedic forms
  • Psychiatry forms
  • Primary care forms

This helps clinicians find relevant forms quickly.

Built-in vs Organization-Specific

Some forms come pre-built:

  • General intake forms
  • Review of systems templates
  • Vital signs recording forms

Organizations can also create their own custom forms tailored to their specific workflows.

Global vs Local

  • Global forms - Available to all organizations (built-in templates)
  • Organization forms - Specific to one organization

Global forms can be cloned and customized by organizations that want modifications.

Querying Forms and Responses

Listing Forms

list_forms() returns available templates. Filters include:

  • specialty - Show cardiology forms
  • form_type - Show assessment forms
  • status - Show only active forms

Listing Responses

list_form_responses() returns filled responses. Filters include:

  • patient_id - Show this patient's forms
  • encounter_id - Forms from this encounter
  • status - Show only finalized responses
  • form_id - Responses to a specific template

Cross-Form Queries

list_all_responses() can find responses across all forms - useful for dashboards showing recent form activity.

Updating and Amending

Draft Updates

Draft responses can be freely updated. Add data, change values, no restrictions.

Submitted Updates

Submitted responses can still be edited, but this might require re-submission for review.

Final Response Amendments

Finalized responses are locked. But clinical reality sometimes requires corrections. The amendment process:

  1. Mark the response as "amended"
  2. Record what changed and why
  3. The original data is preserved for audit

Deletion Restrictions

Only draft responses can be deleted. Submitted and finalized responses must remain for audit purposes.

Integration with Clinical Data

To Observations

Form fields with type: "observation" map to the Observation model. The mapping specifies:

  • observation_code - LOINC or local code
  • observation_type - Category (vital-signs, laboratory)
  • unit - Measurement unit

To Conditions

Fields with type: "condition" map to MedicalCondition. The mapping uses:

  • icd10_searchable - Enable ICD-10 code lookup
  • severity - Optional severity level

To Other Resources

Forms can also map to:

  • Medications (prescriptions)
  • Allergies (newly discovered)
  • Immunizations (vaccines administered)
  • ServiceRequests (orders placed)

Use Cases

Specialty Assessments

A psychiatric practice creates a "Mental Status Exam" form with structured fields for appearance, mood, thought process, etc. Each field maps to appropriate observation types.

Pre-Visit Questionnaires

Patients complete forms before their visit. These capture symptoms, review of systems, and social history in a structured way.

Procedure Documentation

Surgical procedure documentation with fields for findings, complications, and specimens - all mapped to appropriate clinical resources.

Research Protocols

Clinical trials might require specific data collection. Custom forms ensure consistent capture across study participants.

Key Takeaways

  1. Dynamic structure - Forms are defined in JSON, not code

  2. Resource mapping - Form fields can create clinical data

  3. Status lifecycle - draft → submitted → final → amended

  4. Finalization trigger - Clinical resources created on finalize

  5. Specialty customization - Different forms for different needs

  6. Versioning - Templates track version history

  7. Audit preservation - Final responses are never deleted

Next: Read about the Announcements Domain to understand internal communication