Introduction
| Excerpt |
|---|
This guide walks you through the process of creating a simple JavaScript app for a healthcare provider (doctor, nurse, pharmacist, etc.) that is launched from an EHR (HSPC Sandbox) and queries the Bilirubin Observations for the patient in the EHR context. |
This simple JavaScript app is a great starter project from which you can begin to add your business logic and user interface.
Prerequisites
- In order to launch the starter app, you will need an account on the HSPC Sandbox.
- (Optional) Familiarity with the SMART on FHIR specification
What you will build
In this guide, you will build a simple JavaScript app that consists of two HTML files. If you prefer, you can skip the steps in the guide and download a finished copy of the project.
What you will need
- A Web Server. This guide will use Apache Tomcat. Please see our guides for AWS, Apache, and Tomcat.
- Your IP Address or hostname.
- An IDE or text editor.
Step 1: Create a Simple Launch File
When your app is used in production, it will be made available within the EHR as a link or a button. The healthcare provider will choose a patient then select your app. The EHR will send a launch request to tell your app that it is being launched. The launch message will include information such as the address of the EHR resource server and the patient in the EHR context.
Create the following launch.html file on your filesystem:
...
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<script src="https://apps.hspconsortium.org/hspc-reference-apps/static/jsfiddle/fhir-client.js"></script>
<script>
FHIR.oauth2.authorize({
client_id: "my_web_app",
scope: "patient/*.read"
});
</script>
</head>
<body>
Launching...
</body>
</html>
As you can see, when the launch page is requested, it will use the SMART on FHIR client library to authorize the app. In this example, we will be using the client existing "my_web_app". When you register your app with the HSPC Sandbox, you will be issued a new client id. It is likely that each EHR system will issue your app a client id within that EHR.
Step 2: Create a Simple App File
When your app completes the authorization protocol (from the launch.html page), the EHR will send a request to a "redirect" address. This redirect address is typically the entry point to your app. In this guide, this will be our index.html file.
Create the following index.html file on your filesystem:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<html>
<head>
<script src="https://apps.hspconsortium.org/hspc-reference-apps/static/jsfiddle/fhir-client.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
<style>
table, th, td {
border: 1px solid black;
border-collapse: collapse;
}
th, td {
padding: 5px;
text-align: left;
}
</style>
</head>
<body>
<script type="text/javascript">
FHIR.oauth2.ready(function (fhirClient) {
var patient = fhirClient.patient;
$.when(patient.read())
.done(function (p) {
var name = p.name[0];
var formattedName = name.given[0] + " " + name.family;
$("#patientName").text(formattedName);
});
$.when(patient.api.search({type: "Observation", query: {code: 'http://loinc.org|58941-6'}, count: 50}))
.done(function (obsSearchResults) {
obsSearchResults.data.entry.forEach(function (obs) {
var obsRow = "<tr><td>" + obs.resource.effectiveDateTime + "</td>" + "<td>" +
obs.resource.valueQuantity.value + obs.resource.valueQuantity.unit + "</td></tr>"
$("#obsTable").append(obsRow);
});
});
});
</script>
<h2 id="patientName"></h2>
<table id="obsTable">
<tr>
<th>Date</th>
<th>Value</th>
</tr>
</table>
</body>
</html> |
As you can see, the app is again using the SMART on FHIR client library. The app first uses the FHIR.oauth2.ready method to compete the authorization process. When the process is completed, the app will get the patient from the SMART context, look up the patient demographics, and query for Bilirubin (http://loinc.org|58941-6) observations. The app will display these values in a table.
Step 3: Try it out
We will run this app using a two-step process.
- Host this app on a web server.
If you host on a server running locally, get the hostname of your machine. The app needs to be accessible from the HSPC Sandbox. If you are using Apache Tomcat, copy the "fhir-app" folder to the tomcat webapps folder. Start up Tomcat. - Use the HSPC Sandbox to launch your app.
- Log into the HSPC Sandbox. If you don't have an HSPC Sandbox account, create one now. Refer to the HSPC Sandbox reference for details.
- Create a launch scenario to launch your app. See the Sandbox Launch Scenarios reference for details.
- Practitioner: Any
- Patient: Daniel Adams
- App ID: my_web_app
- Launch URL: [your app host address and context]/launch.html
* ex: http://example.com/fhir-app/launch.html - (Optional) Save your scenario
- Launch Your App
- Complete the Authorization Flow
- At this point, you have asked the EHR (HSPC Sandbox) to launch the app "My Web App" for the provider and the patient Baby Bili. The EHR (HSPC Sandbox) has sent a launch request to your hosted launch.html. The launch.html has initiated the FHIR.oauth2.authorize for the client my_web_app with a scope of "patient/*.read".
- Allow the app to proceed (gain access to the EHR's data on your behalf) by selecting "Authorize".
- Enter the app
Upon authorization, the EHR redirects to the index.html with an OAuth2 access token your app can then use to query data from the EHR.
4. Register your App within your Sandbox
To obtain your own client id (instead of "my_web_app" above), register your app with the HSPC Sandbox. See Register Your App in the HSPC Sandbox for details.
Where to go from here
Now you have a fully operational SMART on FHIR app that does launch, scopes, authentication, and querying. Continue to build out your app logic and user interface using this starter project or merge these same techniques into your existing codebase.
See Also
Use the fhir-client.js in a Multi-page Architecture
Get the Source Code
GitHub
...
The following JavaScript sample applications are available: