Audience: Practice staff (clinicians, receptionists, practice managers)
Applies to: GP Booking App (test-client & all practices using TDL integration)
Last updated: 2026-07-28
This page describes the complete operational workflow for pathology (blood test) results at The Doctor's Laboratory (TDL), from the clinician deciding to order a test, through to the results being filed in the patient's record.
There are three staff roles involved:
| Role | Person | Typical tasks |
|---|---|---|
| Clinician | Doctor | Orders tests, reviews & files results |
| Receptionist | Debbie | Monitors incoming results, handles errors |
| Practice Manager | Admin | Configures TDL + IMAP mailbox settings |
┌─────────────────────────────────────────────────────────┐
│ PHASE 1: Clinician orders tests │
│ │
│ 1. See patient at appointment │
│ 2. Decide which blood tests are needed │
│ 3. Open patient record → click "+ Log Lab Order" │
│ 4. Select tests from picker (FBC, LFT, Vitamin D, etc.) │
│ 5. Click "Save & Open TDL Portal" │
│ 6. TDL eViewPlus opens in new tab │
│ 7. Complete the order in TDL portal (patient details, │
│ print barcode labels) │
│ 8. Sample taken → sent to TDL via courier │
│ │
│ Patient record now shows: 🟡 PENDING Lab Order card │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ PHASE 2: TDL processes sample & emails results │
│ │
│ 1. TDL receives sample, runs tests │
│ 2. Generates encrypted PDF report │
│ 3. Emails PDF to practice's IMAP mailbox │
│ (e.g. results-practice@lab.veripath.co.uk) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ PHASE 3: System automatically ingests the result │
│ │
│ 1. Celery task polls IMAP every 5 minutes │
│ 2. Downloads email + PDF attachment │
│ 3. Decrypts PDF using practice's TDL password │
│ 4. Saves email to inbox (PracticeEmailMessage) │
│ 5. Extracts text via pdfplumber │
│ 6. Parses patient name + DOB via regex │
│ 7. Matches patient using scoring algorithm: │
│ - Name match: 60pts │
│ - DOB match: +40pts │
│ - Score ≥ 90 & 20 ahead → auto-match │
│ - Otherwise → send to review │
│ 8. If matched → links LabOrder to document │
│ (status: 🟢 RECEIVED) │
│ 9. Extracts granular biomarker data │
│ (21 results parsed from a typical FBC+LFT panel) │
│ 10. Files to patient record │
│ (status: 🔵 FILED) │
│ │
│ Staff inbox updates automatically 🟡→🟢→🔵 │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ PHASE 4: Staff review (if needed) │
│ │
│ Receptionist at `/lab/mailbox/`: │
│ ┌──────────────────────────────────────────────────┐ │
│ │ From │ Subject │ Status │ Actions │ │
│ ├─────────┼────────────────┼─────────┼──────────────┤ │
│ │ TDL │ FBC - Brown │ 🔵 Filed │ [View] │ │
│ │ TDL │ LFT - Williams│ 🔍 Review│ [Verify] │ │
│ │ TDL │ HbA1c - Jones │ ❌ Error│ [Re-process] │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ If REVIEW → Clinician at `/lab/documents/<uuid>/verify/`:│
│ Split-screen: PDF (left) + editable grid (right) │
│ → Edit values if parser got them wrong │
│ → Click "Verify & File" │
│ → Audit-logged for CQC compliance │
│ │
│ If ERROR → Receptionist can: │
│ → Click "Re-process" to re-run the pipeline │
│ → Download raw PDF from the email detail │
│ → Upload manually at `/lab/upload/` if needed │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ PHASE 5: Results available on patient record │
│ │
│ Clinician at `/accounts/patients/<id>/`: │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Lab Orders │ │
│ │ ┌──────────────────────────────────────┐ │ │
│ │ │ 🔵 Lab Order — FBC, LFT, VitaminD │ │ │
│ │ │ Filed | View Report │ │ │
│ │ └──────────────────────────────────────┘ │ │
│ │ │ │
│ │ Lab Reports │ │
│ │ ┌──────────────────────────────────────┐ │ │
│ │ │ Date │ Ref │ Status │ Actions │ │ │
│ │ │ 28 Jul│ TDL… │ 🔵 Filed │ [View] │ │ │
│ │ └──────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ → Click "View Report" to see the PDF │
│ → Filed results include 21 biomarker values │
│ → Abnormal values flagged in red │
└─────────────────────────────────────────────────────────┘
Primary view: /lab/mailbox/
| Element | What it shows |
|---|---|
| Email rows | From, Subject, Attachments, Received time, Status |
| Status badges | New (🟡), Processing (🔵), Filed (🔘), Review (🔍), Error (❌) |
| Refresh button | Triggers an immediate IMAP poll |
| Attachment icon | Paperclip with count — click row to download/view original PDF |
| Reprocess button | Appears on Error rows — re-runs the pipeline |
Daily tasks:
Primary view: Patient record at /accounts/patients/<id>/
| Section | What it shows |
|---|---|
| Lab Orders | Pending → Received → Filed timeline for each ordered test |
| Lab Reports | All filed PDFs with source, status, and view link |
| "+ Log Lab Order" button | Opens modal to select tests and save order |
Additional views:
/lab/ — Document inbox showing all processed documents needing review/lab/documents/<uuid>/verify/ — Split-screen verify & file interfacePrimary view: /lab/config/
| Section | Fields |
|---|---|
| TDL Settings | Account ID, Decryption password |
| IMAP Mailbox | Email address, IMAP password, Server, Port, SSL toggle |
Setup checklist:
/lab/config//lab/mailbox/ for incoming results)LabOrderTracks a clinician's request for lab tests.
| Field | Purpose |
|---|---|
patient + clinician |
Who it's for and who ordered it |
tests_ordered |
JSON array of test codes (e.g. ["FBC", "LFT"]) |
status |
PENDING → RECEIVED → FILED |
tdl_order_ref |
Reference from TDL eViewPlus portal |
lab_document |
Linked when results arrive and are matched |
PracticeMailboxIMAP credentials for receiving TDL emails.
| Field | Purpose |
|---|---|
clinic_config |
Links to TDL config (password shared for decryption) |
mailbox_email |
e.g. results-practice@lab.veripath.co.uk |
imap_password |
Encrypted at rest |
imap_server / imap_port |
Connection details |
tdl_filter |
Default: @tdlpathology.com |
PracticeEmailMessageStores fetched email metadata.
| Field | Purpose |
|---|---|
mailbox |
Which mailbox it came from |
uid |
IMAP UID (deduplication) |
from_address, from_name, subject |
Email headers |
received_at |
From email Date header |
has_attachments, attachment_count |
Attachment info |
raw_attachment |
Original PDF file (downloadable) |
lab_document |
Linked LabDocument once processed |
status |
NEW → PROCESSING → MATCHED/REVIEW/ERROR → FILED |
LabDocumentThe processed PDF with patient match.
| Field | Purpose |
|---|---|
patient |
Matched patient (null until matched) |
source |
DIRECT, EMAIL, IMAP, PORTAL |
status |
PENDING → MATCHED/REVIEW/ERROR → FILED |
file |
Decrypted PDF (stored in media storage) |
extracted_raw_text |
Full text from pdfplumber |
metadata |
Parsed: name, DOB, lab_ref, NHS number |
LabReport / LabResult / BiomarkerGranular biomarker data (EAV schema).
| Model | Purpose |
|---|---|
LabReport |
One per document filed |
Biomarker |
Lookup table of test types |
LabResult |
Individual values with reference ranges |
| URL | Purpose | Visible to |
|---|---|---|
/lab/mailbox/ |
Email inbox — monitor incoming TDL results | Receptionist, Clinician, Admin |
/lab/mailbox/<id>/ |
Email detail — view body, download attachment | All staff |
/lab/ |
Document inbox — pending reviews | Clinician, Admin |
/lab/upload/ |
Manual PDF upload | All staff |
/lab/config/ |
TDL + IMAP settings | Practice Manager, Admin |
/lab/orders/ |
All lab orders list | Clinician, Admin |
/lab/documents/<uuid>/ |
Document detail + PDF preview | Clinician, Admin |
/lab/documents/<uuid>/verify/ |
Split-screen verify & file | Clinician only |
/accounts/patients/<id>/ |
Patient record (Lab Orders + Lab Reports cards) | Clinician, Admin |