Latest SIG not reliably available from a single Canvas read source after ChangeMedicationCommand

[jayant-walvekar-falconeer]

We are updating medication SIG using the Canvas SDK ChangeMedicationCommand (originate + commit on a note).

Issue:
After the command is committed, we are not consistently able to read the latest SIG back from a single Canvas medication read source.

Important:
This issue happens always, not intermittently.

What we observe:

• The patient chart shows the latest SIG.
• ChangeMedicationCommand doesn't appear in the note on the UI but it appears if we fetch the note via API
• But when we read medications via API/SDK, the latest SIG is not consistently returned from one canonical location.
• After some experimentation, we found that the latest SIG can be discovered only by checking multiple sources:
  • medication-level SIG fields
  • medication statement text
  • latest committed ChangeMedicationCommand in notes

Questions:

1. After ChangeMedicationCommand is committed, what is the correct read path for the latest SIG?
2. What consistency timing should we expect after commit?
3. Should the latest SIG be reliably available from one resource, without having to reconcile against note commands?
4. If not, what is the recommended integration pattern for reading the current SIG?

[rmagier1]

Hi @jayant-walvekar-falconeer ,

How latest_sig works

The "latest SIG" shown in the patient chart is not a stored field on the Medication record — it's a computed property that Canvas calculates on the fly each time it's read. It searches across all committed commands that can carry a SIG for that medication and returns the one from the most recent note (by date of service).

The priority order is:

┌─────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                   Source                    │                                             When it wins                                             │
├─────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Prescription / Refill / Adjust Prescription │ If its note's date of service is more recent than the latest ChangeMedication                        │
├─────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ChangeMedication                            │ If its note's date of service is more recent than the latest Prescription, or no prescriptions exist │
├─────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ MedicationStatement                         │ Fallback — used only if no prescriptions or ChangeMedication records exist                           │
└─────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┘

This is why you're seeing the SIG spread across multiple sources — it's not inconsistency, it's that Canvas intentionally derives the "current" SIG from the most recent command rather than storing it in one place. A ChangeMedicationCommand commit writes the SIG to its own record but doesn't overwrite any field on the Medication or MedicationStatement model.

Reading the latest SIG

Via FHIR API (recommended for external integrations):

The computed latest_sig is returned in the MedicationStatement resource's dosage[0].text field:
GET /MedicationStatement/{medication_id}

  {
    "dosage": [
      {
        "text": "Two tablets twice daily with meals"
      }
    ]
  }

This returns the same value displayed in the chart. The value is available immediately after commit — there is no async delay.

Via SDK (for use within plugins):

The latest_sig property is not currently exposed in the SDK data models. However, you can replicate the same logic by querying the Command model. The SIG is stored in each command's data JSON field under the key sig:

  from canvas_sdk.v1.data.command import Command

  def get_latest_sig(patient_id: str, medication_dbid: int) -> str:
      """
      Replicates the chart's latest_sig logic using the SDK Command model.
      Checks changeMedication, prescribe, refill, adjustPrescription, and
      medicationStatement commands in priority order based on note date of service.
      """
      commands = (
          Command.objects.filter(
              patient__id=patient_id,
              schema_key__in=[
                  "changeMedication",
                  "prescribe",
                  "refill",
                  "adjustPrescription",
                  "medicationStatement",
              ],
              state="committed",
          )
          .select_related("note")
          .order_by("-note__datetime_of_service", "-dbid")
      )

      for cmd in commands:
          data = cmd.data or {}

          # Each command type stores the medication reference differently
          if cmd.schema_key == "changeMedication":
              med_id = data.get("medication", {}).get("value")
          elif cmd.schema_key in ("prescribe", "refill", "adjustPrescription"):
              med_id = data.get("prescribe", {}).get("value")
          elif cmd.schema_key == "medicationStatement":
              med_id = data.get("medication_statement", {}).get("value")
          else:
              continue

          if med_id == medication_dbid:
              return data.get("sig", "")

      return ""

The medication_dbid is the integer database ID of the Medication (available as medication.dbid in the SDK). Since commands are ordered by note date of service descending, the first match for your medication is the most recent SIG — matching the same logic the chart uses.

