Commands

The commands module lets you define commands within a specific note in Canvas, which capture and display data. Each command can be imported into a plugin and used to build a new, or reference an existing, command instance within a specific note.

The following commands are available for use in this module:

Common Attributes #

Parameters #

All commands share the following init kwarg parameters:

NameTypeRequiredDescription
user_idstringtrueThe externally exposable id of the user performing the command action.
note_idstringtrue if creating a new commandThe externally exposable id of the note in which to insert the command.
command_uuidstringtrue if updating an existing commandThe externally exposable id of the command which is being referenced.

All parameters can be set upon initialization, and also updated on the class instance.

Methods #

All commands have the following methods:

originate #

Returns an Effect that originates a new command in the note body.

edit #

Returns an Effect that edits an existing command with the values set on the command class instance.

delete #

Returns an Effect that deletes an existing, non-committed command from the note body.

commit #

Returns an Effect that commits an existing, non-committed command to the note body.

enter_in_error #

Returns an effect that enter-in-errors an existing, committed command in the note body.

Example:

from canvas.commands import PlanCommand

def compute():

    existing_plan = PlanCommand(user_id='fg787uu', command_uuid='63hdik', narrative='something new')
    new_plan = PlanCommand(user_id='fg787uu', note_id='rk786p', narrative='new')
    new_plan.narrative = 'newer'

    return [existing_plan.edit(), new_plan.originate()]

Command-specific details for each command class can be found below.

Assess #

Command-specific parameters:

NameTypeRequiredDescription
condition_idstringtrueThe externally exposable id of the condition being assessed.
backgroundstringfalseBackground information about the diagnosis.
statusStatus enumfalseThe current status of the diagnosis. Must be one of AssessCommand.Status
narrativestringfalseThe narrative for the current assessment.
    
Status 
IMPROVED“improved”
STABLE“stable”
DETERIORATED“deteriorated”

Example:

from canvas.commands import AssessCommand

assess = AssessCommand(
    user_id='fg787uu',
    note_id='rk786p',
    condition_id='hu38rlo',
    background='started in 2012',
    status=AssessCommand.Status.STABLE,
    narrative='experiencing more pain lately'
)

Diagnose #

Command-specific parameters:

NameTypeRequiredDescription
icd10_codestringtrueICD-10 code of the condition being diagnosed.
backgroundstringfalseBackground information about the diagnosis.
approximate_date_of_onsetdatetimefalseThe approximate date the condition began.
today_assessmentstringfalseThe narrative for the initial assessment of the condition.
    

Example:

from canvas.commands import DiagnoseCommand
from datetime import datetime

diagnose = DiagnoseCommand(
    user_id='fg787uu',
    note_id='rk786p',
    icd10_code='M54.50',
    background='lifted heavy box',
    approximate_date_of_onset=datetime(2012, 1, 1),
    today_assessment='unable to sleep lately'
)

Goal #

Command-specific parameters:

NameTypeRequiredDescription
goal_statementstringtrueDescription of the goal.
start_datedatetimefalseThe date the goal begins.
due_datedatetimefalseThe date the goal is due.
achievement_statusAchievementStatus enumfalseThe current achievement status of the goal.
priorityPriority enumfalseThe priority of the goal.
progressstringfalseA narrative about the patient’s progress toward the goal.
    
AchievementStatus 
IN_PROGRESS“in-progress”
IMPROVING“improving”
WORSENING“worsening”
NO_CHANGE“no-change”
ACHIEVED“achieved”
SUSTAINING“sustaining”
NOT_ACHIEVED“not-achieved”
NO_PROGRESS“no-progress”
NOT_ATTAINABLE“not-attainable”
Priority 
HIGH“high-priority”
MEDIUM“medium-priority”
LOW“low-priority”

Example:

from canvas.commands import GoalCommand
from datetime import datetime

goal = GoalCommand(
    user_id='fg787uu',
    note_id='rk786p',
    goal_statement='Eat more healthy vegetables.',
    start_date=datetime(2024, 1, 1),
    due_date=datetime(2024, 12, 31),
    achievement_status=GoalCommand.AchievementStatus.IN_PROGRESS,
    priority=GoalCommand.Priority.HIGH,
    progress='patient is frequenting local farmers market to find healthy options'
)

HistoryOfPresentIllness #

Command-specific parameters:

NameTypeRequiredDescription
narrativestringtrueThe narrative of the patient’s history of present illness.
    

Example:

from canvas.commands import HistoryOfPresentIllnessCommand

hpi = HistoryOfPresentIllnessCommand(
        user_id='fg787uu',
        note_id='rk786p',
        narrative='presents with chronic back pain and headaches'
    )

MedicationStatement #

Command-specific parameters:

NameTypeRequiredDescription
fdb_codestringtrueThe fdb code of the medication.
sigstringfalseAdministration details of the medication.
    

Example:

from canvas.commands import MedicationStatementCommand

medication_statement = MedicationStatementCommand(
    user_id='fg787uu',
    note_id='rk786p',
    fdb_code='198698',
    sig='two pills taken orally'
)

Plan #

Command-specific parameters:

NameTypeRequiredDescription
narrativestringtrueThe narrative of the patient’s plan.
    

Example:

from canvas.commands import PlanCommand

plan = PlanCommand(
    user_id='fg787uu',
    note_id='rk786p',
    narrative='will return in 2 weeks to check on pain management'
)

Prescribe #

Command-specific parameters:

NameTypeRequiredDescription
fdb_codestringtrueThe fdb code of the medication.
icd10_codeslist[string]falseA list of ICD-10 codes representing the indications for the prescription.
sigstringtrueAdministration instructions/details of the medication.
days_supplyintegerfalseThe number of days that the prescription should last.
quantity_to_dispenseDecimaltrueHow much of the medication to dispense.
type_to_dispensestringtrueThe unit which is dispensed.
refillsintegertrueThe number of refills available to the patient.
substitutionsSubstitutions enumfalseThe substitution status of the medication.
pharmacystringfalseThe name of the pharmacy to send the prescription to.
prescriber_idstringtrueThe externally exposable id of the provider prescribing the medication.
note_to_pharmaciststringfalseA freetext note to include for the pharmacist with additional instructions.
    
Substitutions 
ALLOWED“allowed”
NOT_ALLOWED“not_allowed”

Example:

from canvas.commands import PrescribeCommand
from decimal import Decimal

prescribe = PrescribeCommand(
        user_id='fg787uu',
        note_id='rk786p',
        fdb_code='198698',
        icd10_codes=['M54.50'],
        sig='1 po bid pc',
        days_supply=10,
        quantity_to_dispense=Decimal(10),
        type_to_dispense='tablet',
        refills=1,
        substitutions=PrescribeCommand.Substitutions.NOT_ALLOWED,
        pharmacy='Main Street in Spring Lake',
        prescriber_id='298uhh',
        note_to_pharmacist='please give patient oral instructions'
    )

Questionnaire #

Command-specific parameters:

NameTypeRequiredDescription
questionnaire_idstringtrueThe externally exposable id of the questionnaire being answered by the patient.
resultstringfalseA summary of the result of the patient’s answers.
    

Example:

from canvas.commands import QuestionnaireCommand

questionnaire = QuestionnaireCommand(
    user_id='fg787uu',
    note_id='rk786p',
    questionnaire_id='g73hd9',
    result='The patient is feeling average today.'
)

ReasonForVisit #

Command-specific parameters:

NameTypeRequiredDescription
structuredbooleanfalseWhether the RFV is structured or not. Defaults to False.
codingCodingtrue if structured=TrueThe coding of the structured RFV.
commentstringfalseAdditional commentary on the RFV.
    

Example:

from canvas.commands import ReasonForVisitCommand

structured_rfv = ReasonForVisitCommand(
    user_id='fg787uu',
    note_id='rk786p',
    structured=True,
    coding={'code': '', 'system': '', 'display': ''},
    comment='also wants to discuss treament options'
)
unstructured_rfv = ReasonForVisitCommand(
    user_id='fg787uu',
    note_id='rk786p',
    comment='also wants to discuss treatment options'
)

StopMedication #

Command-specific parameters:

NameTypeRequiredDescription
medication_idstringtrueExternally exposable id of the patient’s medication being stopped.
rationalestringfalseThe reason for stopping the medication.
    

Example:

from canvas.commands import StopMedicationCommand

stop_medication = StopMedicationCommand(
    user_id='fg787uu',
    note_id='rk786p',
    medication_id='2u309j',
    rationale='In remission'
)

UpdateGoal #

Command-specific parameters:

goal_id: str = Field(json_schema_extra={“commands_api_name”: “goal_statement”}) due_date: datetime | None = None achievement_status: AchievementStatus | None = None priority: Priority | None = None progress: str | None = None

NameTypeRequiredDescription
goal_idstringtrueExternally exposable id of the goal being updated.
due_datedatetimefalseThe date the goal is due.
achievement_statusAchievementStatus enumfalseThe current achievement status of the goal.
priorityPriority enumfalseThe priority of the goal.
progressstringfalseA narrative about the patient’s progress toward the goal.
    
AchievementStatus 
IN_PROGRESS“in-progress”
IMPROVING“improving”
WORSENING“worsening”
NO_CHANGE“no-change”
ACHIEVED“achieved”
SUSTAINING“sustaining”
NOT_ACHIEVED“not-achieved”
NO_PROGRESS“no-progress”
NOT_ATTAINABLE“not-attainable”
Priority 
HIGH“high-priority”
MEDIUM“medium-priority”
LOW“low-priority”

Example:

from canvas.commands import UpdateGoalCommand
from datetime import datetime

update_goal = UpdateGoalCommand(
    user_id='fg787uu',
    note_id='rk786p',
    goal_id='0j9whjjk',
    due_date=datetime(2025, 3, 31),
    achievement_status=GoalCommand.AchievementStatus.WORSENING,
    priority=GoalCommand.Priority.MEDIUM,
    progress='patient has slowed down progress and requesting to move due date out'
)