SGN note state is not in the docs or in the SDK code?

[misham]

Hello,

I am seeing a new (to me) note state SGN showing up but I can't find it in the docs: https://docs.canvasmedical.com/sdk/data-note/#notestates and when searching through the latest code I have, version 0.142.0

Can you share any details about this state?

[rmagier1]

Hi @misham,

Good catch — SGN is a real, current note state, and you're right that it's missing from the docs. Quick answer below, but I also just updated the documentation to include this state.

What SGN is

SGN = Signed. It's part of the NoteStates enum in the SDK and lives here in the code.

SIGNED = "SGN", "Signed"

It was added in #1292 ("feat: add support for note lock, sign, unlock, check_in and no_show effects") and first shipped in canvas-plugins 0.85.0, so it's been in the package well before 0.142.0 you're on. If you do from canvas_sdk.v1.data.note import NoteStates; print(NoteStates.SIGNED) in 0.142.0 it should resolve fine.

What "signing" means in the workflow

When a provider signs a note, they're attesting that the note's clinical content is complete and accurate — it's the closing step of a clinical encounter. After signing, the note is effectively sealed for that visit. If something needs to change later, the provider has to amend the note (unlock it, edit, re-lock, re-sign), which leaves a full audit trail rather than letting changes happen silently against a "finished" record.

Whether a given note type requires a signature is configured per-note-type by your practice admin via the is_sig_required flag on NoteType. The admin-side workflow for toggling this is documented here: Configuring note signing requirements. Some note types (e.g., chart review notes, certain appointment types) don't require a signature — those skip SGN entirely and are considered "done" once they reach LKD.

How that shows up in the state machine

For note types where is_sig_required = True, the transitions involving SGN are:

• LKD → SGN — "Sign": the provider signs a locked note
• SGN → ULK — "Amend": the provider unlocks the signed note to make corrections
• SGN → SGN — idempotent re-sign of an already-signed note (no state change beyond logging the action)

A typical amend-and-resign flow goes through unlock and lock again, not directly back to SGN:

SGN → ULK → LKD → SGN
(amend)  (re-lock) (re-sign)

For note types where is_sig_required = False, the state machine stops at LKD and you'll never see SGN.

You can branch on this from a plugin:

if note.note_type_version.is_sig_required:
    # SGN is a possible state for this note
    ...

What this means for your data

A few practical things to know if you're querying or reporting on note state:

• Terminal state differs by note type. For sig-required note types, the "fully completed" state is SGN, not LKD. If you're filtering for completed notes, you generally want state == SGN for sig-required types and state == LKD for non-sig types — filtering on LKD alone will miss the bulk of sig-required notes that have moved past locking.
• Amendment cycles. A single note may pass through SGN multiple times. A typical signed-then-amended history looks like NEW → LKD → SGN → ULK → LKD → SGN. Each entry is a separate row in NoteStateChangeEvent, so you can see exactly when each sign / amend / re-sign happened. The most recent state is on CurrentNoteStateEvent; the full history is on note.state_history.
• Audit context. Each NoteStateChangeEvent records the user who originated the transition, so the state history doubles as a sign/amend audit trail (who, when, in what order).

[misham]

Awesome, thank you