Note Effects

Last updated: 5 Oct 2026

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.

Build a Note with the attributes the operation needs, then return one of its methods from your handler. Each section below covers one method and lists its attributes: create(), update(), push_charges(), lock(), sign(), unlock(), check_in(), no_show(), delete(), undelete(), discharge(), and upsert_metadata(). Faxing a note uses a separate FaxNoteEffect, covered under Fax Note.

Create Note #

create() → Effect

Creates a new note. Can be passed an optional UUID as instance_id from the uuid.uuid4 library, or will be assigned one if not present. Passing a user-set UUID as the instance_id allows for assigning commands to the note in the same plugin action.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier for the note	No
`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
`supervising_provider_id`	`str` or `None`	Staff identifier for the supervising provider	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
If supervising_provider_id is provided, validates that the Staff record exists

Example Usage #

import datetime

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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()]

To create a note and add commands to it in the same compute(), give the note an instance_id you generate, use that same value as each command’s note_uuid, and return the note’s create() effect before the command effects. Canvas applies a handler’s effects in the order they are returned, so the note exists by the time the commands are originated:

import datetime
import uuid

from canvas_sdk.commands import PlanCommand
from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_id = str(uuid.uuid4())

        note_effect = Note(
            instance_id=note_id,
            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",
        )
        plan = PlanCommand(note_uuid=note_id, narrative="Follow up in two weeks")

        return [note_effect.create(), plan.originate()]

Update Note #

update() → Effect

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
`supervising_provider_id`	`str` or `None`	Staff identifier for the supervising provider	No	Yes

Note: patient_id and note_type_id cannot be updated after creation.

Example Usage #

import datetime

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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()]

Fax Note #

FaxNoteEffect.apply() → Effect

Sends an existing note via fax to a specified recipient. This effect allows you to transmit patient notes to external healthcare providers or facilities.

Attributes #

Attribute	Type	Description	Required
`note_id`	`UUID` or `str`	Identifier of the note to fax	Yes
`recipient_name`	`str`	Name of the fax recipient	Yes
`recipient_fax_number`	`str`	Fax number of the recipient. Should include the country code	Yes
`include_coversheet`	`bool`	Whether to include a coversheet with the fax	No
`subject`	`str` or `None`	Subject line for the coversheet (required if coversheet used)	No
`comment`	`str` or `None`	Additional comments for coversheet (required if coversheet used)	No
`location_id`	`UUID` or `str` or `None`	Practice location ID (required if coversheet used)	No

Implementation Details #

Validates that the note exists in the system
If include_coversheet is True, the following fields become required:
- subject: The subject line for the coversheet
- comment: Additional comments to include on the coversheet
- location_id: The practice location identifier (must exist in the system)
Validates that the practice location exists if provided
The fax is recorded as a NoteActionEvent on the note, so a plugin reads whether it was delivered through note.action_events. See Faxes sent by a plugin

Example Usage #

from canvas_sdk.effects.fax.note import FaxNoteEffect
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        # Basic fax without coversheet
        fax_effect = FaxNoteEffect(
            note_id="existing-note-uuid",
            recipient_name="Dr. Jane Smith",
            recipient_fax_number="15551234567"
        )

        return [fax_effect.apply()]

Example with Coversheet #

from canvas_sdk.effects.fax.note import FaxNoteEffect
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        # Fax with coversheet
        fax_effect = FaxNoteEffect(
            note_id="existing-note-uuid",
            recipient_name="Dr. Jane Smith",
            recipient_fax_number="15551234567",
            include_coversheet=True,
            subject="Patient Referral - Follow-up Care",
            comment="Please review attached consultation notes for continuing care.",
            location_id="practice-location-uuid"
        )

        return [fax_effect.apply()]

Note state transitions #

The state change effects below (push charges, lock, sign, unlock, check in, no show, delete, undelete, and discharge) each move a note to a new state, and each is accepted only from certain current states. Which transitions a note allows depends on its note type’s category, and on whether the type is billable or requires a signature. An effect applied from any other state raises ValueError: Invalid state transition.

Effect	Moves the note to	Allowed from
`push_charges()`	`PSH`	`NEW`, `CVD`, `PSH`, `ULK`, `UND`. Billable encounter note types only, and only when the Push charges button is enabled.
`lock()`	`LKD`	`NEW`, `CVD`, `ULK`, `UND`, and also `PSH` for encounter notes. Appointment notes lock only from `NSW`.
`sign()`	`SGN`	`LKD`, or `SGN` to sign again. Note types with `is_sig_required` only.
`unlock()`	`ULK`	`LKD`, and also `SGN` for note types with `is_sig_required`. On appointment notes, unlocking moves `LKD` back to `NSW`.
`check_in()`	`CVD`	`BKD`, `RVT`, `NSW`. Appointment notes only.
`no_show()`	`NSW`	`BKD`, `RVT`. Appointment notes only.
`delete()`	`DLT`	`NEW`, `CVD`, `ULK`, `UND`, and also `PSH` for encounter notes. Appointment notes delete only from `SCH`.
`undelete()`	`UND`	`DLT`. Not available for appointment notes.
`discharge()`	`DSC`	`NEW`, `CVD`, `ULK`, `UND`. Inpatient notes only.

Notes in the remaining categories, such as message, letter, data, and search notes, accept none of these effects.

Push Charges #

push_charges() → Effect

Pushes the charges from the Note to its associated Claim in the Revenue module. Has the exact same effect as clicking on the Push charges button in the Note footer.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to update	Yes

Note: instance_id must be a valid, existing Note, and its NoteTypeVersion must have is_billable = True.

Example Usage #

import datetime

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.push_charges()]

To change the charge amount on a claim that already exists, use the UpdateClaimLineItem effect. Alternatively, add BillingLineItems to the patient’s note and then push charges so the claim is updated appropriately. The FHIR Claim API only supports changing the queue or adding a comment, so charge amounts cannot be edited there.

To move a claim into a specific revenue queue from a plugin — for example, to route contract-based claims that do not go through a clearinghouse into a queue your team works manually — use ClaimEffect.move_to_queue().

Lock #

lock() → Effect

Locks an existing note, preventing further modifications. Has the exact same effect as clicking on the Lock button in the Note footer.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to lock	Yes

Note: instance_id must be a valid, existing Note that is not already locked.

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.lock()]

Validating before a note is locked or signed #

To conditionally allow or block a note from being locked or signed — for example, requiring that a specific command or CPT code is present, that the signer is on the patient’s care team, or that the signer holds a matching state license — use the NOTE_STATE_CHANGE_EVENT_PRE_CREATE validation-error effect. When the validation fails, the effect prevents the state change and surfaces an error to the user. See the pre-lock-validation example plugin.

For example, to block a lock until the note has a billing line item:

from canvas_sdk.effects import Effect
from canvas_sdk.effects.validation import EventValidationError
from canvas_sdk.events import EventType
from canvas_sdk.handlers import BaseHandler
from canvas_sdk.v1.data.billing import BillingLineItem, BillingLineItemStatus


class RequireCptBeforeLock(BaseHandler):
    RESPONDS_TO = EventType.Name(EventType.NOTE_STATE_CHANGE_EVENT_PRE_CREATE)

    def compute(self) -> list[Effect]:
        if self.event.context.get("state") != "LKD":
            return []

        has_line_item = BillingLineItem.objects.filter(
            note__id=self.event.context["note_id"],
            status=BillingLineItemStatus.ACTIVE,
        ).exists()
        if has_line_item:
            return []

        error = EventValidationError()
        error.add_error("Add a CPT code before locking this note.")
        return [error.apply()]

Sign #

sign() → Effect

Signs an existing note, marking it as reviewed and approved by the provider. Has the exact same effect as clicking on the Sign button in the Note footer.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to sign	Yes

Note: instance_id must be a valid, existing Note that is not already signed.

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.sign()]

To lock and sign a note in a single plugin action, return the lock() effect before the sign() effect:

# inside compute()
note = Note(instance_id="existing-note-uuid")
return [note.lock(), note.sign()]

Unlock #

unlock() → Effect

Unlocks a previously locked/signed note, allowing modifications again. Has the exact same effect as clicking on the Unlock/Amend button in the Note footer.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to unlock	Yes

Note: instance_id must be a valid, existing Note that is currently locked.

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.unlock()]

Check In #

check_in() → Effect

Marks a patient as checked in for their appointment. Has the exact same effect as clicking on the Check In button in the Appointment note.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note for check-in	Yes

Note: instance_id must be a valid, existing Note associated with an appointment.

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.check_in()]

No Show #

no_show() → Effect

Marks an appointment as a no-show when the patient does not arrive. Has the exact same effect as marking an appointment as No Show in the Appointment note.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to mark no-show	Yes

Note: instance_id must be a valid, existing Note associated with an appointment.

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.no_show()]

Delete #

delete() → Effect

Deletes an existing note. Has the exact same effect as clicking on the Delete button in the Note footer.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to delete	Yes

Note: instance_id must be a valid, existing Note whose current state allows deletion (e.g. NEW, CONVERTED, UNLOCKED, PUSHED, or UNDELETED).

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.delete()]

Undelete #

undelete() → Effect

Restores a previously deleted note. Has the exact same effect as clicking on the Restore button on a deleted note.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note to restore	Yes

Note: instance_id must be a valid, existing Note that is currently in the DELETED state.

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-note-uuid")
        return [note_effect.undelete()]

Discharge #

discharge() → Effect

Locks and discharges an inpatient note. Has the exact same effect as clicking on the Lock and discharge button in the Inpatient note footer.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the inpatient note to discharge	Yes

Note: instance_id must be a valid, existing Note whose NoteTypeVersion.category is INPATIENT, and whose current state allows discharge (NEW, CONVERTED, UNLOCKED, or UNDELETED).

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note_effect = Note(instance_id="existing-inpatient-note-uuid")
        return [note_effect.discharge()]

Upsert Metadata #

upsert_metadata(key: str, value: str) → Effect

Creates or updates a metadata entry for the specified note. For detailed documentation on note metadata management, see NoteMetadata Effect.

Parameters #

Parameter	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the note (set on the `Note` effect)	Yes
`key`	`str`	Unique identifier for the metadata entry within the note context	Yes
`value`	`str`	The metadata value to store	Yes

Example Usage #

from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        note = Note(instance_id="existing-note-uuid")
        return [note.upsert_metadata(key="my_plugin:custom_key", value="custom_value")]

ScheduleEvent Effect #

The ScheduleEvent effect enables creating, updating, and deleting schedule events for providers, with optional patient association.

Build a ScheduleEvent with the attributes the operation needs, then return one of its methods from your handler: create(), covered here, or update(), reschedule(), or delete().

create() → Effect creates a schedule event with the attributes below.

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 #

import datetime

from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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 #

update() → Effect

Updates an existing schedule event in place.

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 #

import datetime

from canvas_sdk.effects.note import AppointmentIdentifier
from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.effects.note.base import AppointmentIdentifier
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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"
        schedule_event_effect.external_identifiers = [
            AppointmentIdentifier(system="test_system", value="123TEST")
        ]

        return [schedule_event_effect.update()]

Reschedule Schedule Event #

reschedule() → Effect

Reschedules an existing schedule event by creating a new event and cancelling the original. This maintains the event history and ensures proper tracking of rescheduled events.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the event to reschedule	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
`external_identifiers`	`list[AppointmentIdentifier]` or `None`	Updated external identifiers	No

Note: At least one field (besides instance_id) must be modified.

Example Usage #

import datetime

from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")
        schedule_event_effect.start_time = datetime.datetime.now() + datetime.timedelta(hours=3)
        schedule_event_effect.duration_minutes = 45

        return [schedule_event_effect.reschedule()]

Delete Schedule Event #

delete() → Effect

Marks a schedule event as cancelled.

Example Usage #

import datetime

from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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.

Build an Appointment with the attributes the operation needs, then return one of its methods from your handler: create(), covered here, or update(), reschedule(), cancel(), or revert().

create() → Effect creates an appointment with the attributes below.

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 #

import datetime
from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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 #

update() → Effect

Updates an existing appointment in place.

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 #

import datetime

from canvas_sdk.effects.note import AppointmentIdentifier
from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        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"
        appointment_effect.external_identifiers = [
            AppointmentIdentifier(system="my_external_system", value="appt-12345")
        ]

        return appointment_effect.update()

Reschedule Appointment #

reschedule() → Effect

Reschedules 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 reschedule	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: At least one field (besides instance_id) must be modified. patient_id cannot be updated after creation.

Example Usage #

import datetime

from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        appointment_effect = Appointment(instance_id="existing-appointment-uuid")
        appointment_effect.start_time = datetime.datetime.now() + datetime.timedelta(days=1)
        appointment_effect.duration_minutes = 60

        return appointment_effect.reschedule()

Cancel Appointment #

cancel() → Effect

Cancels an existing appointment and updates its status.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the appointment to cancel	Yes

Note: instance_id must be a valid, existing Appointment whose current state allows cancellation. An appointment can only be cancelled when it is in the BOOKED or REVERTED state.

Example Usage #

from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        appointment_effect = Appointment(instance_id="existing-appointment-uuid")

        return appointment_effect.cancel()

Revert Appointment #

revert() → Effect

Reverts a booked or checked-in appointment back to a state where it can be checked in, cancelled, rescheduled, or marked as no-show.

Attributes #

Attribute	Type	Description	Required
`instance_id`	`UUID` or `str`	Identifier of the appointment to revert	Yes

Note: instance_id must be a valid, existing Appointment whose current state allows reversion. An appointment can only be reverted when it is in the CANCELLED, CONVERTED, or NOSHOW state.

Example Usage #

from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
    def compute(self):
        appointment_effect = Appointment(instance_id="existing-appointment-uuid")

        return appointment_effect.revert()

Managing Appointment Labels #

Canvas supports adding up to 3 labels per appointment for categorization and workflow automation. Labels can be managed programmatically using the appointment label effects.

For detailed documentation on appointment label management, see Appointment Label Effects.

Quick Example #

from canvas_sdk.effects.note.appointment import AddAppointmentLabel, RemoveAppointmentLabel
from canvas_sdk.events import EventType
from canvas_sdk.handlers.base import BaseHandler

class MyHandler(BaseHandler):

    RESPONDS_TO = [EventType.Name(EventType.APPOINTMENT_LABEL_ADDED), EventType.Name(EventType.APPOINTMENT_LABEL_REMOVED)]

    def compute(self):
        # Add labels to an appointment
        add_effect = AddAppointmentLabel(
            appointment_id="appointment-uuid",
            labels={"URGENT", "FOLLOW_UP"}
        )

        # Remove labels from an appointment
        remove_effect = RemoveAppointmentLabel(
            appointment_id="appointment-uuid",
            labels={"CANCELLED"}
        )

        return [add_effect.apply(), remove_effect.apply()]

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, or LETTER note types
- Schedule events must use SCHEDULE_EVENT note types
- Appointments must use ENCOUNTER note types that are scheduleable
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.
Update Restrictions: Certain fields cannot be modified after creation:
- Notes: patient_id and note_type_id are immutable
- Appointments: patient_id is immutable
- All Effects: At least one field must be modified for an update operation to succeed

Note Effect #

Create Note #

Attributes #

Implementation Details #

Example Usage #

Update Note #

Attributes #

Example Usage #

Fax Note #

Attributes #

Implementation Details #

Example Usage #

Example with Coversheet #

Note state transitions #

Push Charges #

Attributes #

Example Usage #

Lock #

Attributes #

Example Usage #

Validating before a note is locked or signed #

Sign #

Attributes #

Example Usage #

Unlock #

Attributes #

Example Usage #

Check In #

Attributes #

Example Usage #

No Show #

Attributes #

Example Usage #

Delete #

Attributes #

Example Usage #

Undelete #

Attributes #

Example Usage #

Discharge #

Attributes #

Example Usage #

Upsert Metadata #

Parameters #

Example Usage #

ScheduleEvent Effect #

Attributes #

Implementation Details #

Example Usage #

Update Schedule Event #

Attributes #

Example Usage #

Reschedule Schedule Event #

Attributes #

Example Usage #

Delete Schedule Event #

Example Usage #

Appointment Effect #

Attributes #

Implementation Details #

Example Usage #

Update Appointment #

Attributes #

Example Usage #

Reschedule Appointment #

Attributes #

Example Usage #

Cancel Appointment #

Attributes #

Example Usage #

Revert Appointment #

Attributes #

Example Usage #

Managing Appointment Labels #

Quick Example #

Validation #

On this page