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

Overview — FHIR and inviting patients

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.

FHIR in a nutshell

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.

Reading this implementation guide

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:

  • a Content tab that starts with the Scope and Usage of the resource in Open Health Hub, followed by the formal views of the profile and notes on how to use the resource;
  • formal views, tables that list the elements of the resource with their cardinality (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;
  • Examples of the resource as JSON, XML or Turtle.

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.

Inviting a patient to a program

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.

  1. Find the program. 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>.
  2. Invite the patient. Create a CarePlan with POST [base]/CarePlan, see Create CarePlan. The CarePlan refers to the program in instantiatesCanonical, and contains:
    • the patient (subject), as a contained Patient with at least a patient identifier and an email address;
    • the date the program starts for the patient (period.start);
    • optionally the care provider that invites the patient (author);
    • optionally the caregivers of the patient for the caregiver roles of the program, as a contained CareTeam (careTeam);
    • optionally a contained Task (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.

  3. The tasks are planned. The patient is registered to the program right away, and the CarePlan has the status 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.
  4. The questionnaires are filled out. Once a task has started, the patient or caregiver fills out the questionnaire in the Open Health Hub form filler, using the link in the 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.
  5. Retrieve the responses. Create a Subscription on QuestionnaireResponse to be notified of new responses, or search them with 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.
  6. Manage the invite. Until the patient has completed a questionnaire, 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:

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.