External Event Effect

Last updated: 22 Jan 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.

Attributes #

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

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

Effect Methods #

`create()` #

Create a new external event record.

Effect Type: CREATE_EXTERNAL_EVENT
Payload: { "data": { patient_id, visit_identifier, message_control_id, event_type, ... } }

`update()` #

Update an existing external event.

Effect Type: UPDATE_EXTERNAL_EVENT
Payload: { "data": { external_event_id, <dirty_fields> } }
Only fields marked dirty (modified on the model) are included in the update.

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