Settings and features
Understand project features, settings, defaults, and the APIs that control them in Ovok.
Each project has two kinds of controls. Features switch platform capabilities on for the whole project. Settings configure how a user flow behaves.
Feature or setting?
A feature is a capability the platform turns on for your project: automations, scheduled jobs, email sent from automations, live subscriptions, all-or-nothing batch writes, AI, and document-reading operations. Off, it is unavailable to everyone in the project.
A setting is a rule for how your project behaves for its users: who may sign in, register or be invited, where emailed links point, and which access policy a new practitioner receives. Off, the affected flow refuses one audience while other operations keep working.
Features answer “Can my project do this at all?” Settings answer “How should my project behave?”
Which one do I need?
| Feature | Setting | |
|---|---|---|
| Shape | Names from a fixed list; a listed feature is on. | Named values, such as a Boolean or text value; every supported key has a default. |
| Read | GET /v1/projects/me/features returns { features: [...] }. | GET /v1/project/settings returns every key: what is saved, and what Ovok applies (effectiveSettings). Unset text reads as null. |
| Write | PATCH /v1/projects/me/features replaces the whole list. | PUT /v1/project/settings/:key changes one Boolean; PUT /v1/project/settings/values/:key changes one text value. |
| Usually set | When the project is created. | By admins as the app evolves. |
| Inheritance | None. | On/off values do not inherit. App URLs can fall back to the parent project. |
| Concurrent edit | A write can return 409: read again, reapply your change, retry. | Same. |
Any practitioner can read both; a project admin writes. For the examples below, set OVOK_TOKEN to a practitioner access token for the current project.
Project features
A PATCH replaces the project's whole feature list, so omitting a feature turns it off. To add cron, read the list, add cron, then send the entire updated list.
curl --get 'https://api.sandbox.ovok.com/v1/projects/me/features' \
--header "Authorization: Bearer ${OVOK_TOKEN}"| Response field | Example | Meaning |
|---|---|---|
features | bots, cron, email, transaction-bundles, websocket-subscriptions | Complete list of feature names currently enabled for this project. |
curl --request PATCH \
--url 'https://api.sandbox.ovok.com/v1/projects/me/features' \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"features":["bots","cron","email","transaction-bundles","websocket-subscriptions","ai"]}'The available feature names include:
| Feature | Enables |
|---|---|
bots | Automations. |
cron | Scheduled jobs. Add bots as well to run automations on a schedule. |
email | Email sent by automations. It does not control the emails Ovok sends itself. |
websocket-subscriptions | Live updates through WebSocket subscriptions. |
transaction-bundles | All-or-nothing FHIR transaction bundles. Without it, a transaction bundle runs as a batch. |
ai | The AI operation, called with your own model key. |
aws-comprehend | Accepted and stored; no operation depends on it today. Comprehend Medical analysis is an option of aws-textract. |
aws-textract | Document-reading and text-extraction operations. Needs S3 file storage on the platform. |
google-auth-required | Require Google sign-in where the platform's standard sign-in applies. |
graphql-introspection | Accepted and stored; GraphQL introspection is currently controlled platform-wide. |
validate-terminology | Rejects coded values that break a required terminology binding when a resource is written. |
Edit the feature list with care
The 409 only protects against a write that overlaps yours inside the same request. If two admins each read the list and send it back, the second write silently overwrites the first. Read the list immediately before you write it, and send every feature you want to keep.
Project settings
GET /v1/project/settings returns every setting of the current project. The path is singular.
- 1Project settings control sign-in and registration.
- 2Toggle a setting, then save the app URL used in email links.
| Field | Holds | Use it to |
|---|---|---|
effectiveSettings | Each on/off switch as Ovok applies it: the saved value, else the default, and false while the switch lacks a setting it depends on. | Decide whether a flow works. |
overrides | Each on/off switch's saved value, or null when none is saved. | See what an admin chose. |
settings | Each on/off switch, true only when saved as true. Kept for older clients. | Nothing new: an unset switch reads false here even when it is on by default. |
values | Each text setting: app URLs and default access policies, null when unset. | Read app URLs and policies. |
To change a Boolean, send {"enabled": true} or {"enabled": false} to PUT /v1/project/settings/:key. To set a text value, send {"value": "..."} to PUT /v1/project/settings/values/:key. Send {"value": null} to remove a stored text value.
curl --get 'https://api.sandbox.ovok.com/v1/project/settings' \
--header "Authorization: Bearer ${OVOK_TOKEN}"curl --request PUT \
--url 'https://api.sandbox.ovok.com/v1/project/settings/PATIENT_REGISTRATION_ENABLED' \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"enabled":false}'curl --request PUT \
--url 'https://api.sandbox.ovok.com/v1/project/settings/values/PRACTITIONER_APP_URL' \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"value":"https://app.example.com"}'Defaults and dependencies
A switch with no saved value uses its default. A switch whose dependency is missing is saved as on but does nothing, and effectiveSettings shows false. Read effectiveSettings, not settings, to know whether a flow works, and set what a switch needs before you turn it on.
| Setting | Default when unset | Needs, or effectiveSettings is false |
|---|---|---|
PATIENT_LOGIN_ENABLED | On | — |
PRACTITIONER_LOGIN_ENABLED | On | — |
PATIENT_INVITATION_ENABLED | On | DEFAULT_PATIENT_ACCESS_POLICY set. |
PRACTITIONER_INVITATION_ENABLED | On | — |
RELATED_PERSON_LOGIN_ENABLED | On | — |
RELATED_PERSON_INVITATION_ENABLED | On | — |
PATIENT_REGISTRATION_ENABLED | On | DEFAULT_PATIENT_ACCESS_POLICY naming an AccessPolicy of the project. |
PRACTITIONER_REGISTRATION_ENABLED | Off | DEFAULT_PRACTITIONER_ACCESS_POLICY naming an AccessPolicy of the project. |
CLINICIAN_INVITE_ON_BUSINESS_EMAIL | Off | Patient registration in effect, and DEFAULT_PRACTITIONER_ACCESS_POLICY. |
effectiveSettings does not check app URLs or email templates. CLINICIAN_INVITE_ON_BUSINESS_EMAIL also needs both app URLs and the CLINICIAN_SIGNUP_INVITE email template; without them, the person is registered as a patient and the caller is not told.
Settings are not permissions
An auth setting controls whether a sign-in, registration, or invitation flow can run. It does not define what a signed-in user can read or change; that is the access policy's job.
Turning a login switch off stops new sign-ins. Once the login-switch change is deployed, it will also stop token renewals. A token already issued can remain valid until it expires, for up to 60 minutes.
A registration switch needs only the dependency in the table above. Invitations also need the applicable default AccessPolicy and the matching app URL (PATIENT_APP_URL or PRACTITIONER_APP_URL); if none resolves, the invite answers 409 app_url_not_configured. The settings response shows only values stored on the current project, so an app URL shown as null may still resolve from a parent project.
Quick reference
| I want to… | Switch |
|---|---|
| Run automations | Feature bots. |
| Run automations on a schedule | Features bots and cron. |
| Send email from an automation | Feature email. |
| Write several records all-or-nothing | Feature transaction-bundles. |
| Get live updates | Feature websocket-subscriptions. |
| Require Google sign-in | Feature google-auth-required. |
| Stop patients registering themselves | Setting PATIENT_REGISTRATION_ENABLED = false. |
| Pause practitioner sign-in | Setting PRACTITIONER_LOGIN_ENABLED = false. |
| Let admins invite colleagues | Setting PRACTITIONER_INVITATION_ENABLED, plus PRACTITIONER_APP_URL and a default practitioner AccessPolicy. |
| Let practitioners register themselves | Setting PRACTITIONER_REGISTRATION_ENABLED = true, plus DEFAULT_PRACTITIONER_ACCESS_POLICY. |
| Make emailed links open my app | Set PATIENT_APP_URL and/or PRACTITIONER_APP_URL. |
| Invite clinicians who register with a work email | CLINICIAN_INVITE_ON_BUSINESS_EMAIL, plus a default practitioner AccessPolicy and both app URLs. |
| Customise the emails Ovok sends | Email templates. |
| Let patients share data | PATIENT_SHARING_ENABLED at /v1/patient-sharing/settings. |
| Let patients invite carers | PATIENT_SHARING_ENABLED, RELATED_PERSON_INVITATION_ENABLED, RELATED_PERSON_LOGIN_ENABLED and PATIENT_APP_URL. See Carers. |
Reserved settings
MAILING_ENABLED and CONTENT_ENABLED (which the Console sets when you enable the CMS) are accepted settings keys but do not control an active Ovok flow yet. Treat them as reserved; use the email feature to allow email sent from automations.
Last updated on