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

Connecting using a FHIR API Client

Client types

We support 2 different types of clients to access our FHIR APIs:

• Data centered client: This client can be used to invite participants to programs (PlanDefinitions) and retrieve (encrypted) participant’s responses.
• Person centered client: This client can be used to display the available programs for a user, show the questionnaires to the user, and capture the participant’s responses.

In the following sections we’ll show the following icons for the different types of client that could use that API:

• Data centered:
• Person centered:

Data Centered Client

Data centered clients are mainly used to invite participants for a program created in the Form Designer and to retrieve the (encrypted) responses to the questionnaires.

After setting up accounts and clients the standard flow for a data centered client is:

The data centered client starts with inviting a participant by creating a CarePlan. Once the participant is registered for this program, he can fill out the questionnaires in a form filler.

The next step is retrieving the QuestionnaireResponse for a participant. This can be done by polling for new responses, but the preferred way is using Subscriptions to get notified about new responses.

Once the responses are retrieved, they need to be decrypted to read the actual answers given by the participant.

Person Centered Client

Person centered clients are used to present the programs and questionnaires to the participant and capture the responses of the participant.

After setting-up accounts and clients the standard flow for a person centered client is:

The person centered client might start with retrieving all CarePlans for a participant. The CarePlan contains all tasks the participant should complete for this specific program. For every task there is a Questionnaire that the participant should fill out.

After the participant has filled out the Questionnaire, the person centered client should have a complete QuestionnaireResponse with all the given answers. To provide this response to the Open Health Hub FHIR API, the response should be encrypted. For encrypting, the client will need the public keys of the participants in the program. These can be retrieved as part of the CarePlan, as part of a CareTeam, or as a list of Practitioners.

Once the QuestionnaireResponse is encrypted, the client needs to send a Bundle of QuestionnaireResponses (one response per public key/participant), to the Open Health Hub FHIR API. This will fulfill the task of the CarePlan, optionally triggering new tasks.

Get started with your client

You can use the Open Health Hub FHIR APIs to access the Open Health Hub Platform to interact with questionnaires, forms, and information.

Step 1. Play and learn

Get familiar with our FHIR REST APIs and FHIR Client Example Repository. You can play with our sandbox with the listed credentials.

Learn more about FHIR via the following links:

• HL7 FHIR documentation
• Learn HL7 FHIR
• HL7 FHIR wiki

Our Postman Collection offers a great start at discovering our FHIR REST APIs in a sandbox environment. It is pre-configured with the sandbox credentials (api-key, openid credentials), so you can start right away:

• click on the collection “Open Health Hub FHIR APIs” on the left.
• click on the tab “Authorization”
• click on the button “Get New Access Token” at the bottom of the page

Now you can start making requests and view the results in the console.

Step 2. Get Credentials

To generate FHIR API credentials for the live environment:

1. Request for an Open Health Hub API developer account.
2. We will send your credentials.
3. You can start using your credentials.
4. Replace the sandbox credentials with your credentials.
5. Replace the sandbox URL with the live URL.

For more information about authentication, see the section below.

Step 3. Get an Open Health Hub account

You can design your own questionnaires and participant instructions which you can use for your app project using the Open Health Hub Form Designer.

1. Register your own Form Designer account or deliver your API key to one of your colleagues who already has an Improve Designer account.
2. Use the program credentials for your app project.

Step 4. Start your integration

Start building your own App project using this documentation and our example FHIR Client Example Repository.

Authentication

Open Health Hub uses API keys and OpenID Connect to allow access to the FHIR API. After getting an account, you or one of your colleagues can get the API Key from the Open Health Hub Manager.

The Open Health Hub FHIR API expects the API key and OpenID Connect access token to be included in all API requests to the server in a header, or as a request parameter on the url.

For the sandbox environment this looks as follows:

• API Key:
  • A header: X-API-KEY: ad880601-b7e6-4d86-901d-b6fca96fc725
  • As url parameter: https://api.openhealthhub.com/OpenHealthhub/fhir/4/CarePlan/1?apikey=ad880601-b7e6-4d86-901d-b6fca96fc725
• Access token header: Authorization: Bearer <access_token_retrieved_from_oidc_server>

You can retrieve the access token header from the token endpoint using the fields below. In some cases the language’s FHIR library will take care of this. You’ll need to set these values in your code then.

• Access token endpoint: https://auth.openhealthhub.com/auth/realms/OpenHealthHub/protocol/openid-connect/token
• OpenID Connect client_id: api-sandbox
• OpenID Connect client_secret: 95810e52-4307-41f5-99a4-d873ab63b536
• OpenID Connect grant_type: client_credentials