Skip to content

Note freeze and unfreeze #1070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ruipbatista wants to merge 2 commits into
base: main
Choose a base branch
from
+141 −18
Open

Note freeze and unfreeze #1070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6cb2f5f
add docs for freeze and unfreeze the note
ruipbatista Feb 19, 2026
4776b2d
updated docs based on the new implementation
ruipbatista Feb 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 80 additions & 18 deletions collections/_sdk/effects/note.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(
note_type_id="note-type-uuid",
Expand Down Expand Up @@ -80,7 +80,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(instance_id="existing-note-uuid")
note_effect.title = "Updated Consultation Notes"
Expand Down Expand Up @@ -121,7 +121,7 @@ from canvas_sdk.effects.fax.note import FaxNoteEffect
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
# Basic fax without coversheet
fax_effect = FaxNoteEffect(
Expand All @@ -140,7 +140,7 @@ from canvas_sdk.effects.fax.note import FaxNoteEffect
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
# Fax with coversheet
fax_effect = FaxNoteEffect(
Expand Down Expand Up @@ -177,7 +177,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(instance_id="existing-note-uuid")
return [note_effect.push_charges()]
Expand All @@ -204,7 +204,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(instance_id="existing-note-uuid")
return [note_effect.lock()]
Expand All @@ -231,7 +231,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(instance_id="existing-note-uuid")
return [note_effect.sign()]
Expand All @@ -258,14 +258,76 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


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

{% include alert.html type="info" content="This effect will be originated by the current actor that triggered the event, with a fallback to Canvas Bot if no actor is found." %}

### Freeze

Temporarily freezes a note, preventing other users from editing it. The note is automatically unfrozen after the specified duration. While frozen, the note displays a banner and can optionally blur the note body for non-owner users.

If the same user freezes an already-frozen note, the freeze timer is extended without modifying the note.

#### Attributes

| Attribute | Type | Description | Required |
|---------------|-----------------|--------------------------------------------------------------------|----------|
| `instance_id` | `UUID` or `str` | Identifier of the note to freeze | Yes |
| `duration` | `int` | Duration in seconds before the note is automatically unfrozen | No |
| `user_id` | `str` or `None` | Identifier of the user who is freezing the note (the "lock owner") | No |
| `blur` | `bool` | Whether to blur the note body for users other than the lock owner | No |

**Defaults**: `duration` = 300 (5 minutes), `blur` = False

#### Example Usage

```python
from canvas_sdk.effects.note.note import Note
from canvas_sdk.events import EventType
from canvas_sdk.handlers.base import BaseHandler


class MyHandler(BaseHandler):
RESPONDS_TO = EventType.Name(EventType.NOTE_BODY_UPDATED)

def compute(self):
note_effect = Note(instance_id=self.target)

return [note_effect.freeze(
duration=300,
user_id=self.context.get("user", {}).get("id"),
blur=True,
)]
```

### Unfreeze

Unfreezes a previously frozen note, allowing all users to edit it again. This also cancels any pending auto-unfreeze task.

#### Attributes

| Attribute | Type | Description | Required |
|---------------|-----------------|------------------------------------|----------|
| `instance_id` | `UUID` or `str` | Identifier of the note to unfreeze | Yes |

#### Example Usage

```python
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.unfreeze()]
Comment on lines +324 to +328
Copy link
Contributor

@rmagier1 rmagier1 Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the example above you respond to NOTE_BODY_UPDATED. For this case, how would a user know when to unfreeze the note? Like what would I suggest to people as the trigger to know someone is done in the note? I mean I guess end users may want to have an action button? Not sure

Copy link
Contributor Author

@ruipbatista ruipbatista Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is always going to depend on their user case, but unfreeze note is called automatically after the set duration has elapsed.

```

### Check In

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.
Expand All @@ -285,7 +347,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(instance_id="existing-note-uuid")
return [note_effect.check_in()]
Expand All @@ -312,7 +374,7 @@ from canvas_sdk.effects.note.note import Note
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
note_effect = Note(instance_id="existing-note-uuid")
return [note_effect.no_show()]
Expand Down Expand Up @@ -355,7 +417,7 @@ from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
schedule_event_effect = ScheduleEvent(
note_type_id="schedule-event-note-type-uuid",
Expand Down Expand Up @@ -397,7 +459,7 @@ from canvas_sdk.effects.note.base import AppointmentIdentifier
from canvas_sdk.handlers.base import BaseHandler


class Protocol(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)
Expand Down Expand Up @@ -438,7 +500,7 @@ from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.handlers.base import BaseHandler


class Protocol(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)
Expand All @@ -460,7 +522,7 @@ from canvas_sdk.effects.note.appointment import ScheduleEvent
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
schedule_event_effect = ScheduleEvent(instance_id="existing-event-uuid")

Expand Down Expand Up @@ -501,7 +563,7 @@ from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class Protocol(BaseHandler):
class MyHandler(BaseHandler):
def compute(self):
appointment_effect = Appointment(
appointment_note_type_id="appointment-note-type-uuid",
Expand Down Expand Up @@ -544,7 +606,7 @@ from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class Protocol(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)
Expand Down Expand Up @@ -582,7 +644,7 @@ from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


class Protocol(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)
Expand All @@ -602,7 +664,7 @@ from canvas_sdk.effects.note.appointment import Appointment
from canvas_sdk.handlers.base import BaseHandler


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

Expand Down
61 changes: 61 additions & 0 deletions collections/_sdk/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1878,6 +1878,67 @@ These events fire as a result of records being created, updated, or deleted.

#### Notes

<table>
<thead>
<tr><th colspan="2">NOTE_CREATED</th></tr>
<tr><td colspan="2">Occurs when a new note is created.</td></tr>
</thead>
<tbody>
<tr>
<td>Target object</td>
<td>Context object</td>
</tr>
<tr>
<td><pre>"id": note_id
"type": Note</pre></td>
<td><pre>"patient":
"id": pt_id</pre></td>
</tr>
</tbody>
</table>

<table>
<thead>
<tr><th colspan="2">NOTE_UPDATED</th></tr>
<tr><td colspan="2">Occurs when a note is updated. This fires on any save to the note, including body changes, state changes, and metadata updates.</td></tr>
</thead>
<tbody>
<tr>
<td>Target object</td>
<td>Context object</td>
</tr>
<tr>
<td><pre>"id": note_id
"type": Note</pre></td>
<td><pre>"patient":
"id": pt_id
"user":
"id": staff_id</pre></td>
</tr>
</tbody>
</table>

<table>
<thead>
<tr><th colspan="2">NOTE_BODY_UPDATED</th></tr>
<tr><td colspan="2">Occurs when the content of a note's body changes. This is a more specific event than <code>NOTE_UPDATED</code> — it only fires when the body text is actually modified, not on other note updates. Useful for triggering actions like <a href="/sdk/effect-notes/#freeze">freezing a note</a> when a user is actively editing.</td></tr>
</thead>
<tbody>
<tr>
<td>Target object</td>
<td>Context object</td>
</tr>
<tr>
<td><pre>"id": note_id
"type": Note</pre></td>
<td><pre>"patient":
"id": pt_id
"user":
"id": staff_id</pre></td>
</tr>
</tbody>
</table>

<table>
<thead>
<tr><th colspan="2">NOTE_STATE_CHANGE_EVENT_CREATED</th></tr>
Expand Down