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?

FeatureSetting
ShapeNames from a fixed list; a listed feature is on.Named values, such as a Boolean or text value; every supported key has a default.
ReadGET /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.
WritePATCH /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 setWhen the project is created.By admins as the app evolves.
InheritanceNone.On/off values do not inherit. App URLs can fall back to the parent project.
Concurrent editA 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 fieldExampleMeaning
featuresbots, cron, email, transaction-bundles, websocket-subscriptionsComplete 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:

FeatureEnables
botsAutomations.
cronScheduled jobs. Add bots as well to run automations on a schedule.
emailEmail sent by automations. It does not control the emails Ovok sends itself.
websocket-subscriptionsLive updates through WebSocket subscriptions.
transaction-bundlesAll-or-nothing FHIR transaction bundles. Without it, a transaction bundle runs as a batch.
aiThe AI operation, called with your own model key.
aws-comprehendAccepted and stored; no operation depends on it today. Comprehend Medical analysis is an option of aws-textract.
aws-textractDocument-reading and text-extraction operations. Needs S3 file storage on the platform.
google-auth-requiredRequire Google sign-in where the platform's standard sign-in applies.
graphql-introspectionAccepted and stored; GraphQL introspection is currently controlled platform-wide.
validate-terminologyRejects 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.

  1. 1Project settings control sign-in and registration.
  2. 2Toggle a setting, then save the app URL used in email links.
FieldHoldsUse it to
effectiveSettingsEach 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.
overridesEach on/off switch's saved value, or null when none is saved.See what an admin chose.
settingsEach 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.
valuesEach 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.

SettingDefault when unsetNeeds, or effectiveSettings is false
PATIENT_LOGIN_ENABLEDOn—
PRACTITIONER_LOGIN_ENABLEDOn—
PATIENT_INVITATION_ENABLEDOnDEFAULT_PATIENT_ACCESS_POLICY set.
PRACTITIONER_INVITATION_ENABLEDOn—
RELATED_PERSON_LOGIN_ENABLEDOn—
RELATED_PERSON_INVITATION_ENABLEDOn—
PATIENT_REGISTRATION_ENABLEDOnDEFAULT_PATIENT_ACCESS_POLICY naming an AccessPolicy of the project.
PRACTITIONER_REGISTRATION_ENABLEDOffDEFAULT_PRACTITIONER_ACCESS_POLICY naming an AccessPolicy of the project.
CLINICIAN_INVITE_ON_BUSINESS_EMAILOffPatient 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 automationsFeature bots.
Run automations on a scheduleFeatures bots and cron.
Send email from an automationFeature email.
Write several records all-or-nothingFeature transaction-bundles.
Get live updatesFeature websocket-subscriptions.
Require Google sign-inFeature google-auth-required.
Stop patients registering themselvesSetting PATIENT_REGISTRATION_ENABLED = false.
Pause practitioner sign-inSetting PRACTITIONER_LOGIN_ENABLED = false.
Let admins invite colleaguesSetting PRACTITIONER_INVITATION_ENABLED, plus PRACTITIONER_APP_URL and a default practitioner AccessPolicy.
Let practitioners register themselvesSetting PRACTITIONER_REGISTRATION_ENABLED = true, plus DEFAULT_PRACTITIONER_ACCESS_POLICY.
Make emailed links open my appSet PATIENT_APP_URL and/or PRACTITIONER_APP_URL.
Invite clinicians who register with a work emailCLINICIAN_INVITE_ON_BUSINESS_EMAIL, plus a default practitioner AccessPolicy and both app URLs.
Customise the emails Ovok sendsEmail templates.
Let patients share dataPATIENT_SHARING_ENABLED at /v1/patient-sharing/settings.
Let patients invite carersPATIENT_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

On this page