Replace an org's rule settings
Replace an org's rule settings, through Ovok's Signals gateway.
Replace an org's rule settings
| Method | Path |
|---|---|
PUT | /v1/signals/api/settings/org |
- Sandbox: not available
- Staging: available
- Production: unknown
Deprecated
This route is deprecated. The description below names its successor.
Deprecated: a tenant's rule settings are orgSettings on GET and PATCH /api/tenant. This route still serves the per-project rows of a tenant several projects share.
Replaces the settings for project, or the tenant-wide row without it, whole. A patient whose metadata.project has a row reads that row; any other patient reads the tenant-wide row. The two are not merged. A tenant-wide write first makes a tenant's only project row its tenant-wide row, as PATCH /api/tenant does. Audited as UPDATE_ORG_SETTINGS.
With ifAbsent=true the row is created only when none exists and never replaced, so a default seeded at enrolment cannot overwrite a concurrent save; the answer adds created and carries the stored document either way, and only a creation is audited.
A body whose settings has no triggers key keeps the stored triggers (the home defaults seeded by Signals, or triggers pushed through the config routes); a body that sends triggers, {} included, replaces them.
The body may carry resolvedAt (ISO 8601), when the caller resolved this write: it lands only over a stored write resolved earlier, or stored without one, and is otherwise refused 409 STALE_SETTINGS with nothing written or audited. A write without resolvedAt always lands and keeps the stored stamp.
Signals stores settings as given and reads it only through the triggers it holds (triggers, the home's and the resident's own): what each other key means is theirs, so the object is checked for shape and size only. The default pack reads bands — per code { low?, high? }, { mode: 'baseline', pct, low?, high? } (outside either band fires; a patient's own baseline band with no sides of its own is judged alone) or "NO_THRESHOLD" — and outOfBed: { limitSeconds, enabled?, returnSeconds?, window?: { start: 'HH:MM', end: 'HH:MM', timeZone } }. A patient's own key wins over the org's; extra keys are ignored. See tech/RULES-ENGINE.md.
Through ovok
- Who can call it: Manager apps, and users whose access policy grants the capabilities.
- Capabilities, all required:
signals_config:update,signals_silence:update. Project admins have every capability; client applications get no admin bypass. - Your tenant keeps one org row, the tenant-wide one, so
projectisn't taken. - It can reach any patient of your project without naming one, so it is for callers that reach every patient: project admins, manager or submitter apps, and anyone whose Patient access has no criteria.
- Deprecated. Use
/v1/signals/api/tenant.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
ifAbsent | boolean | No | Create the row only when none exists, never replace one: a default seeded at enrolment must not overwrite a concurrent save of the home. |
Body
Required. Schema WriteStampedSettingsDto.
| Field | Type | Required | Description |
|---|---|---|---|
resolvedAt | string | No | — |
settings | object | Yes | — |
Responses
| Status | Meaning |
|---|---|
200 | The settings as stored, kept triggers included (with created under ifAbsent). |
400 | The query carries a raw #, or more than 200 parameters. |
401 | Your ovok access token, or your client id and secret, are missing or invalid. |
403 | ovok refused the call: you lack a capability this route needs, or your session has no project, or your access covers only some patients. From Signals: Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
409 | Your project has no Signals tenant of its own (SIGNALS_TENANT_NOT_OWN), or it is moving to another one. From Signals: A write resolved no later than the stored one (STALE_SETTINGS); nothing was written. |
415 | The body is not JSON. |
422 | project was sent, or resolvedAt is more than 5 minutes ahead of now. From Signals: settings is missing, is not a plain object or is over 64 KiB, or project or resolvedAt is invalid. |
429 | Too many requests. Retry after the seconds in Retry-After. |
500 | ovok hit an unexpected fault, such as your project having no Signals submitter. |
502 | Signals answered with something ovok couldn't use, or refused ovok's own credential. |
503 | Signals is unavailable. Retry after the seconds in Retry-After. |
504 | Signals did not answer in time. |
Example
curl --request PUT 'https://api.sandbox.ovok.com/v1/signals/api/settings/org' \
--user "${OVOK_CLIENT_ID}:${OVOK_CLIENT_SECRET}" \
--header 'Content-Type: application/json' \
--data @body.jsonLast updated on