OZO FHIR implementation guide
0.9.0 - ci-build
OZO FHIR implementation guide - Local Development build (v0.9.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The OZO platform connects care professionals with informal caregivers. The platform is able to create a link between the formal healthcare network with the informal social environment of the patient. Hereby the OZO platform needs to cross borders of healthcare and open up to the social context of the patents.
TODO: give a functional overview.
For a complete list of all FHIR profiles, examples, and resources defined in this Implementation Guide, see the Artifacts page. The Artifacts page includes links to the FSH source files for all resources.
Please refer to the following documentation of the Dutch name element:
The FHIR API is based on FHIR R4 and makes use of the following FHIR resources:
Profile: OZOPatient
The Patient represents the client in the domain, for each real-life patient only one single entity exists. The
Patient
is primary identified by the BSN. Required fields:
| field | cardinality | description |
|---|---|---|
| identifier | 1..* | Open slicing. Recognized: BSN (http://fhir.nl/fhir/NamingSystem/bsn), email. Any ozoverbindzorg.nl/namingsystem/ system supported. |
| name | 1..* | The name field, ZIB |
| gender | 1..1 | |
| birthDate | 1..1 | |
| active | 1..1 | true |
The identifier of the Patient must be unique and should the internal identifier of the patient in the OZO system.
Profile: OZORelatedPerson
The related person resource represents the relation between Patient and a informal caregiver (RelatedPerson). For
each relationship
between a patient and informal caregiver one related person exists. For each real-life person multiple related person
resources exist, one for each patient it has a caregiving relationship with.
| field | cardinality | description |
|---|---|---|
| identifier | 1..* | Open slicing. Recognized: email. Any ozoverbindzorg.nl/namingsystem/ system supported. |
| name | 1..* | The name field, ZIB |
| patient | 1..1 | The reference to the patient |
| relationship | 1..1 | system=urn:oid:2.16.840.1.113883.5.111 |
| active | 1..1 | true |
The relationship coding can be found here:
The OZO FHIR RelatedPerson uses two identities to identify the RelatedPerson entity:
Profile: OZOPractitioner
The Practitioner represents a health care professional that has a relationship with one or more patients. The
practitioner is linked to the patient by the care team. OZOPractitioner extends the NL Generic Functions Practitioner profile (nl-gf-practitioner), providing compliance with the Dutch care services directory and IHE mCSD alignment.
| field | Cardinality | description |
|---|---|---|
| identifier[AssignedId] | 1..1 | System: https://www.ozoverbindzorg.nl/namingsystem/professional (required by NL-GF) |
| identifier[big] | 0..* | BIG registration number (http://fhir.nl/fhir/NamingSystem/big) |
| identifier[uzi] | 0..* | UZI number (http://fhir.nl/fhir/NamingSystem/uzi-nr-pers) |
| identifier[agb] | 0..* | AGB code (http://fhir.nl/fhir/NamingSystem/agb-z) |
| name | 1..* | The name field, ZIB |
| active | 1..1 | true |
For details on directory participation and identifier requirements, see the Care Services Directory page.
The identifier of the Practitioner must be unique and should be the internal identifier of the practitioner in the OZO
system.
Profile: OZOCareTeam
The CareTeam is the resource that binds the patient to the related person(s) and practitioners. There should exist
only one care team resource for each patient in the system. Multiple care team resources could exist if specific use
cases require this. A CareTeam has a set of participants that consists of a member. For practitioners, this
relationship should also contain the onBehalfOf property, linking to the Organization, this maps the relation of
the Patient to different Organizations. Participants can also include organizational teams (see below) for nested team references.
| field | Cardinality | description |
|---|---|---|
| subject | 1..1 | reference to the Patient |
| participant | 1..* | a reference to a Practitioner, RelatedPerson, Patient (self-reliant client), or OZOOrganizationalCareTeam (nested team) |
| status | 1..1 | "active" |
Profile: OZOOrganizationalCareTeam
The OZOOrganizationalCareTeam represents a department or organizational unit (e.g., pharmacy team, clinic team) that is not bound to a specific patient. It is used for:
senderCareTeam extension) and recipient in conversations between organizationsCareTeam| field | Cardinality | description |
|---|---|---|
| subject | 0..0 | not allowed — organizational teams have no patient |
| name | 1..1 | team display name |
| category | 1..* | SNOMED CT coded team type (e.g., pharmacy service, general medicine) |
| managingOrganization | 1..1 | reference to the Organization this team belongs to |
| participant | 1..* | a reference to a Practitioner (only practitioners, no RelatedPerson) |
| status | 1..1 | "active" |
Profile: OZOOrganization
The Organization resource represents the different organizations in the network. OZOOrganization extends the NL Generic Functions Organization profile (nl-gf-organization), providing compliance with the Dutch care services directory and IHE mCSD alignment. The relation between the Patient and Organization is managed by the participant in the care team. Each member of type Practitioner has an onBehalfOf reference to the Organization.
| field | Cardinality | description |
|---|---|---|
| identifier[ura] | 0..* | URA identifier (required unless partOf is set) |
| identifier[AssignedId] | 1..1 | Platform-assigned identifier with assigner (required by NL-GF) |
| type | 1..* | Organization type from Nictiz organization-type code system |
| name | 1..1 | The name of the Organization |
For details on directory participation and identifier requirements, see the Care Services Directory page.
The different interactions are described in the following guides:
Messaging can be used within the OZO FHIR API. To achieve this, the following 2 FHIR Resources are used:
Profile: OZOCommunicationRequest
The CommunicationRequest Resource is used to:
| field | Cardinality | description |
|---|---|---|
| status | 1..1 | draft | active | completed |
| subject | 1..1 | Reference to a Patient |
| requester | 1..1 | a reference to a RelatedPerson, Practitioner or Patient (individual who initiated - for auditability) |
| sender | 0..1 | a reference to a RelatedPerson, Practitioner or Patient (individual sender) |
| extension[senderCareTeam] | 0..1 | a reference to an organizational CareTeam: the initiating team of a team thread (reply-to address). Should not be repeated in recipient (the 0.8.x shape with the duplicate is accepted in 0.9.0 with a warning) |
| recipient | 1..* | the addressed parties: references to RelatedPerson, Practitioner or CareTeam. For team-to-team threads this is the addressed team only; the initiating team is in extension[senderCareTeam] |
| payload | 1..* | Message or attachment, one of contentString or contentAttachment |
The CommunicationRequest supports team-level messaging through the senderCareTeam extension (FHIR R4 CommunicationRequest.sender does not allow CareTeam references):
requester: Always an individual (Practitioner or RelatedPerson) - tracks who initiated the conversation for auditabilitysender: Always an individual (Practitioner or RelatedPerson) - the person who created the threadextension[senderCareTeam]: A CareTeam reference that enables team-level messaging:
CareTeam (OZOOrganizationalCareTeam, no subject) the requester is a participant of. The AAA proxy rejects the thread otherwise. Patient care teams never act as a team: one Task per team applies to organizational teams onlyrecipient: Lists the addressed parties. The initiating team should not be repeated here (invariant ozo-cr-sender-careteam-not-in-recipient, a warning in 0.9.0 and an error from the next release; the 0.8.x shape with the duplicate is accepted meanwhile and has no effect). The thread parties are the set union of recipient and extension[senderCareTeam]; the custom search parameter participant covers both with a union expression, and the AAA proxy scopes access to threads and messages on it. That is what gives the members of the initiating team access to their own thread.Replies are Communication resources with partOf set to the thread; they carry no recipient of their own, but they do carry extension[senderCareTeam] with the team on whose behalf the message is sent. Threads initiated by a team can be found with the custom search parameter sender-careteam. See Team-to-Team Messaging for the full flow.
Profile: OZOCommunication
The Communication resource is used to:
| field | Cardinality | description |
|---|---|---|
| status | 1..1 | preparation | in-progress | not-done | on-hold | stopped | completed | entered-in-error | unknown |
| partOf | 1..1 | Reference to a CommunicationRequest |
| inResponseTo | 0..1 | Optional quote-reply link to one specific earlier Communication. Not used by the OZO FHIR Api; the thread link is partOf |
| sender | 1..1 | a reference to a RelatedPerson, Practitioner or Patient (must be individual for auditability) |
| extension[senderCareTeam] | 0..1 | the organizational CareTeam on whose behalf the message is sent. Required when the sender is a participant of an organizational team of the thread; see Team-to-Team Messaging |
| recipient | 0..* | Unused — thread parties are defined on CommunicationRequest |
| payload | 1..* | Message or attachment, one of contentString or contentAttachment |
The Communication.sender must always be an individual (Practitioner or RelatedPerson) to ensure auditability. Every message in the system must have an identifiable person as the sender. This applies even in team-level messaging scenarios - while the thread may be owned by a CareTeam, each individual message is sent by a specific person. The team the person acts for is named separately in extension[senderCareTeam].
The Attachment resource is used to:
CommunicationRequest and Communication resource.Profile: OZOTask
The Task resource is used to:
| field | Cardinality | description |
|---|---|---|
| status | 1..1 | requested (unread) or completed (read) |
| basedOn | 1..1 | Reference to a CommunicationRequest |
| intent | 1..1 | order |
| for | 1..1 | a reference to a Patient |
| focus | 0..1 | the latest Communication in the thread |
| owner | 1..1 | a reference to a RelatedPerson, Practitioner or Patient (per-person Task) or to an organizational CareTeam (one Task per team in team threads) |
The OZO FHIR Api creates one Task per thread party: per member of a patient care team or individually addressed person, and one per organizational team with owner set to the CareTeam. A server still in the 0.8.x mode (allowed during the 0.9.0 transition) creates one Task per member of an organizational team as well; clients must accept both owner kinds. See Team-to-Team Messaging.
owner = CareTeamProfile: OZOAuditEvent (custom profile for NEN7510 compliance)
The AuditEvent is used to:
Task status field as client of the OZO FHIR ApiFor detailed information about NEN7510 compliance and audit logging, see AuditEvent for NEN7510 Compliance.
agent.extension[careTeam])Profile: Subscription (based on FHIR R4 Subscription resource)
The Subscription resource is used for clients of the OZO FHIR Api to receive updates about events in the changes in the FHIR Api:
The different interactions are described in the following guides: