Note Effects
Note Effects #
The Canvas SDK provides effects to facilitate creating, updating, and managing visit notes, appointments, and schedule events. Below you’ll find detailed documentation for each effect type and their operations.
Note Effect #
The Note
effect facilitates the creation and updating of visit notes for patients.
Attributes #
Attribute | Type | Description | Required |
---|---|---|---|
note_type_id | UUID or str | Identifier for the note type | Yes |
datetime_of_service | datetime.datetime | When the service was provided | Yes |
patient_id | str | Identifier for the patient | Yes |
practice_location_id | UUID or str | Identifier for the practice location | Yes |
provider_id | str | Identifier for the provider | Yes |
title | str or None | Optional title for the note | No |
Implementation Details #
- Validates that the note type exists and has an appropriate category
- Ensures the patient exists in the system
- Verifies that the practice location and provider are valid
Example Usage #
from canvas_sdk.effects.note.note import Note
import datetime
note_effect = Note(
note_type_id="note-type-uuid",
datetime_of_service=datetime.datetime.now(),
patient_id="patient-uuid",
practice_location_id="practice-location-uuid",
provider_id="provider-uuid"
)
return note_effect.create()
Update Note #
Updates an existing note. Only certain fields can be modified after creation.
Attributes #
Attribute | Type | Description | Required | Updatable |
---|---|---|---|---|
instance_id | UUID or str | Identifier of the note to update | Yes | No |
title | str or None | Updated title for the note | No | Yes |
datetime_of_service | datetime.datetime | Updated service date/time | No | Yes |
practice_location_id | UUID or str | Updated practice location | No | Yes |
provider_id | str | Updated provider | No | Yes |
Note: patient_id
and note_type_id
cannot be updated after creation.
Example Usage #
from canvas_sdk.effects.note.note import Note
note_effect = Note(instance_id="existing-note-uuid")
note_effect.title = "Updated Consultation Notes"
note_effect.datetime_of_service = datetime.datetime.now()
return note_effect.update()
ScheduleEvent Effect #
The ScheduleEvent
effect enables creating, updating, and deleting schedule events for providers, with optional patient association.
Attributes #
Attribute | Type | Description | Required |
---|---|---|---|
note_type_id | UUID or str | Identifier for the note type (must be of category SCHEDULE_EVENT ) | Yes |
patient_id | str or None | Identifier for the patient (if applicable) | Conditional |
description | str or None | Custom description for the event | Conditional |
start_time | datetime.datetime | Start time of the event | Yes |
duration_minutes | int | Duration of the event in minutes | Yes |
practice_location_id | UUID or str | Identifier for the practice location | Yes |
provider_id | str | Identifier for the provider | Yes |
status | AppointmentProgressStatus or None | Status of the event | No |
external_identifiers | list[AppointmentIdentifier] or None | External system identifiers | No |
Implementation Details #
- Validates that the note type exists and is of category
SCHEDULE_EVENT
- Ensures patient is provided if the note type requires it
- Verifies that custom descriptions are only used for note types that allow them
- Validates that the practice location and provider exist
Example Usage #
from canvas_sdk.effects.note.create_appointment import ScheduleEvent
import datetime
schedule_event_effect = ScheduleEvent(
note_type_id="schedule-event-note-type-uuid",
patient_id="patient-uuid", # Optional depending on note type
description="Team meeting", # Optional depending on note type
start_time=datetime.datetime.now(),
duration_minutes=30,
practice_location_id="practice-location-uuid",
provider_id="provider-uuid"
)
return schedule_event_effect.create()
Update Schedule Event #
Updates an existing schedule event by creating a new event and cancelling the original.
Attributes #
Attribute | Type | Description | Required |
---|---|---|---|
instance_id | UUID or str | Identifier of the event to update | Yes |
start_time | datetime.datetime | New start time | No |
duration_minutes | int | New duration in minutes | No |
description | str or None | Updated description | No |
practice_location_id | UUID or str | New practice location | No |
provider_id | str | New provider | No |
status | AppointmentProgressStatus or None | Updated status | No |
Example Usage #
from canvas_sdk.effects.note.appointment import ScheduleEvent
schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")
schedule_event_effect.start_time = datetime.datetime.now() + datetime.timedelta(days=1)
schedule_event_effect.duration_minutes = 60
schedule_event_effect.description = "Rescheduled team meeting"
return schedule_event_effect.update()
Delete Schedule Event #
Marks a schedule event as cancelled.
Example Usage #
from canvas_sdk.effects.note.appointment import ScheduleEvent
schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")
return schedule_event_effect.delete()
Appointment Effect #
The Appointment
effect facilitates creating, updating, and cancelling patient appointments with providers.
Attributes #
Attribute | Type | Description | Required |
---|---|---|---|
appointment_note_type_id | UUID or str | Identifier for the appointment note type (must be of category ENCOUNTER and scheduleable) | Yes |
patient_id | str | Identifier for the patient | Yes |
meeting_link | str or None | Link for virtual appointments | No |
start_time | datetime.datetime | Start time of the appointment | Yes |
duration_minutes | int | Duration of the appointment in minutes | Yes |
practice_location_id | UUID or str | Identifier for the practice location | Yes |
provider_id | str | Identifier for the provider | Yes |
status | AppointmentProgressStatus or None | Status of the appointment | No |
external_identifiers | list[AppointmentIdentifier] or None | External system identifiers | No |
Implementation Details #
- Validates that the appointment note type exists, is of category
ENCOUNTER
, and is scheduleable - Ensures the patient exists in the system
- Verifies that the practice location and provider exist
Example Usage #
from canvas_sdk.effects.note.create_appointment import Appointment
import datetime
appointment_effect = Appointment(
appointment_note_type_id="appointment-note-type-uuid",
patient_id="patient-uuid",
meeting_link="https://zoom.us/example-link", # Optional
start_time=datetime.datetime.now(),
duration_minutes=60,
practice_location_id="practice-location-uuid",
provider_id="provider-uuid"
)
return appointment_effect.create()
Update Appointment #
Updates an existing appointment by creating a new appointment and cancelling the original. This maintains the appointment history and ensures proper tracking of rescheduled appointments.
Attributes #
Attribute | Type | Description | Required |
---|---|---|---|
instance_id | UUID or str | Identifier of appointment to update | Yes |
start_time | datetime.datetime | New start time | No |
duration_minutes | int | New duration in minutes | No |
meeting_link | str or None | Updated meeting link | No |
practice_location_id | UUID or str | New practice location | No |
provider_id | str | New provider | No |
status | AppointmentProgressStatus or None | Updated status | No |
external_identifiers | list[AppointmentIdentifier] or None | Updated external identifiers | No |
Note: patient_id
cannot be updated after creation.
Example Usage #
from canvas_sdk.effects.note.appointment import Appointment
appointment_effect = Appointment(instance_id="existing-appointment-uuid")
appointment_effect.start_time = datetime.datetime.now() + datetime.timedelta(hours=2)
appointment_effect.duration_minutes = 45
appointment_effect.meeting_link = "https://new-meeting-link.com"
return appointment_effect.update()
Cancel Appointment #
Cancels an existing appointment and updates its status.
Example Usage #
from canvas_sdk.effects.note.appointment import Appointment
appointment_effect = Appointment(instance_id="existing-appointment-uuid")
return appointment_effect.cancel()
Validation #
All effects perform comprehensive validation before execution:
- Entity Existence: Validates that referenced entities (patients, providers, practice locations, note types) exist in the system
- Type Compatibility: Ensures note types are appropriate for the intended operation:
- Visit notes cannot use
APPOINTMENT
,SCHEDULE_EVENT
,MESSAGE
, orLETTER
note types - Schedule events must use
SCHEDULE_EVENT
note types - Appointments must use
ENCOUNTER
note types that are scheduleable
- Visit notes cannot use
- Field Requirement Enforcement: The system validates conditional field requirements based on note type configurations:
- Patient Association Requirements: For note types with
is_patient_required=True
, the system enforces that a valid patient ID is provided. This is particularly important for schedule events that may or may not be associated with specific patients. - Custom Description Validation: When a note type has
allow_custom_title=False
, the system prevents custom descriptions from being added. This ensures adherence to standardized naming conventions for certain types of appointments and events. - Required Field Validation: All required fields are checked for proper values and formats before the effect is executed.
- Patient Association Requirements: For note types with
- Update Restrictions: Certain fields cannot be modified after creation:
- Notes:
patient_id
andnote_type_id
are immutable - Appointments:
patient_id
is immutable - All Effects: At least one field must be modified for an update operation to succeed
- Notes: