Update patient sharing settings

Turns patient-to-patient sharing, and the patient and practitioner invites (/v1/invites), on or off for the caller's project.

Auth: bearer token of a project admin. Scope: the caller's project (from the token).

Behaviour

• enabled is required. Turning it on creates the read-only sharing template AccessPolicy, or brings an existing one up to date, in the same atomic write as the setting. The template lets a recipient read and search the sharer's Observations with the shared codes, and read the sharer's Patient resource with contact details, identifiers and most other fields hidden.
• Turning enabled off stops new invites and redemptions. Existing shares stay until they are ended.
• enabled also lets a signed-in patient share Observation codes with a related person by email (POST /v1/invites/record-share with "recipient": "related-person"). A new address gets a related-person account when it accepts, with a built-in base policy that reads only its own RelatedPerson; it is created the first time it is needed. Map RELATED_PERSON_INVITED and RELATED_PERSON_RECORD_SHARED, or the PATIENT_INVITE and PATIENT_ASSIGNMENT_REQUEST templates they fall back to: an invite whose email cannot be sent is undone.
• practitionerSharingEnabled does the same for the patient and practitioner invites, with the practitioner share's template. Leave it out or send null to keep its current value.
• Both are off by default. The response is the settings after the write, as GET /v1/patient-sharing/settings returns them.
• With practitionerSharingEnabled on, a signed-in patient can create a practitioner account (with the project's default practitioner access policy) for a new address, and a practitioner can create a patient account, each holding the share. Make sure that policy gives a new practitioner nothing a patient should not hand out. Map the PATIENT_INVITE, PATIENT_ASSIGNMENT_REQUEST, PRACTITIONER_INVITED_BY_PATIENT and PRACTITIONER_PATIENT_SHARED email templates first: an invite whose email cannot be sent is undone.
• Do not turn on practitionerSharingEnabled in projects whose practitioners use the carehub dashboard: its route guard checks resource types only, so a practitioner who only holds shared patients could see project-wide data there.
• practitionerAlertDigest turns the clinician alert digest on or off: { "enabled": true, "everyHours": 6 }, where everyHours is 1, 6, 12 or 24. Leave everyHours out to keep the saved hours (6 until set). Leave the whole field out, or send null, to keep the digest as it is.
  • Switching it on needs Signals annotations (SIGNALS_ANNOTATE_OBSERVATIONS), enabled and practitionerSharingEnabled all on; otherwise the write is refused with 409 SETTING_NOT_AVAILABLE. A write that only keeps it on is not checked, so sharing can still be turned off. While any of the three is off, no digest goes out.
  • Every everyHours, each practitioner on an active practitioner share gets one email listing their patients with new Signals alerts: the patient's name, how many new alerts, and a link to the patient's alerts in the dashboard. It carries no reading or value, and nothing goes out when there are no new alerts.
  • It counts alerts from the moment it was switched on, never the backlog before. Switching it off, or one of its prerequisites going off, forgets where it was, so switching it on again starts afresh.
  • Each digest covers alerts up to an hour before it goes out: alerts reach FHIR through a flush that can lag, and an alert that arrives more than an hour late is not counted.
  • Map the PRACTITIONER_ALERT_DIGEST email template first.
• A 409 without a code means the project's settings changed during the write. Read the settings again and retry.

Example

curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-sharing/settings' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "enabled": true, "practitionerSharingEnabled": null, "practitionerAlertDigest": { "enabled": true, "everyHours": 6 } }'