Recently, I wrote about the benefits of the HL7® FHIR® industry standard. After participating in the FHIR DevDays, where I experienced the vivid developer community centered around this important topic, I wanted to publish my follow-up post. This blog post will be a practical how-to tutorial on using FHIR on the SAP Business Technology Platform. The new cloud-native service SAP Health Data Services for FHIR, currently available as part of an open beta to our partners and SAP BTP customers, plays a crucial role in this tutorial.
Are you asking yourself at this point one of the following questions: Why is FHIR a vital standard for SAP? Why does it matter for healthcare provider organizations? What is in for SAP partners? If so, I can recommend reading the following blog posts:
During its beta phase, you can try the new SAP Health Data Services for FHIR. In addition to the service, we have published a mission in the SAP Discovery Center, which can be one approach to learning more about the service and potentially realize other use cases.
But now, let’s go into the practical usage of FHIR with the SAP Business Technology Platform. The most straightforward approach to interacting with the service is leveraging the REST API, which most FHIR servers usually provide. Below I will explain in detail how to access and use the REST API of SAP Health Data Services for FHIR using two different tools. To simplify things, we just want to create a “Patient” with the first tool and then access it later with the second.
FHIR REST Client
While various REST Clients are available, I prefer to use Visual Studio Code, as it’s very transparent about what happens.
To perform the subsequent steps, you need to get the following tools:
As you might know, Visual Studio Code is a code editor. The REST Client mentioned above allows you to associate with it and then execute calls directly from the editor via the “Send request” command. Additionally, you can define variables and use them throughout subsequent calls.
To continue, you will need a configured instance of the SAP Health Data Services for FHIR (Beta). Please follow the steps outlined in the documentation to create the instance. Then we need the service key file from the SAP Health Data Service for FHIR (Beta). The contents of the service key file are described here in detail. We will only need the following contents. From the “endpoint” section, we will need the URL of the “coreservice”. And from the “uaa” section, we will need the “url” to authenticate against, the “clientid” and the “clientsecret”.
The security functionality of SAP BTP is based on the OAuth 2.0 specification. Specifically, the User Account and Authentication (UAA) component is the central infrastructure component of the runtime platform for, e.g., authentication. The following text fragment will perform the OAuth authentication using the services’ client credentials and store the corresponding token for subsequent requests.
@url_auth=<uaa_url>
@clientId=<uaa_clientid>
@clientSecret=<uaa_clientsecret>
@url_core=<url_coreservice>
# @name get_token
GET {{url_auth}}/oauth/token?grant_type=client_credentials
Authorization: Basic {{clientId}} {{clientSecret}}
###
@authToken = {{get_token.response.body.access_token}}Please read the documentation of the REST Client for the overall syntax. It’s surprisingly easy. The three hashtags “###” separate requests, and the @name tag helps to associate the response to some context.
Visual Studio Code then adds a small text “Send Request” after the “@name” section, which allows you to execute this when you click on it. After the three dashes, the next line assigns the access token to a variable, so we can use this when executing our requests.
When we are this far, we can execute our first FHIR request and create a patient with the following fragment:
# @name create_patient
POST {{url_core}}/Patient
Content-Type: application/json
Authorization: Bearer {{authToken}}
{
"resourceType": "Patient",
"identifier": [
{
"use": "official",
"system": "http://example.org/fhir/Patient",
"value": "t-1"
}
],
"active": true,
"name": [
{
"use": "official",
"text": "John Putz",
"family": "Putz",
"given": [
"John"
]
}
],
"gender": "male",
"birthDate": "1970-07-30"
}
###After executing the request, a “Response” window opens, where I can see the result. You can copy the “response content” in another editor window, e.g., use the FHIR tools to query, manipulate, validate, and so on.
Similarly, I can now also query the FHIR service for resources, e.g., by executing the following lines, I can retrieve the Patient again:
# @name get_patient_by_identifier
GET {{url_core}}/Patient?identifier=t-1
Authorization: Bearer {{authToken}}Please have a look at the recording showing the steps I just described here:
If you are interested in additional capabilities of the FHIR REST API, watch out for the step “Try out the FHIR API and work with SAP Health Data Services for FHIR” in the abovementioned mission. You can find examples of how to work with conformance, patient, and terminology resources.
Firely Terminal
Let’s conclude our tour using the Firely Terminal command line tool from Firely. We will first need to authenticate again using the client credentials of the SAP Health Data Services for FHIR. One approach to accomplish this in the command line is to use the CloudFoundry UAA Command Line Client. Naturally, this command line tool supports OAuth 2.0 natively.
To retrieve the patient data you created above, please execute the following steps in the command line terminal. I used macOS and the standard shell (zsh) in this example. It should be easy to adapt it to the Windows command line. Remember to replace the brackets, e.g., <url_auth>, with the information you get from your service key.
Step 1: Configure
uaac target <url_auth> --basic_auth
fhir server add hdsf <url_core>
Step 2: Get the access token and add it to the header
uaac token client get '<uua_clientid>' -s '<uaa_clientsecret>'
ACCESS_TOKEN=$(uaac context | awk '/^ *access_token: / {print $2}')
fhir server remove-headers hdsf
fhir server header hdsf Authorization "Bearer $ACCESS_TOKEN"
Step 3: Work with the FHIR Terminal
fhir search hdsf Patient given=John
fhir show
The “fhir search” command finally executes the FHIR GET request against our configured FHIR service and stores the results in a stack. The “fhir show” command retrieves the contents from the stack and shows it. And, magically, you will get back the Patient, we’ve created above.
Here you can find the recording demonstrating the usage of these tools:
Please see the documentation of the Firely Terminal to find out what else you can do with it.
Conclusion
This blog post should give you a better understanding of how you can leverage FHIR to fulfill many use cases. This post focused on using a basic editor or a command line tool. Do you instead want to use a low-code/no-code solution as a basis to create an application? This is a great idea, and you can either get started or wait a couple of days and read more in a subsequent blog post.
If you have further questions about potential use cases you can realize using the SAP Health Data Services for FHIR (beta), please look at the links linked above or comment on this post! Thank you!
