Open Health Hub FHIR Implementation Guide
0.1.0 - v0.1.0
Open Health Hub FHIR Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
This page is the place to start if you are new to FHIR or to Open Health Hub. It explains the FHIR basics you need to read this implementation guide, shows which resources are involved when you invite a patient to a program, and links to the parts of the FHIR specification that are worth reading first.
HL7 FHIR is a standard for exchanging healthcare information. The information is exchanged as resources:
small, self-contained JSON or XML documents such as a Patient, a Questionnaire or a CarePlan. Every resource type has a fixed set of
elements, and resources point to each other with references. A resource that only exists as part of another resource is contained in
it, and is referenced with a # followed by its id, for example #patient. Resources are read, searched, created, updated and deleted
with a REST API per resource type, for example GET [base]/CarePlan/123 or POST [base]/CarePlan.
Open Health Hub uses FHIR R4 (4.0.1). The Open Health Hub FHIR API is not a general purpose FHIR server: it translates FHIR requests into requests to the Open Health Hub Platform, and only supports the resources, interactions and search parameters listed in the CapabilityStatement.
An implementation guide profiles the standard FHIR resources: a profile describes which elements are used, which are required and what they mean in a specific context. Every profile page in this guide has:
0..1 is optional, 1..1 is required, 0..*
can repeat), their data type and a description in the Open Health Hub context. The Key Elements Table is the best place to start.
Elements flagged with S (Must Support) are the elements Open Health Hub sets or reads. See
how to read the tables for an explanation of the columns and flags;Elements of a resource that are not described in this guide are not used by Open Health Hub, and are ignored when you send them. Extensions defined by Open Health Hub carry information that has no standard FHIR element, such as the links to the embedded form filler.
In Open Health Hub a care provider invites a patient to a program. A program is designed in the Open Health Hub Form Designer. It consists of questionnaires, forms and information modules that the patient, and possibly caregivers of the patient, fill out according to a schedule, together with the reminders and call tasks that go with them.
The steps below show the order in which a data centered client uses the resources, once it has been set up as described in Get started with your client, including the key pair to decrypt the responses. See Open Health Hub — FHIR Mappings for the relation between the Open Health Hub terminology and the FHIR resources.
GET [base]/PlanDefinition lists the programs your client can use, GET [base]/PlanDefinition/<id> returns a
single program. Every action of the PlanDefinition is a questionnaire, form or information module of the program: action.definition
refers to the Questionnaire, action.participant tells who fills it out, and action.timing or action.relatedAction tells when it
starts. If you want to know the questions and their codes in advance, retrieve the Questionnaires with GET [base]/Questionnaire/<id>.POST [base]/CarePlan, see
Create CarePlan. The CarePlan refers to the program in instantiatesCanonical, and
contains:
subject), as a contained Patient with at least a patient identifier and an email address;period.start);author);careTeam);activity.reference) with the actions Open Health Hub should perform for the invite, such as sending
the invitation mail.The response is the created CarePlan as described in Retrieve CarePlan. Its id is
the id of the invite, and its form-filler-program-timeline extension contains the link to the program of the patient in the embedded
form filler.
active. Open Health
Hub plans the questionnaire tasks and
reminders and calls according to the schedule of the program. They are listed as
activity in the CarePlan and can be retrieved as Task. A Subscription on CarePlan or Task
notifies you about these changes.form-filler-program-task extension of the CarePlan activity, or in a
person centered client. Submitting the questionnaire completes the task and creates the
QuestionnaireResponse, with the answers encrypted for the care providers of
the program. Reminders and calls are sent or created at the moments defined in the program, as long as the questionnaire has not been
completed.GET [base]/QuestionnaireResponse?based-on=CarePlan/<id>.
Decrypt the answers with your private key,
and use the Questionnaire the response refers to (questionnaire) to interpret them. When you retrieve the responses through the
Open Health Hub FHIR Viewer Gateway, the gateway decrypts them, so you don't have to decrypt them yourself.PUT [base]/CarePlan/<id> updates the patient details, the
start date and the status of the reminders, see Update CarePlan.
PUT [base]/Task/<id> cancels or reactivates a reminder, or completes a call task, see
OHH Participant Task. DELETE [base]/CarePlan/<id> revokes the invite. The CarePlan
gets the status completed once all its tasks are completed.Answers are always encrypted. Your client can only read them with the private key of its key pair. The FHIR Client Example Repository shows how to encrypt and decrypt responses in several programming languages.
The FHIR specification is large. These pages of the FHIR R4 specification are the most relevant for this implementation guide:
_include, _count and paging;dateTime, Identifier, Reference and CodeableConcept;To learn FHIR step by step, see Learn HL7 FHIR or the HL7 FHIR wiki. When building a client, use an existing FHIR library such as HAPI FHIR for Java or the Firely .NET SDK for C#, see Connecting using a FHIR API Client.