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
Changes to this page per IG version. The full project history is on the Changelog page.
| Version | Date | Change |
|---|---|---|
| 0.9.0 | 2026-10-07 | Team messaging model revised as proposed in RFC - Team Messaging Model. recipient lists the addressed team; the initiating team is in extension[senderCareTeam] and should not be repeated (invariant ozo-cr-sender-careteam-not-in-recipient, a warning in 0.9.0, replaces ozo-cr-sender-careteam-in-recipient). New participant search parameter over both elements; the proxy scopes on it. One Task per organizational team with Task.owner set to the CareTeam, instead of one per member. Every team-side action names its team: extension[senderCareTeam] on Communication, agent.extension[careTeam] on the read receipt. 0.9.0 is a compatibility release: 0.8.x clients keep working (duplicate recipient accepted, team inferred when the extensions are absent, per-member Tasks until the server switches); the strict rules apply from the release after 0.9.0. Walkthrough, diagram, query patterns and examples updated. Upgrade steps for the proxy and connecting platforms are on AAA Proxy - Changes for 0.9.0. |
| 0.8.4 | 2026-10-01 | Subscription criteria Task?id, Communication?id and CommunicationRequest?id replaced by Task?, Communication? and CommunicationRequest?. id is not a search parameter (the resource id parameter is _id); HAPI only accepted the old form because it drops parameters without a value. Note on the criteria form added. |
| 0.8.3 | 2026-10-01 | Sender's team tightened to the organizational recipient teams (no subject) that list the sender as participant; a patient care team never counts, so team-wide read never applies to a patient network. extension[senderCareTeam] must be an organizational team the requester participates in. inResponseTo marked as optional in the reply steps. It is a quote-reply link between messages; the thread link is partOf and the OZO FHIR Api does not use inResponseTo. Read receipt: two entity entries instead of "entity.what has two values"; the CommunicationRequest entity is required, the Communication entity optional. Note added that "mark as unread" is not part of the model. |
| 0.8.0 | 2026-09-17 | CommunicationRequest.recipient lists both teams, including the initiating team from extension[senderCareTeam] (invariant ozo-cr-sender-careteam-in-recipient). Task handling described per sender's team (team-wide read). Read receipts use AuditEvent type access (system iso-21089-lifecycle). Query patterns use part-of instead of based-on; new sender-careteam search parameter. Sequence diagram updated. |
| 0.7.6 | 2026-04-02 | Task?status=requested is the only required subscription; Communication?id and CommunicationRequest?id are optional. Explains how Task.focus (introduced in 0.7.5) makes the Task subscription fire on every new message. |
| 0.7.1 | 2026-03-30 | Added the Task?id note for platforms that also want to detect read receipts (REQUESTED → COMPLETED). |
| 0.6.2 | 2026-03-27 | Communication.recipient is no longer set on replies; thread participants live on CommunicationRequest.recipient. Team query pattern changed to part-of:CommunicationRequest.recipient. |
| 0.6.1 | 2026-03-27 | Inline pseudo-code replaced by links to the example resources. Added the "Subscription behavior" section and the Pharmacy A / Clinic B walkthrough with Tasks, AuditEvents and notifications per step. |
| 0.6.0 | 2026-03-27 | Page created, split off from Individual Messaging. Introduces OZOOrganizationalCareTeam, the senderCareTeam extension pattern and the team-to-team sequence diagram. |
Team-to-team messaging enables organizations (pharmacies, clinics, hospitals) to communicate as units while maintaining individual auditability. This pattern uses the OZOOrganizationalCareTeam profile to represent organizational teams: CareTeams without a patient subject, linked to a managing Organization.
For individual messaging (RelatedPerson ↔ Practitioner), see Individual Messaging.
Thread parties: a thread has an addressed side and an initiating side. CommunicationRequest.recipient lists the addressed parties only: the addressed team (Team B), or individuals, or a patient care team. The initiating team (Team A) is referenced in extension[senderCareTeam] and should not be repeated in recipient. The invariant ozo-cr-sender-careteam-not-in-recipient flags a repeat; in 0.9.0 it is a warning, so threads from 0.8.x clients (which list the team in both places) are still accepted, and the duplicate has no effect because the thread parties are the set union of both elements. The severity becomes error in the release after 0.9.0. Both are thread parties: the custom search parameter participant matches either element, and the AAA proxy scopes access to threads and messages on it (see AAA Proxy). A member of the initiating team therefore sees the thread without the team being a recipient.
extension[senderCareTeam] on the CommunicationRequest names the organizational team that started the thread. This is needed because FHIR R4 CommunicationRequest.sender does not allow CareTeam references. The extension:
CareTeam (no subject) the requester is a participant of; the AAA proxy rejects the thread otherwiseCommunicationRequest.requester is always an individual (who initiated the thread)CommunicationRequest.sender is always an individual (same as requester)Communication.sender is always an individual (who sent each message)AuditEvent.agent.who is always an individual (who read a message)One Task per team: the OZO FHIR Api keeps one Task per organizational team that is a party of the thread, with Task.owner set to the CareTeam. The Task is the inbox state of the team, not of the person: requested means the team has an unread message, completed means a member has read or answered it. Every member of the team sees the team's Task (the proxy scopes Task on owner= with the user's own reference and their CareTeams). A practitioner who is in two teams of the same thread sees two Tasks, one per team, each with its own read state. Who in the team has personally seen a message stays visible in the read receipt AuditEvent resources, which is what NEN7510 asks for. Membership changes need no Task handling: a new member sees the team's Task immediately, a removed member loses access through the proxy scoping. During the 0.9.0 transition an OZO FHIR Api may still run the 0.8.x mode (one Task per member of an organizational team, team-wide read); the switch is made per environment once its clients accept a CareTeam as Task.owner, and the per-member mode is removed in the release after 0.9.0. Parties that are not organizational teams keep per-person Tasks in both modes:
Party in recipient or extension[senderCareTeam] |
Tasks |
|---|---|
Organizational CareTeam (OZOOrganizationalCareTeam, no subject) |
One Task, owner = the CareTeam |
Patient care team (OZOCareTeam, with subject) |
One Task per member, owner = the member (see Individual Messaging) |
| Individual practitioner, related person or patient | One Task, owner = that person |
Acting team: every action a person performs for a team names that team. A message carries Communication.extension[senderCareTeam]; a read receipt carries AuditEvent.agent.extension[careTeam]. Both reference an OZOOrganizationalCareTeam. The rule is the same for both: the extension is required when the sender or reader is a participant of at least one organizational team that is a party of the thread, and it must reference one of those teams. The AAA proxy rejects the message or receipt with 422 otherwise. The OZO FHIR Api acts on the named team only; the person's other teams in the same thread are treated like any other party. For a person who is in no organizational team of the thread (a related person, a patient, a practitioner addressed individually or through a patient care team) the extension is absent.
Transition: in 0.9.0 a message or read receipt without the extension is accepted. The OZO FHIR Api infers the team when the person is in exactly one organizational team of the thread; when the person is in more than one, it falls back to the 0.8.x behaviour and acts for all of them, and the proxy logs a warning. This keeps unchanged 0.8.x clients working. An extension that is present but names a wrong team is rejected with 422. From the release after 0.9.0 the extension is required and the ambiguous case is rejected; send the extension now.
This IG distinguishes the following roles when processing team-to-team messages:
CommunicationRequest, Communication, Task and AuditEvent.Both teams use the OZO platform. Unlike individual messaging, there is no OZO client involved: both sides are practitioners.
In practice, a single Subscription is enough for most teams:
Task?status=requested, required. Covers unread tracking and new-message notification for the team. The AAA proxy rewrites the criteria to owner=<practitioner>,<the practitioner's CareTeams>, so the team's Task is in scope for every member. A platform receives one notification per team Task change instead of one per member. Use Task? (every Task change) instead if the platform also needs to detect read receipts (REQUESTED → COMPLETED transitions).Optional additional subscriptions:
Communication?, optional. Only needed to see messages sent by your own team members. The team's own Task is set to COMPLETED on send and won't match status=requested.CommunicationRequest?, optional. Only needed if you care about thread lifecycle events (creation, revoked, completed) separately from messages. The proxy rewrites the criteria with participant=, so threads the team initiated are included.Criteria form:
Subscription.criteriais a FHIR search string. A criteria without parameters is written asTask?, the resource type followed by an empty parameter list. HAPI FHIR requires the?; a bareTaskis rejected with "must be in the form {Resource Type}?[params]". Earlier versions of this page usedTask?id,Communication?idandCommunicationRequest?id.idis not a search parameter (the resource id parameter is_id); HAPI only accepted that form because it drops parameters without a value. Replace it with the empty form.
In the Netherlands, healthcare data must not be pushed in subscription notifications. All subscriptions use the notify-then-pull pattern:
This means channel.payload must be left empty. The notification only signals that something matched the subscription criteria; the subscriber is responsible for fetching the actual data.
Each subscription serves a different purpose. Understanding when notifications fire is critical for correct client implementation:
| Subscription | Purpose | Required? | Fires when |
|---|---|---|---|
Task?status=requested |
Unread tracking and new-message notification for the team. Primary mechanism. | Required | Any change to the team's Task that matches status=requested. This includes status transitions to REQUESTED AND content changes (like focus) on a Task already REQUESTED. |
Communication? |
Visibility of messages sent by your own team members (the team's Task goes to COMPLETED). | Optional | A new Communication is created (POST). |
CommunicationRequest? |
Thread lifecycle changes (creation, revoked, completed). | Optional | A CommunicationRequest is created or its status changes. |
Important: When a new message arrives, the OZO FHIR Api updates the Task's
focusfield to reference the newCommunication. This ensuresTask?status=requestedfires even when the task was already in REQUESTED status: thefocuschange creates a new resource version. Thefocusfield also gives clients a direct pointer to the most recent unread message.This means
Task?status=requestedis a reliable single subscription for both unread tracking and new-message notification. The other two subscriptions are optional and only needed for specific edge cases.
A practitioner from Team A creates a new thread addressed to Team B. The process looks as follows:
CommunicationRequest object, the following fields are set:
requester is the Practitioner who initiates the conversation (for auditability)sender is the same Practitioner (individual sender)extension[senderCareTeam] is set to the CareTeam of Team A (initiating team, reply-to address). This must be an organizational CareTeam (no subject) the requester is a participant of; the AAA proxy rejects the CommunicationRequest otherwisesubject is the Patient referencerecipient lists the CareTeam of Team B. Team A should not be listed; a 0.8.x client that still lists it gets a validation warning in 0.9.0 (ozo-cr-sender-careteam-not-in-recipient) and an error from the next release, and the duplicate has no effectstatus is set to ACTIVEpayload contains the initial messageTask per thread party, here one per team:
owner is the CareTeamstatus is set to REQUESTED for Team B's Task and to COMPLETED for Team A's Task (the initiating team: the requester sent the message)intent is set to ORDERbasedOn is set to the CommunicationRequest referencefor is set to the Patient referencefocus is not set at thread creation (there is no initial Communication yet; the thread's initial message is on CommunicationRequest.payload)CommunicationRequest and Task by Subscription:
CommunicationRequest subscription notifies Team B of the new threadTask (status REQUESTED, owner Team B) marks the thread unread in Team B's shared inboxparticipant= and owner= with the team referenceA practitioner from Team B responds to the thread. Replies are not addressed individually: the Communication only references the thread, and the thread parties (recipient plus extension[senderCareTeam] of the CommunicationRequest) define who takes part.
Communication with the following fields:
partOf is set to the reference of the CommunicationRequestinResponseTo references the specific earlier Communication this message replies to (a quote-reply). The OZO thread model does not need it: the message belongs to the thread via partOf, and the OZO FHIR Api does not use inResponseTo for Task handling. Platforms without a reply-to-message concept leave it out.sender is set to the Practitioner from Team B (individual auditability)extension[senderCareTeam] is set to the CareTeam of Team B (the acting team). Required because the sender is a participant of an organizational team of the thread; the AAA proxy rejects the message with 422 when it names a team that is not a party of the thread or not one of the sender's teams. A missing extension is tolerated in 0.9.0 only (see the transition note above)payload consists of text and optionally attachmentsstatus is set to COMPLETEDrecipient is not set; thread parties are defined on the CommunicationRequest.CommunicationRequest and the acting team from extension[senderCareTeam] (here Team B). Then, for every party:
focus is updated to the new Communicationfocus is updated to the new Communication (ensures the subscription fires even when the status was already REQUESTED)status REQUESTED, intent ORDER, basedOn the CommunicationRequest, for the Patient, owner the party (the CareTeam for a team, the person otherwise) and focus the new CommunicationTask?status=requested subscription fires once for Team A: the team's Task moved to REQUESTED and focus points to the new Communication, which creates a new version even when the status was already REQUESTED.A different practitioner from Team A follows up on the thread. This demonstrates that any team member can participate in the conversation.
Communication with the following fields:
partOf is set to the reference of the CommunicationRequestinResponseTo is optional, as abovesender is set to the different Practitioner from Team A (individual auditability; note this is a different person than the original requester)extension[senderCareTeam] is set to the CareTeam of Team Apayload consists of text and optionally attachmentsstatus is set to COMPLETEDfocus on the new messagefocus on the new message (a colleague answered)When a practitioner reads a message in a team thread:
AuditEvent (a read receipt) with the following properties:
type is set to http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle|access. This is the only type the OZO FHIR Api treats as a read receipt; the REST audit events the proxy creates itself use type rest and are ignored here. See Manu-Read-Team-Thread and Pieter-Read-Team-Thread for examples.action is set to 'R'recorded field is set to the current timestampagent.who field is set to the Practitioner who read the messageagent.extension[careTeam] is set to the CareTeam on whose behalf the message was read (the acting team). Required because the reader is a participant of an organizational team of the thread; the AAA proxy rejects the receipt with 422 when it names a team that is not a party of the thread or not one of the reader's teams. A missing extension is tolerated in 0.9.0 only (see the transition note above)entity entries, each with one what (the profile allows entity 0..* and entity.what 0..1):
CommunicationRequest. Required: the OZO FHIR Api looks up the team's Task with Task?based-on=<CommunicationRequest>&owner=<CareTeam>; without this entry the read receipt is ignored.Communication that was read. Optional but recommended: the OZO FHIR Api only completes the Task when this is the newest message in the thread, so reading an older message does not clear a newer unread one; without this entry the thread is marked read unconditionally. It also records for the NEN7510 audit trail which message was viewed. At thread creation there is no Communication yet; a receipt for the initial message carries the CommunicationRequest entity only.Task owned by the CareTeam in agent.extension[careTeam] is queried and its status is set to COMPLETEDCareTeam. The AuditEvent records which person read it.Note: "Mark as unread" is not part of the OZO messaging model. The read state lives in the
Task(requested= unread,completed= read) and only the OZO FHIR Api changes it: on a read receipt, on a new message, and at thread creation. Clients have read-only access toTask, and there is no AuditEvent type that sets a Task back torequested. A platform that offers "mark as unread" keeps that state locally; it is not visible to other systems or, in team threads, to other team members.
The diagram below displays the team-to-team messaging flow, including thread creation and responses from both teams. {::nomarkdown}
{:/}
The following walkthrough shows a concrete example with Apotheek de Pil (Pharmacy A: A.P. Otheeker, Pieter de Vries) and Huisarts Amsterdam (Clinic B: Manu van Weel, Mark Benson, Johan van den Berg). It shows the 0.9.0 team-Task mode: the thread has two Tasks throughout, one per team. A server still in the 0.8.x per-member mode creates five Tasks and fans reads out to the team members, as documented up to 0.8.4.
A pharmacist (A.P. Otheeker) from Apotheek de Pil sends a message to Huisarts Amsterdam about a patient's medication; see Pharmacy-to-Clinic for the full CommunicationRequest. recipient lists Clinic-B, the addressed team; extension[senderCareTeam] references Pharmacy-A, the initiating team.
The OZO FHIR Api creates one Task per team:
requestedcompleted (initiating team)Notifications fired:
CommunicationRequest subscription → both teams notified of the new thread (the proxy rewrites the criteria with participant=, which matches Pharmacy A through the extension)Task?status=requested subscription → Clinic B notified of the unread thread, once, through the team's TaskDr. Manu van Weel from the clinic reads the message. The OZO platform creates a read receipt AuditEvent with type iso-21089-lifecycle|access, agent.who Manu and agent.extension[careTeam] Clinic B; see Manu-Read-Team-Thread. There is no Communication yet, so the receipt references the CommunicationRequest only.
The OZO FHIR Api completes the Task of the named team:
completed (was: requested). The message is now read for Mark Benson and Johan van den Berg as well; the AuditEvent records that Manu read it.Manu then replies with a Communication whose partOf points to the thread and whose extension[senderCareTeam] names Clinic B; see Clinic-Response-to-Pharmacy for the full resource.
The OZO FHIR Api updates both Tasks:
requested, focus → new Communicationcompleted (acting team), focus → new CommunicationNotifications fired:
Communication subscription → Pharmacy A notified of the new messageTask?status=requested subscription → Pharmacy A notified of the unread message, onceA.P. Otheeker has not seen the reply yet. Pieter de Vries opens it; the OZO platform creates a read receipt with agent.who Pieter, agent.extension[careTeam] Pharmacy A and two entities, the thread and the Communication that was read; see Pieter-Read-Team-Thread. The Communication is the newest message in the thread, so the OZO FHIR Api completes the Task:
completed (was: requested). Read for the whole team, including Otheeker.Pieter then responds, demonstrating that any team member can participate; see Pharmacy-Followup-by-Pieter for the full Communication. extension[senderCareTeam] names Pharmacy A.
The OZO FHIR Api updates both Tasks:
requested (was: completed), focus → new Communicationcompleted (acting team), focus → new CommunicationNotifications fired:
Communication subscription → Clinic B notified of new message (always fires)Task?status=requested subscription → Clinic B notified, once (status changed from COMPLETED to REQUESTED AND focus updated to the new Communication)Note: Even if Clinic B had not yet read the previous message (Task still REQUESTED), the
focusupdate would still create a new Task version and fire the subscription. Thefocusfield eliminates the no-op scenario.
Two Tasks per thread instead of five, and no inference of the team at any step.
Communication links to its thread via partOf, so thread searches use the part-of search parameter. based-on is a different element and is not used in the OZO messaging model.
Find messages for my team (via thread membership):
GET /Communication?part-of:CommunicationRequest.participant=CareTeam/Pharmacy-A
The AAA proxy applies this filter automatically for client access, so a plain GET /Communication returns the same result for a team member. participant matches threads the team is addressed in and threads it initiated. _include is blocked for clients by the proxy; system access can add &_include=Communication:part-of to fetch the threads in the same call.
Find all messages in a thread:
GET /Communication?part-of=CommunicationRequest/thread-id&_sort=sent
Find messages I sent:
GET /Communication?sender=Practitioner/my-id
Find messages sent on behalf of my team:
GET /Communication?part-of:CommunicationRequest.participant=CareTeam/Pharmacy-A&sender=Practitioner/a,Practitioner/b
There is no search parameter on Communication.extension[senderCareTeam]; filter on the team's members or on the extension client-side.
Find all threads my team takes part in:
GET /CommunicationRequest?participant=CareTeam/Pharmacy-A
participant is a custom search parameter defined by this IG with a union expression over recipient and extension[senderCareTeam]; see ozo-communicationrequest-participant.
Find threads addressed to my team:
GET /CommunicationRequest?recipient=CareTeam/Pharmacy-A
Find threads initiated by my team:
GET /CommunicationRequest?sender-careteam=CareTeam/Pharmacy-A
sender-careteam is a custom search parameter defined by this IG on extension[senderCareTeam]; see ozo-communicationrequest-sender-careteam. The HAPI FHIR server needs the OZO package installed and existing threads reindexed once for both custom parameters; see Installing OZO Package in HAPI FHIR Server.
Shared inbox: unread threads of my team:
GET /Task?owner=CareTeam/Pharmacy-A&status=requested
Task.owner tells the platform which team inbox a Task belongs to. A practitioner in two teams gets one Task per team for the same thread.
completed)extension[senderCareTeam] = Clinic Bextension[senderCareTeam] = Pharmacy ACommunicationRequest?participant= finds threads a party takes part in, addressed or initiatingCommunicationRequest?sender-careteam= finds threads initiated by a teamFor detailed analysis of the addressing solution, see FHIR Addressing Analysis. For the design discussion behind the 0.9.0 model, see RFC - Team Messaging Model.