Regarding ChangeMedication not appearing in the note

You mentioned that the ChangeMedicationCommand doesn't appear in the note on the UI. Can you share more details on this — specifically which note you're looking at and how the command was originated (via the UI, a plugin, or the API)? The command should appear in the note body regardless of how it was created, so we'd like to understand what you're seeing to help debug. Or you can open a support ticket for this specific issue, because we may have a bug we need to look into more.

Let us know if you have any other questions!

[jayant-walvekar-falconeer]

Point 1 — latest_sig logic:

Thank you for the detailed explanation of how latest_sig is computed. I have updated my plugin to replicate this logic — querying across all five command types (changeMedication, prescribe, refill, adjustPrescription, medicationStatement) ordered by note datetime_of_service.

However, I would like to understand the design rationale here. The SIG is conceptually a property of the medication. It is what the patient sees and what clinicians' reference. But to read the current SIG, an App has to query the Command model across five different schema keys, understand the different reference key structures (medication.value vs prescribe.value vs medication_statement.value), and implement date-based priority ordering. This feels like an internal implementation detail that's been pushed to the plugin consumer.

Is there a reason latest_sig isn't exposed as a computed property on the Medication data model in the SDK? Or surfaced through a helper/utility? I noticed the FHIR API does return it cleanly via dosage[0].text on MedicationStatement, but for plugins that use the SDK there's no equivalent. I have to rebuild the derivation logic ourselves.

I want to make sure I am not missing a simpler path. If this is truly the intended design for SDK consumers, I will work with it — but it would be great to know if there are any plans to expose this more directly. Any change in this model will break my code.

Point 2 — ChangeMedicationCommand not rendering in note UI:

How I create the command in our plugin:

Note already exists and is editable

note = Note.objects.get(id=note_key)
note_uuid = str(note.id)

medication_id is the UUID from Medication model (Patient.medications → med.id)

command = ChangeMedicationCommand(
medication_id=,
sig=,
note_uuid=note_uuid,
)
command.command_uuid = str(uuid4())
effects = [command.originate(), command.commit()]
return effects
Verified result from the Note data:

When I list all the notes using plugin API and look at this particular note object, I see that the note ash
Command UUID, State: committed, Origination source: plugin
Data: { "sig": "<my_new_data>", "medication": { <expected_object>} }
The note body references the command: { "type": "command", "value": "changeMedication", "data": { "command_uuid": "..." } }

The command is originated, committed, and present in the note body — but the Canvas UI renders the note as empty. StopMedicationCommand using the same pattern renders correctly with "Stop Medication: ..." in the UI.

Could you check if there's a rendering issue for plugin-originated changeMedication commands?

[rmagier1]

@jayant-walvekar-falconeer

Yes, good point about the fact that a lot of canvas out of the box functionality relies on computed properties. I think this example is an excellent example of a place where we need to improve, whether that is store this on the Medication table or add a helper/property to the SDK Data Module to have. I logged this as an issue #1620 so we can try to improve that, so you dont have to manage that logic manually.

As for the changeMedication, looks like those commands were not enabled in your environments. I have fixed that, can you try again?

[jayant-walvekar-falconeer]

@rmagier1 ChangeMedication command is now appearing in the note. Thanks for fixing this. Looking forward to the fix for #1620

[jayant-walvekar-falconeer]

Any ETA on this?

[rmagier1]

Hi @jayant-walvekar-falconeer,

Thanks for following up, and apologies for the wait. I don't have an ETA to share on #1620 right now — it's tracked on our backlog but hasn't been scheduled the roadmap yet.

In the meantime, the two paths from earlier in this thread are still the recommended ones:

• FHIR (recommended): read MedicationStatement.dosage[0].text — that already returns the computed latest SIG and avoids reimplementing the priority logic across the five command types. From inside a plugin you can hit this via the CanvasFhir client
• From inside a plugin: the Command-model snippet above will give you the same value the chart shows.

If the lack of a direct SDK accessor is becoming a blocker for you, let me know and I can raise the priority internally with any context of what you are trying to achieve.