External Event Effect

Last updated: 5 Oct 2026

The ExternalEvent effect provides a way to create and update external clinical events within the Canvas platform. External events represent clinical encounters from external data sources such as ADT (Admission, Discharge, Transfer) feeds, enabling tracking of patient visits that occur outside of Canvas.

Build an ExternalEvent with the attributes you want to set, then return one of its two methods from your handler: create() for a new external event, or update() for an existing one.

Methods #

create() → Effect #

Creates an external event.

patient_id, visit_identifier, message_control_id, and event_type are required.
external_event_id must not be set.

update() → Effect #

Updates an existing external event.

external_event_id is required, and must be the id of an existing external event.
Only the attributes you set on the effect are changed. Attributes you leave unset keep their current values.

Attributes #

Attribute	Type	Description	Required
`external_event_id`	`str` or `UUID` or `None`	Unique identifier of an existing external event. Must be unset when creating.	For `update()`
`patient_id`	`str` or `None`	ID of the patient for this event.	For `create()`
`visit_identifier`	`str` or `None`	Identifier for the visit/encounter.	For `create()`
`message_control_id`	`str` or `None`	Unique identifier for the message (e.g., HL7 message control ID).	For `create()`
`event_type`	`str` or `None`	Type of event (e.g., “ADT^A01” for admission).	For `create()`
`event_datetime`	`datetime` or `None`	Date and time when the event occurred.	No
`event_cancelation_datetime`	`datetime` or `None`	Date and time when the event was cancelled. Set this to mark an event as cancelled.	No
`message_datetime`	`datetime` or `None`	Date and time when the message was sent.	No
`information_source`	`str` or `None`	Source of the event information (e.g., hospital name, system name).	No
`facility_name`	`str` or `None`	Name of the facility where the event occurred.	No
`raw_message`	`str` or `None`	Raw message content (e.g., original HL7 message).	No

Validation & Errors #

Before any effect is emitted, the model runs these checks:

Create Validation #

external_event_id must not be set (will be generated by the system)
patient_id is required
visit_identifier is required
message_control_id is required
event_type is required

Update Validation #

external_event_id is required and must reference an existing external event
All other fields are optional; only dirty (modified) fields are updated

Example Usage #

from datetime import datetime

from canvas_sdk.effects.external_event import ExternalEvent
from canvas_sdk.v1.data.external_event import ExternalEvent as ExternalEventModel
from canvas_sdk.v1.data.patient import Patient

patient = Patient.objects.first()

Create an Admission Event #

# Create an external event for a hospital admission
admission_event = ExternalEvent(
    patient_id=str(patient.id),
    visit_identifier="VISIT-2024-001234",
    message_control_id="MSG-20240115-143052",
    event_type="ADT^A01",  # Admission
    event_datetime=datetime.now(),
    message_datetime=datetime.now(),
    information_source="General Hospital ADT Feed",
    facility_name="General Hospital - Main Campus",
    raw_message="MSH|^~\&|HOSPITAL|FAC|CANVAS|...",
)

effect_create = admission_event.create()

Create a Discharge Event #

# Create an external event for a discharge
discharge_event = ExternalEvent(
    patient_id=str(patient.id),
    visit_identifier="VISIT-2024-001234",  # Same visit as admission
    message_control_id="MSG-20240118-091530",
    event_type="ADT^A03",  # Discharge
    event_datetime=datetime.now(),
    message_datetime=datetime.now(),
    information_source="General Hospital ADT Feed",
    facility_name="General Hospital - Main Campus",
)

effect_discharge = discharge_event.create()

Cancel an Existing Event #

# Find an existing external event to cancel
existing_event = ExternalEventModel.objects.filter(
    patient__id=patient.id,
    event_cancelation_datetime__isnull=True,  # Not already cancelled
).first()

if existing_event:
    # Cancel the event by setting the cancelation datetime
    cancel_effect = ExternalEvent(
        external_event_id=str(existing_event.id),
        event_cancelation_datetime=datetime.now(),
    )

    effect_cancel = cancel_effect.update()

Update Event Details #

# Update an existing external event with additional information
existing_event = ExternalEventModel.objects.filter(patient__id=patient.id).first()

if existing_event:
    updated_event = ExternalEvent(
        external_event_id=str(existing_event.id),
        facility_name="General Hospital - West Wing (Corrected)",
        raw_message="MSH|^~\&|HOSPITAL|FAC|CANVAS|...|CORRECTED",
    )

    effect_update = updated_event.update()

Create Event with All Fields #

# Create an external event with all optional fields populated
complete_event = ExternalEvent(
    # Required fields
    patient_id=str(patient.id),
    visit_identifier="VISIT-2024-005678",
    message_control_id="MSG-20240120-163045",
    event_type="ADT^A01",
    # Optional datetime fields
    event_datetime=datetime(2024, 1, 20, 16, 30, 0),
    message_datetime=datetime(2024, 1, 20, 16, 30, 45),
    # Optional string fields
    information_source="Regional Medical Center - HL7 Interface",
    facility_name="Regional Medical Center - Emergency Department",
    raw_message="MSH|^~\&|RMC|ED|CANVAS|RECV|20240120163045||ADT^A01|MSG123|P|2.5",
)

effect_complete = complete_event.create()

Common Event Types #

The event_type field typically contains HL7 ADT event codes:

Event Type	Description
ADT^A01	Admit/Visit Notification
ADT^A02	Transfer a Patient
ADT^A03	Discharge/End Visit
ADT^A04	Register a Patient
ADT^A08	Update Patient Information
ADT^A11	Cancel Admit/Visit Notification
ADT^A12	Cancel Transfer
ADT^A13	Cancel Discharge/End Visit