Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Spec: specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md
Status: ✅ Complete
Last Updated: 2026-03-28

​
Events

​
ce_lead_converted_to_patient

FieldValue
PublisherCE (useLeadMutations.convertLead)
SubscribersPM-01 (patient registration), PM-38 (appointment automation), Analytics
DeliveryAt-least-once (FW-16)
Idempotencycorrelation_id — subscribers must deduplicate
Payload (IDs only — no PHI): 
{
  lead_id: string;        // UUID
  contact_id: string;     // UUID
  organization_id: string; // UUID
  correlation_id: string;  // Format: "{lead_id}_to_{type}_{timestamp}"
  converted_to_type: string;
  converted_to_id?: string;
  converted_by: string;    // UUID (user)
  converted_at: string;    // ISO 8601
}

​
ce_lead_converted_to_resident

Same payload schema as above. Subscribers: RH-01 (admission), PM-39 (waitlist), Analytics.

​
ce_lead_converted (deprecated)

Legacy event maintained for backward compatibility with CE-17 consumers. Same payload. New consumers should use the granular events above.

​
Audit Table: ce_lead_conversions

Pattern: INSERT-only (no UPDATE/DELETE policies). Immutable audit trail.
ColumnTypeNotes
idUUIDPK
organization_idUUIDTenant isolation (FK → pf_organizations)
lead_idUUIDFK → ce_leads
conversion_typeTEXTlead_to_patient, lead_to_resident, lead_to_both
correlation_idTEXTIdempotency key
patient_idUUIDNullable — set by PM-01 subscriber
resident_idUUIDNullable — plain UUID (no FK until RH-01 creates rh_residents)
converted_byUUIDUser who triggered conversion
notesTEXTOptional (max 500 chars)
custom_fieldsJSONBExtension point
created_atTIMESTAMPTZConversion timestamp
created_byUUIDAudit

​
Permissions

KeyDescription
ce.lead-conversions.viewView conversion history
ce.lead-conversions.createTrigger lead conversion
Mapped to: org_admin, platform_admin

​
Idempotency Rules

  1. Each conversion generates a unique correlation_id in format {lead_id}_to_{conversion_type}_{timestamp}. The correlation_id is created once per user intent and must be reused unchanged across retries or double-submits — it is not regenerated on each attempt.
  2. For lead_to_both, two audit records are inserted (one per type) with distinct correlation IDs
  3. Downstream subscribers (PM-01, RH-01) MUST check correlation_id before creating entities
  4. Duplicate delivery with same correlation_id returns success without creating a second record (enforced by UNIQUE constraint on (organization_id, lead_id, conversion_type, correlation_id))

​
References

  • Full Spec: specs/ce/specs/CE-29-lead-to-patient-conversion-pipeline.md
  • Integration Doc: docs/architecture/integrations/CE-29-LEAD-CONVERSION-INTEGRATION.md
  • Event Contracts: docs/architecture/integrations/EVENT_CONTRACTS.md
  • CE-17 (deprecated): specs/ce/specs/CE-17-ce-rh-admission-handoff.md