Leave a note on a notification
- Sandbox: available
- Staging: available
- Production: unknown
Leaves a note on a notification. A note is a practitioner's comment on a notification, stored as a FHIR Communication whose basedOn points at the alert. The alert itself is never changed.
Auth: Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant Patient:read (an admin or super admin who holds no access policy skips this check). Only a practitioner can write notes.
Scope: The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
Behaviour
kindnames the feed the notification comes from:ooboralarmwith the row'scommIdasid,medicalwith the row'sepisode.id, oralertwith a raw Signals alert'sid.- A note on a raw alert is also listed and counted on that alert's episode. Which episode is decided once, when the note is written.
textis trimmed and must be 1 to 2000 characters.- The author is the calling practitioner, never a body field.
- Notes can be left on acknowledged notifications too.
medicalandalertnotes are read from Signals first, so they answer 503signals_unavailablewhile Signals is down. Retry once Signals is back.- Answers 201 with the note as stored.
Example
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/notes' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "kind": "oob", "id": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "text": "Resident was in the bathroom." }'bearerAuthorizationBearer <JWT>application/json- body
kind*string"oob""alarm""medical""alert"id*string^[A-Za-z0-9-]{1,64}$text*string1 <= length <= 2000The note as stored.
application/json- response
id*stringtarget*patientId*stringtext*stringauthor*createdAt*stringdate-timeupdatedAt*stringdate-timecurl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/notes' \ -H 'Content-Type: application/json' \ -d '{ "kind": "oob", "id": "string", "text": "string"}'{ "id": "string", "target": { "kind": "oob", "id": "string" }, "patientId": "string", "text": "string", "author": { "practitionerId": "string", "name": "string" }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z"}Acknowledge medical notification POST
Acknowledges one medical notification, so it leaves the medical bell. The acknowledgement is written to Signals, which owns medical episodes. **Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant `Patient:read` (an admin or super admin who holds no access policy skips this check). **Scope:** The caller's project (from the token). Ovok reads the episode with your project and checks its resident against your project before it writes anything. ## Behaviour - No CommunicationRequest is created or changed. Signals closes the episode with reason `ACKNOWLEDGED`. A resident still outside the band opens a new episode on their next reading. - Repeating the call is safe. - Answers 200 with the acknowledged row, in the feed's row shape, already carrying the new `acknowledgement` and closed status. Replace the list entry with it; no refetch is needed. - `acknowledgement.acknowledgedBy` is Ovok's client id at Signals, not a person; do not show it as a name. `acknowledgement.acknowledgedActor` is the caller's profile reference and display name, or `null` when the session has no profile. - Ovok clears its cached index of the project's open episodes, so other reads see the episode as closed straight away rather than after a cache expiry. - An episode in another project, an out-of-bed episode (code `103214-3`) or one that does not exist answers the same 404, and nothing is acknowledged. Acknowledge an out-of-bed alert with `PATCH /v1/slim/notifications/{id}/ack`. - A 409 means the project's Signals tenant has episodic alerts switched off. - While Signals does not answer, Ovok keeps trying for up to 12 seconds before it answers. A 503 (`signals_unavailable`) means Ovok could not confirm the acknowledgement; repeat the call after `retryAfterSec` (also sent as `Retry-After`). ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/c3499c27-2973-0a7f-807e-fb8676a92dcb/ack' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
An out-of-bed notification's notes GET
Lists the notes on an out-of-bed notification. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed. **Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant `CommunicationRequest:read` and `CommunicationRequest:search` (an admin or super admin who holds no access policy skips this check). **Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404. ## Behaviour - `id` is the notification row's `commId`. - Newest first. Deleted notes are not listed. - Read-only. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/oob/c3499c27-2973-0a7f-807e-fb8676a92dcb/notes' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```