> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/appertafoundation/openeyes/llms.txt > Use this file to discover all available pages before exploring further. # Clinical Workflow > Understanding episodes, events, and the clinical workflow in OpenEyes ## Overview OpenEyes uses an **episode-based, event-driven** clinical workflow model. This architecture provides structured clinical documentation while maintaining flexibility for various ophthalmic specialties. The episode-event model is central to OpenEyes. Understanding this structure is essential for effective clinical documentation. ## Episode-Based Architecture ### What is an Episode? An **episode** represents a continuous period of care for a specific condition in a particular subspecialty. * Patient * Subspecialty (e.g., glaucoma, cataract) * Firm (clinical team) * Principal diagnosis * Affected eye(s) * Status (active, discharged) * Created at first contact * Remains open during active care * Can be closed and reopened * Tracks start and end dates ### Episode Types OpenEyes supports different episode categories: Regular clinical episodes for subspecialty care: * Glaucoma * Cataract * Medical Retina * Oculoplastics * Each tied to a specific subspecialty and firm Non-clinical support services: * Orthoptics * Low vision * Contact lens services * Separate from subspecialty episodes Historical episodes: * Imported from old systems * Read-only data * Maintained for continuity ### Creating Episodes Navigate to patient record from search or worklist System displays all episodes for the patient * Active episodes shown in green * Closed episodes shown in gray If no episode exists for current subspecialty: 1. Click **Add New Episode** 2. System associates with selected firm 3. Subspecialty determined by firm 1. Select disorder from SNOMED-coded list 2. Choose affected eye: Right, Left, or Both 3. Optionally set diagnosis date 4. Diagnosis becomes episode identifier You must have **OprnCreateEpisode** permission to create new episodes. Contact your administrator if this action is unavailable. ### Episode Management **Viewing Episodes:** * Patient summary shows all episodes * Click episode to view details * See all events within episode * Review episode timeline **Editing Episodes:** 1. Navigate to episode view 2. Click **Edit** tab (if permitted) 3. Update principal diagnosis 4. Change episode status 5. Save changes **Episode Status:** * **Active**: Ongoing clinical care * **Closed**: Episode completed * Episode end date set when closed ## Event-Driven Documentation ### What is an Event? An **event** is a specific clinical encounter or documentation instance within an episode. * Event type (examination, operation, etc.) * Event date * Associated episode * Creating user and firm * Custom elements per event type * Examination * Prescription * Operation booking * Biometry * Correspondence * Custom module events ### Event Lifecycle ```mermaid theme={null} graph LR A[Create Event] --> B[Add Elements] B --> C[Save Draft] C --> D[Complete & Save] D --> E[Event Locked] E --> F[View/Print] F --> G{Need Changes?} G -->|Yes| H[Delete & Recreate] G -->|No| F ``` Once saved, events are generally locked for audit purposes. If changes are needed, the event may need to be deleted (soft delete) and recreated. ### Creating Events Find patient record via search or worklist Ensure appropriate episode exists for event 1. Click **Add Event** button 2. Select event type from dropdown 3. System creates event in current episode Each event type has specific elements: * Examination: VA, IOP, anterior segment, etc. * Prescription: Medications, dosage, instructions * Operation: Procedure, laterality, booking details * **Save Draft**: Work in progress (can edit later) * **Save & Exit**: Complete event (locked) * Event appears in patient timeline ### Event Elements Each event type contains multiple elements: * **History**: Presenting complaint, history of presenting complaint * **Visual Acuity**: Aided/unaided, right/left/both eyes * **Refraction**: Sphere, cylinder, axis for each eye * **Intraocular Pressure**: IOP readings and method * **Anterior Segment**: Slit lamp findings with EyeDraw * **Posterior Segment**: Fundus findings with EyeDraw * **Diagnoses**: Update or confirm diagnoses * **Management**: Clinical plan and follow-up * **Conclusions**: Summary and next steps * **Drug Selection**: Search formulary * **Dose & Frequency**: Standard or custom * **Route**: Topical, oral, injection * **Laterality**: Right eye, left eye, both, or systemic * **Duration**: Treatment period * **Instructions**: Patient directions * **Prescriber Details**: Regulatory information * **Procedure**: SNOMED-coded operation * **Laterality**: Eye to be operated * **Surgeon**: Operating consultant * **Anaesthetic**: Local, general, or sedation * **Priority**: Routine, urgent, emergency * **Booking Details**: Date, time, location * **Consent**: Documentation reference ### Event Drafts Drafts allow work-in-progress: * **Save Draft**: Preserves partial work * **Resume Draft**: Continue from where you left off * **Draft List**: View all pending drafts * **Auto-save**: Periodic saving (if enabled) * **Draft Age**: System tracks how long drafts are pending Drafts are not part of the clinical record until finalized. Complete drafts promptly to maintain accurate patient timelines. ## Clinical Pathways Integration Events can be linked to clinical pathways: ### Pathway Steps Events can fulfill pathway steps: * Check-in * Pre-assessment * Examination * Procedure * Follow-up ### Worklist Integration Events created from worklists: * Automatically link to worklist patient * Update pathway status * Track wait times * Measure clinic efficiency See the [Worklists guide](/user-guide/worklists) for detailed information on pathway-based workflows. ## Event Validation ### Date Validation Event dates must: * Not be in the future (unless allowed by configuration) * Be logical in sequence (generally after episode start) * Be after patient date of birth * Be before date of death (if deceased) ### Required Elements Each event type has mandatory elements: * Cannot save without completing required fields * System highlights missing elements * Validation messages guide completion ### Business Rules Events follow clinical rules: * Prescription requires valid prescriber * Operation must have laterality specified * Examination requires at least one finding * Correspondence must have recipient ## Event Hierarchy and Relationships ### Parent-Child Events Events can have hierarchical relationships: * **Parent Event**: Original event (e.g., operation booking) * **Child Events**: Follow-up events (e.g., post-op review) * Navigation between related events * Maintains clinical context ### Event Groups Events can be grouped: * Same-day events * Related procedures * Linked correspondence * Grouped viewing and printing ## Viewing Events ### Timeline View Patient summary displays events chronologically: * Most recent events first * Color-coded by event type * Quick view of event date and type * Click to open full event ### Episode View View events within an episode: * Filtered by episode * Shows progression of care * Track diagnosis changes * Review management over time ### Lightning Viewer Quick access to document events: * Grouped by type (letters, reports, etc.) * Organized by year * Side-by-side comparison * Print-friendly view Lightning Viewer is useful for quickly reviewing correspondence, biometry reports, and other documents without navigating through full events. ## Event Deletion and Modification ### Soft Delete Events can be soft-deleted: 1. Open event view 2. Click **Delete** (if permitted) 3. Enter deletion reason 4. Event marked as deleted (not removed) 5. Audit trail maintained **Event deletion requires appropriate permissions:** * Should only be used for errors or duplicates * Deleted events remain in audit log * Cannot be restored without database access * Consider creating corrective event instead ### Audit Trail All event actions are logged: * Creation timestamp and user * Modifications (if allowed) * Views and prints * Deletion with reason * Complete audit trail for governance ## Multi-Specialty Workflow ### Multiple Episodes Patients can have concurrent episodes: * Different subspecialties * Different clinical teams * Independent management plans * Shared patient context ### Episode Switching Switch between episodes: 1. View patient summary 2. See all active episodes 3. Click episode to set context 4. New events added to selected episode ### Cross-Episode View Some views show all episodes: * Complete patient timeline * All visual acuity measurements * All prescriptions * Comprehensive clinical picture ## Firm-Based Workflow ### Firm Context Clinical work is firm-specific: * Select firm at session start * Events created under selected firm * Episodes associated with firm * Worklists filtered by firm ### Multi-Firm Access Clinicians can belong to multiple firms: * Switch firms in header * View changes to show current firm's patients * Maintain separate worklists per firm * Cross-firm patient access maintained ## Advanced Workflows ### Automated Events Some events can be automated: * Imported from devices (biometry, OCT) * Auto-generated from pathways * Scheduled follow-ups * System-triggered notifications **Automated Source Tracking:** * Events marked with `is_automated` flag * Source system recorded in JSON * Different validation rules * Audit trail includes automation details ### Template-Based Events Use templates for efficiency: * Pre-populate common findings * Standard letters * Routine examinations * Custom templates per firm/user ### Event Attachments Attach files to events: * Imaging results * External reports * Correspondence received * Supporting documents Attachments are grouped by event for easy access. Supported formats include PDF, images, and medical imaging standards. ## Best Practices Create separate episodes for each subspecialty to maintain clear clinical focus Finalize event documentation during or immediately after the clinical encounter Ensure event date reflects actual clinical encounter, not documentation date Set principal diagnosis that best represents the episode's clinical focus ## Troubleshooting **Possible causes:** * No firm selected * Insufficient permissions (need OprnCreateEpisode) * Patient record issues **Solutions:** * Select firm from header dropdown * Contact administrator for permission review * Verify patient record is valid and not deleted **Common issues:** * Missing required elements * Invalid date (future date not allowed) * Validation errors in element data **Solutions:** * Review red error messages * Complete all required fields (marked with \*) * Check date is not in future * Verify eye-specific data is logical **Possible reasons:** * Wrong episode selected * Insufficient view permissions * Events exist but are drafts * Deleted events (need special view) **Check:** * Verify correct episode is active * Review user permissions with admin * Look in drafts section * Check if OprnViewClinical permission granted **To update:** * Navigate to episode view * Click Edit tab (need OprnEditEpisode permission) * Update principal diagnosis * Select correct affected eye * Optionally update diagnosis date * Save changes Note: Diagnosis changes are audited ## Next Steps Explore specific event types and clinical modules Learn detailed examination documentation Master prescription creation and management Understand operation booking and management