Labs

What it is

Laboratory tests and analyses management system with reference ranges, result evaluation, and AI-powered interpretation.

Who it's for

Workspace Owner Staff

Access & Scope

Property	Value
Module	labs
Personas	workspace-owner, staff
Scope	Workspace-level
UI Location	Dashboard > Labs

| Status | active |

UI Location

Dashboard > Labs

Labs Manager Interface

The Labs Manager provides a comprehensive interface organized into main tabs and configuration sub-tabs:

Main Tabs

1. Operations: Day-to-day lab operations and test management (coming soon)
2. Reports & Analytics: Lab reports and analytics dashboard (coming soon)
3. Configurations: All lab configuration and setup options

Configuration Tabs

The Configurations tab includes the following sub-tabs for managing lab resources:

1. Lab Units: Manage measurement units for test results
2. Test Units: Define test unit types
3. Test Samples: Manage sample types (e.g., blood, urine, tissue)
4. Test Profiles: Organize tests into profiles
5. Tests: Manage individual lab tests
6. Test Groups: Organize multiple tests into groups
7. Organisms: Manage organisms for culture tests
8. Lab Coupons: Create and manage discount coupons for lab services
9. SMS/WhatsApp Templates: Configure notification templates for lab results

Responsive Tabs Design

The Labs Manager uses a responsive tabs component that:

• Automatically hides tabs that don't fit in the available space
• Shows a "More" dropdown menu for hidden tabs
• Maintains active tab state in the URL for bookmarking and sharing
• Supports both main tabs and sub-tabs with different visual styles

How it works

The Labs module provides comprehensive laboratory test management with the following components:

1. Lab Units: Define measurement units for test results (e.g., mg/dL, mmol/L, units/L)

   • Create, edit, and delete lab units
   • Seed lab units from external sources
   • Workspace-scoped units

2. Test Units: Define test unit types for categorization

   • Create, edit, and delete test units
   • Seed test units from external sources

3. Test Samples: Manage sample types used in lab tests

   • Create, edit, and delete test samples (e.g., blood, urine, tissue)
   • Seed test samples from external sources

4. Test Profiles: Organize tests into profiles for easier management

   • Create, edit, and delete test profiles
   • Seed test profiles from external sources

5. Test Groups: Organize multiple tests into groups for easier management:

   • Group title and default price
   • Associate multiple tests with a group
   • Seeding from external sources
   • Select tests from source JSON files
   • Manage selected tests per group

6. Analyses: Create and manage laboratory analyses with:

   • Test name, report name, bill name, and history name
   • Price per analysis
   • Sample type
   • Associated unit
   • Reference ranges based on age, gender, and priority

7. Reference Ranges: Define normal ranges for each analysis with:

   • Age range (from/to with unit: days, weeks, months, years)
   • Gender filter (male, female, both)
   • Low and high limits with flags (L/H)
   • Priority for range matching
   • Conditional result notes (notes shown when result matches specific conditions)
   • Reference notes and comments

8. Organisms: Manage organisms for culture tests

   • Create, edit, and delete organisms
   • Associate organisms with culture test values
   • Seed organisms from external sources

9. Lab Coupons: Create and manage discount coupons for lab services

   • Create coupons with percentage or fixed currency discounts
   • Set coupon codes and status (active/inactive)
   • Manage coupon values and types

10. Tests: Create lab tests for clients with:

    • Client selection
    • Test date
    • Multiple analyses per test
    • Test status tracking (pending, in-progress, completed, billed, posted)
    • Supervisor assignment
    • Custom fields support

11. Test Items: Each test contains multiple items (analyses) with:

    • Result values (numeric or text)
    • Automatic range matching based on client age and gender
    • Flag computation (normal, low, high)
    • Conditional result notes display
    • AI-powered interpretation
    • Price and unit snapshots

12. Section Values Management: Manage values within test design sections

    • Create and edit section values with different types (text, number, choices, culture, text editor)
    • Configure value properties: name, type, unit, default values
    • For number types: support equations and formula-based calculations
    • For choices types: define multiple choice options
    • For culture types: configure display layout (horizontal/vertical) and associate organisms
    • Manage normalizations per value with age ranges, gender filters, and reference values
    • Reorder values within sections

13. Result Evaluation:

• Automatic matching of reference ranges based on client age and gender
• Flag computation (normal, low, high) based on matched range
• Conditional notes display when result matches specific conditions
• AI interpretation of results using OpenAI with language selection (Arabic/English)
• Two-step interpretation process: estimate cost first, then generate interpretation
• Automatic text direction (RTL/LTR) based on selected language

12. Invoicing & Income:

• Generate invoices from completed tests
• Post test invoices to income records
• Track billing status

Settings

The Labs feature includes the following configurable settings:

1. Lab Units Management:

   • Create custom measurement units
   • Edit and delete lab units
   • Seed lab units from external sources
   • Units are workspace-scoped

2. Test Units Management:

   • Create, edit, and delete test units
   • Seed test units from external sources
   • Organize tests by unit type

3. Test Samples Management:

   • Create, edit, and delete test samples
   • Seed test samples from external sources
   • Define sample types (e.g., blood, urine, tissue)

4. Test Profiles Management:

   • Create, edit, and delete test profiles
   • Seed test profiles from external sources
   • Organize tests into profiles

5. Test Groups Management:

   • Create test groups with title and default price
   • Seed test groups from external API sources
   • Manage selected tests per group
   • Load default test selections from source JSON files
   • Add or remove tests from groups

6. Organisms Management:

   • Create, edit, and delete organisms
   • Seed organisms from external sources
   • Associate organisms with culture test values

7. Lab Coupons Management:

   • Create coupons with title, code, type (percentage/currency), and value
   • Set coupon status (active/inactive)
   • Edit and delete coupons

