2. FHIR IG
2.1. Introduction
This Technical Design (TD) describes the technical implementation of the ProviderTasks (Aanbiedertaken) based on the Functional Design (FD). The TD is the technical counterpart of the FD and describes: • the involved actors and systems; • the FHIR profiles and resources to be used; • the transactions (search/retrieve/update) including example queries; • the workflow relationships between definitions, orders/requests, and workflow items.
The FHIR version used for this IG is HL7 FHIR R4 (4.0.1). Infrastructure, security, authentication and authorization are governed by the MedMij framework and are not re-specified in this TD. (link naar changemanagement)
2.2. Workflow model (FHIR Workflow)
ProviderTasks follows the FHIR workflow approach where resources are grouped into Definitions, Requests, and Events:
- Definitions: reusable definitions of digital activities (e.g., ActivityDefinition, Questionnaire)
- Requests: patient-specific “orders/requests” that something should be done (e.g., ServiceRequest, Task)
- Events: the execution/results (e.g., Observation, Procedure, QuestionnaireResponse). This is out of scope in this TD version. Focus is on tasks workflow only.
FHIR explicitly describes these categories (definitions/requests/events) and their relationships (e.g., requests referencing definitions, events referencing orders, parent-child relationships).
2.2.1. Relationships in ProviderTasks
- ActivityDefinition (Definition) describes the digital activity (e.g., a launchable module or informational content) and contains generic, reusable information about what the digital activity is and how it should be used, including the technical launch information via Endpoint.
- ServiceRequest (Request) is the patient-specific clinical order to perform the digital activity, including scheduling (occurrence) and patient instructions (patientInstruction). It can also carry patient-specific instructions that override or complement the generic guidance in the ActivityDefinition.
- Task (Request) is the actionable workflow item shown to and performed by the patient (status/owner/partOf/groupIdentifier).
- Event resources (out of scope): Observations/QuestionnaireResponse/etc. resulting from execution (not specified here).
2.3. Actors involved
| Actor | System | FHIR CapabilityStatement | |||
|---|---|---|---|---|---|
| Name | Description | Name | Description | Name | Description |
| Patient | User who performs the digital activity | PHR | Personal health record | [TO DO] | FHIR client requirements |
| Healthcare provider | User who initiates the digtial activity | source system | Healthcare information system | [TO DO] | FHIR server requirements |
| Module system | System that delivers the digital activity | modul system | Healthcare information system | [TO DO] | FHIR server requirements |
2.4. Boundaries and relationships
This FHIR IG covers use cases for exchanging task data between healthcare providers and patients (typically through a PHR).
This IG guide assumes that a PHR is able to connect with a source system. It does not provide information on finding the right source system nor does it provide information about security. These infrastructure and interface specifications are described in the MedMij Afsprakenstelsel.
Out of scope for this TD version:
- Exchange of clinical results produced by the activity (events).
2.5. Use cases
2.5.1. Overview
The healthcare provider initiates a digital activity for the patient. The patient retrieves the task list in the PHR, starts (launches) the digital activity, performs it in an external application/module, and then sees task status updates in the PHR.
2.5.2. Transactions
- PULL task list (PGO → source system): retrieve Task , including the links to the ActivityDefinition (instantiates extension), and basedOn links to ServiceRequest (if used).
- LAUNCH (PGO → module system): start external module using information from ActivityDefinition and Endpoint (launch outside core REST exchange).
- UPDATE status (Module system → source system): update Task.status for both main tasks and subtasks to reflect progress and completion.
2.5.3. Use case: Provider Module
2.5.4. Dataset and conformance
The dataset is specified in the Logical Models:
- LogicalModel Task
- LogicalModel ActivityDefinition
- LogicalModel ServiceRequest
- LogicalModel Endpoint
Test material (fixtures) and example instances are published separately as test artifacts in the Implementation Guide.
2.5.4.1. PHR: request message
The PHR system requests task data using individual search interactions. The task data exchange consists of multiple FHIR resources with specific constraints. These interactions are performed using an HTTP GET as shown below:
GET [base]/[type]{?[parameters]}
To update the '.status of an existing Task (e.g., after launching or completing an activity), the Module system updates the Task resource on the source system using an HTTP PUT.
PUT [base]/Task/[id]
2.5.4.2. Retreive task list (PGO → Source System)
Goal: the patient retrieves both open and completed tasks, along with the related context required to display the task list and support launching the associated digital activity.
Response:
- A Bundle containing Task resource(s) conforming to the ProviderTasks-Task profile, including:
- the referenced basedOn ServiceRequest (if present);
- any subtasks linked via partOf (if present).
2.5.4.3. Update Task status (Module system → Source System)
Goal: Write back progress/completion after the patient interacted with the activity (including after returning from the external module).
2.5.4.4. Launch (PGO → module system)
The launch is based on information in ActivityDefinition and Endpoint (e.g., endpoint.address). In the ProviderTasks this is the step where the PHR starts an external module/application.
The launch is an interaction outside the core REST data exchange and is based on SMART App Launch. The specifications can be found in the ()
2.5.4.5. Workflow relationships and grouping
Link to Modules (ActivityDefinition):
- The Tasks (main task and subtasks) contain a link to ActivityDefinition that defines the launchable digital activity (what should be launched or performed).
- The ActivityDefinition references one or more Endpoint(s) that expose the activity and provide the technical access/launch details.
Main task and subtasks:
- If subtasks are used, there is always a main (parent) task representing the overall activity/module.
- Subtasks reference the main task via Task.partOf.
- Subtasks are only used for repeating tasks of a single digital activity (one ActivityDefinition). Therefore, subtasks linked via Task.partOf SHALL NOT reference a different ActivityDefinition than their main task.
- Grouping of tasks within a single digital care module can be done using Task.groupIdentifier.
Link to order (ServiceRequest)
- A Task can reference the originating ServiceRequest via Task.basedOn.
- The ServiceRequest represents the clinical order for the digital activity and may include:
- the patient-specific requested schedule (occurrence);
- patient-specific instructions (patientInstruction).
2.5.4.6. Source system: example queries
The returned data to the PHR should conform to the profiles listed in the table below. The table below shows in the first four columns the provider module sections, the HCIMs that constitute those sections and the specific content of the provider module specific information. The last column shows the FHIR search queries to obtain the Provider Module information. These queries and expected responses are based on profiles listed in the functional design.
| Section | CIM NL | HCIM EN | FHIR Profile | Search URL |
|---|---|---|---|---|
| 1 | Patiënt | Patient | nl-core-Patient | GET [base]/Patient |
| 2 | Taak | Task | pt-Task | GET [base]/Task |
| 3 | Digitale activiteit | ActivityDefinition | pt-ActivityDefinition | See Task |
| 4 | Zorgopdracht | ServiceRequest | pt-ServiceRequest | See Task |
| 5 | Endpoint | Endpoint | pt-Endpoint | See ActivityDefinition |
| 6 | Taak | Task | pt-Task | PATCH [base]/Task/[id] |
| 7 | Zorgaanbieder | HealthcareProvider | nl-core-HealthcareProvider nl-core-HealthcareProvider-Organization | See PractitionerRole |
| 8 | Zorgverlener | HealthProfessional | nl-core-HealthProfessional-Practitioner nl-core-HealthProfessional-PractitionerRole | See Task and ServiceRequest |
2.5.4.7. Configuration search query Task
The PHR may use and the source system shall be capable of processing the minimal requirements outlined in the FHIR R4 IG 2.7.1.1 Search on date, number or quantity. Example query:
For ProviderTasks, the most common use is retrieving open tasks. Retrieve all non-completed tasks for the patient context: GET [base]/Task?status:not=completed