Patient

Patient Effect #

The Patient effect enables the creation of patient records within the Canvas system. This effect captures demographic information, contact details, and clinical associations necessary for patient registration.

Attributes #

AttributeTypeDescriptionRequired
first_namestrPatient’s first nameYes
last_namestrPatient’s last nameYes
middle_namestr or NonePatient’s middle nameNo
birthdatedatetime.date or NonePatient’s date of birthNo
prefixstr or NoneName prefix (e.g., “Dr.”, “Mr.”)No
suffixstr or NoneName suffix (e.g., “Jr.”, “III”)No
sex_at_birthPersonSex or NonePatient’s sex assigned at birthNo
nicknamestr or NonePatient’s preferred name or nicknameNo
social_security_numberstr or NonePatient’s SSNNo
administrative_notestr or NoneAdministrative notes about the patientNo
clinical_notestr or NoneClinical notes about the patientNo
default_location_idstr or NoneID of patient’s default practice locationNo
default_provider_idstr or NoneID of patient’s default healthcare providerNo
previous_nameslist[str] or NoneList of patient’s previous namesNo
contact_pointslist[PatientContactPoint] or NonePatient’s contact informationNo
external_identifierslist[PatientExternalIdentifier] or NonePatient’s external identifiersNo

PatientContactPoint #

The PatientContactPoint dataclass represents various methods of contacting the patient.

Attributes #

AttributeTypeDescriptionRequired
systemContactPointSystemType of contact (e.g., phone, email)Yes
valuestrThe contact information value (e.g., phone number, email address)Yes
useContactPointUsePurpose of the contact point (e.g., home, work)Yes
rankintPriority order of contact methodsYes
has_consentbool or NoneWhether consent has been given to use this contact methodNo

PatientExternalIdentifier #

The PatientExternalIdentifier dataclass represents an external identifier (ID) associated with the patient. An example would be the unique patient ID for a third party system integrated with Canvas EMR.

Attributes #

AttributeTypeDescriptionRequired
systemstrURL of the system of origin for the external ID (e.g., http://hl7.org/fhir/sid/us-ssn)Yes
valuestrThe external ID or membership number/valueYes

Implementation Details #

  • Validates that referenced practice locations exist in the system
  • Verifies that referenced healthcare providers exist in the system
  • Structures contact information through the PatientContactPoint dataclass
  • Structures external identifier through the PatientExternalIdentifier dataclass

Example Usage #

from canvas_sdk.effects.patient import Patient, PatientContactPoint, PatientExternalIdentifier
from canvas_sdk.handlers.base import BaseHandler
from canvas_sdk.v1.data.common import ContactPointSystem, ContactPointUse, PersonSex
import datetime


class Protocol(BaseHandler):
    def compute(self):
        patient = Patient(
            first_name="Jane",
            last_name="Doe",
            middle_name="Marie",
            birthdate=datetime.date(1980, 1, 15),
            sex_at_birth=PersonSex.SEX_FEMALE,
            nickname="Janie",
            default_location_id="location-uuid",
            default_provider_id="provider-uuid",
            contact_points=[
                PatientContactPoint(
                    system=ContactPointSystem.PHONE,
                    value="555-123-4567",
                    use=ContactPointUse.MOBILE,
                    rank=1,
                    has_consent=True
                ),
                PatientContactPoint(
                    system=ContactPointSystem.EMAIL,
                    value="jane.doe@example.com",
                    use=ContactPointUse.WORK,
                    rank=2,
                    has_consent=True
                )
            ],
            external_identifiers=[
                PatientExternalIdentifier(
                    system="http://www.aaa.com",
                    value="pat_id_123456"
                )
            ]
        )

        return [patient.create()]

Validation #

The effect performs validation before execution to ensure data integrity:

  1. Required Fields: Validates that mandatory fields like first_name and last_name are provided
  2. Referenced Entity Validation: Confirms that any referenced entities exist in the system:
    • Verifies that the specified default practice location exists
    • Ensures that the specified default provider exists
  3. Data Format Validation: Ensures that provided values conform to expected formats:
    • Date fields must be valid dates
    • Enumerated types like PersonSex, ContactPointSystem, and ContactPointUse must contain valid values