8. Section Values Configuration:

   • Configure value types: text, number, choices, culture, text editor
   • Set value properties: name, unit, default values
   • For number types: enable equations and define formulas
   • For choices types: define multiple choice options
   • For culture types: configure display layout and associate organisms
   • Manage normalizations with age ranges, gender filters, and reference values
   • Reorder values within sections

9. Analysis Configuration:

   • Define test names and display names (report, bill, history)
   • Set pricing per analysis
   • Associate with measurement units
   • Define sample types
   • Add website notes

10. Reference Range Configuration:

• Age-based ranges with flexible units
• Gender-specific or universal ranges
• Priority-based matching (higher priority ranges matched first)
• Low and high limits with custom flags
• Conditional result notes with operators (>=, <=, =, >, <)
• Support for both numeric and string result values

11. Test Status Management:

• Pending: Test created but not started
• In Progress: Test is being processed
• Completed: All results entered, ready for billing
• Billed: Invoice generated
• Posted: Posted to income records

Permissions

Access to the Labs feature is controlled by role-based permissions:

• labs.view: Required to view labs module, analyses, tests, and test details
• labs.manage: Required to create, edit, and delete analyses, ranges, units, and tests
• labs.run: Required to enter test results and mark tests as completed
• labs.billing: Required to generate invoices and post to income

Default Access:

• Workspace Owner: Has all permissions by default
• Staff: Permissions are granted based on their assigned roles. Staff without labs.view permission will not see the Labs section in the menu.

Use Cases

1. Medical Laboratory Management:

   • Manage laboratory tests and analyses
   • Define reference ranges for different age groups and genders
   • Track test results and generate reports
   • Provide AI-powered interpretation of results

2. Test Result Tracking:

   • Create tests for clients
   • Enter and track test results
   • Automatically match results to appropriate reference ranges
   • Display conditional notes based on result values

3. Billing Integration:

   • Generate invoices from completed tests
   • Post test invoices to income records
   • Track billing status per test

4. Reference Range Management:

   • Define multiple reference ranges per analysis
   • Age and gender-specific ranges
   • Priority-based matching for overlapping ranges
   • Conditional notes for specific result values

5. AI Interpretation:

   • Get AI-powered interpretation of test results
   • Interpret individual test items
   • Choose output language (Arabic or English)
   • Two-step process: estimate cost before generating interpretation
   • Automatic text direction adjustment (RTL for Arabic, LTR for English)
   • View interpretation history and cached interpretations
   • Cost tracking and balance management

Notes / Limits

1. Module Activation:

   • Labs module must be enabled for the workspace via workspace menu overrides
   • Module availability depends on workspace subscription

2. Reference Range Matching:

   • Ranges are matched based on client age (converted to appropriate unit) and gender
   • Higher priority ranges are matched first
   • If no matching range is found, flag computation may be unavailable

3. Result Notes:

   • Conditional notes are evaluated when results are entered
   • Notes with string values can only use "=" (equals) condition
   • Notes with numeric values support all operators (>=, <=, =, >, <)
   • Multiple notes can match for a single result

4. Test Status Flow:

   • Tests start as "pending"
   • Can be marked as "in-progress" when work begins
   • Must be "completed" before invoicing
   • Invoice generation creates "billed" status
   • Posting to income creates "posted" status

5. Data Validation:

   • Analysis names are required
   • Prices must be non-negative
   • Age ranges must be valid (ageFrom <= ageTo)
   • Reference ranges require valid gender, age, and limit values

6. AI Interpretation:

   • Requires OpenAI API configuration
   • Interpretation is generated per test item
   • Results are cached and can be regenerated
   • Language selection: Choose output language (Arabic or English) for interpretations
   • Cost estimation: Check estimated cost and current balance before generating interpretation
   • Improved accuracy: Cost estimation uses realistic token counts (400 tokens) for better accuracy

Changelog

Recent Updates

Labs Manager Interface:

• Added comprehensive Labs Manager with tabbed interface
• Main tabs: Operations, Reports & Analytics, Configurations
• Responsive tabs component with "More" dropdown for hidden tabs
• URL-based tab state management for bookmarking and sharing
• Support for main tabs and sub-tabs with different visual styles

Configuration Management:

• Added Lab Units management (create, edit, delete, seed)
• Added Test Units management (create, edit, delete, seed)
• Added Test Samples management (create, edit, delete, seed)
• Added Test Profiles management (create, edit, delete, seed)
• Added Organisms management (create, edit, delete, seed)
• Added Lab Coupons management (create, edit, delete with percentage/currency types)
• Added SMS/WhatsApp Templates configuration tab

Section Values Management:

• Added section value card and form components
• Support for multiple value types: text, number, choices, culture, text editor
• Equation support for number types
• Choices management with add/remove functionality
• Culture type with display layout configuration and organism association
• Normalization management with age ranges, gender filters, and reference values
• Value reordering within sections

Test Groups Feature:

• Added test groups management for organizing multiple tests
• Test groups seeding from external API sources
• Test group detail page with test selection interface
• Select tests from source JSON files functionality
• Manage selected tests per group (add/remove)
• Default price configuration per test group

AI Interpretation Enhancements:

• Added language selection for interpretations (Arabic/English)
• Added cost estimation endpoint to check costs before generating interpretation
• Improved cost estimation accuracy (400 tokens instead of 1000)
• Automatic text direction adjustment based on selected language
• Enhanced user experience with language selector in interpretation modal

Fri Jan 03 2025

• Initial Labs module implementation
• Test units management
• Analyses and reference ranges
• Test creation and result tracking
• AI-powered result interpretation
• Invoicing and income integration
• Conditional result notes support