Skip to content

Dev #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smalho01 merged 4 commits into from
Jul 1, 2024
Merged

Dev #74

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b61da8c
readme updates
KeeyanGhoreshi Jun 18, 2024
d9015b9
minor change
KeeyanGhoreshi Jun 18, 2024
8719cc6
Merge pull request #73 from mcode/update_readme
smalho01 Jun 21, 2024
ca9a57f
Merge branch 'main' into dev
smalho01 Jul 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 29 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,25 @@
# EHR FHIR Server
# REMS EHR FHIR Server

This sub-project hosts a HAPI FHIR server that is based on the now-deprecated [hapi-fhir-jpaserver-example](https://github.com/jamesagnew/hapi-fhir/tree/master/hapi-fhir-jpaserver-example). The new repo is found [here](https://github.com/hapifhir/hapi-fhir-jpaserver-starter).

## Running the server
The server this repository runs is a standard FHIR server that saves and provides FHIR resources for clients. Almost every step of the REMS workflow involves the EHR, it communicates with the [Request Generator](https://github.com/mcode/request-generator), [REMS Admin](https://github.com/mcode/rems-admin), [REMS SMART on FHIR app](https://github.com/mcode/rems-smart-on-fhir), and [Pharmacy System](https://github.com/mcode/pims).

1. Make sure `gradle` is installed on your machine. Gradle v6.9 or higher.
2. Run `gradle bootRun`
3. In a separate terminal tab, run `gradle loadData` to load resources
Any compliant FHIR server can replace this server in the workflow. This EHR server is provided as a convenience. All apps in the REMS workflow are programmed to function with any FHIR server, but are programmed to work with this one by default.

This will start the server running on http://localhost:8080/test-ehr.

**If you've loaded resources before, and want a clean slate, delete the `target` and `build` folders from test-ehr if they exist.**
## Initialization

## Adding resources to the database
1. Install [Java](https://www.oracle.com/java/technologies/downloads/) version 11 or higher.
2. Install [gradle](https://gradle.org/) version 6.9 or higher.
3. Run `gradle bootRun`
4. In a separate terminal tab, run `gradle loadData` to load resources.

The FHIR server will persist FHIR resources between restarts. You can delete the folder `target` to clear all resources.

To load the data from the json files in fhirResourcesToLoad, run the following script:
`gradle loadData`
This will start the server running on http://localhost:8080/test-ehr.

> Note: 'gradle loadData' can only be run while the FHIR server is running and `use_oauth` is false in `src/main/resources/fhirServer.properties`
**If you've loaded resources before, and want a clean slate, delete the `target` and `build` folders from test-ehr if they exist.**

## Using OAuth security features

The FHIR server is open by default, but this can be changed in the `fhirServer.properties` file.
The FHIR server is open by default, but this can be changed in the `application.yml` file.

First, change the `use_oauth` flag to `true` to turn on security. Then set the `client_id`, `client_secret`, and `oauth_token` fields.

Expand All @@ -32,32 +28,31 @@ If using Keycloak and following the [REMS Admin](https://github.com/mcode/rems-a
1. Open the Keycloak admin console (http://localhost:8180/auth) and log in
2. Open the ClientFhirServer, then the `clients` tab, and click `app-token`.
3. Click on the `Credentials` tab, use the `regenerate secret` option if needed.
4. Copy the client secret into the properties file under `client_secret`
4. Copy the client secret into the `application.yml` file under `client_secret`

Finally, ensure that the [request generator](https://github.com/mcode/request-generator) has the correct username and password in the `properties.json` file. If following the REMS Admin guide, this will be one of the users created when setting up Keycloak.
## Usage

## Server endpoints
The EHR mainly serves resources to clients and handles authorization requests. Generally, the other apps in the REMS workflow interact with the EHR automatically. To add resources to the EHR, place the resource files in the `fhirResourceToLoad` directory and then run `gradle loadData` while the server is currently running.

| Relative URL | Endpoint Description |
| -------------- | ------------------------------------------------------ |
| `/test-ehr/` | Base server endpoint |
| `/test-ehr/r4` | EHR FHIR Server endpoint (will not resolve in browser) |
| `/test-ehr/script/rxfill` | NCPDP SCRIPT endpoint that RxFill messages from the pharmacy can be sent to (will not resolve in browser) |
A new resource can also be created manually by making a POST to a resource endpoint, for example:

## Version
`curl -d '{"resourceType":"Patient", "id":"example"}' -H "Content-Type: application/json" -X POST http://localhost:8080/test-ehr/r4/Patient`

Java v11 or higher is required to run this application.
## SMART on FHIR

## Run configurations
The EHR server SMART on FHIR compliant. This means that SMART apps like the [Request Generator](https://github.com/mcode/request-generator) and [REMS SMART on FHIR app](https://github.com/mcode/rems-smart-on-fhir) can authenticate automatically against the FHIR server.

Run configurations to run, clean, and load data for the FHIR server can be used for the IntelliJ IDEA CE IDE. You can set breakpoints on the `Boot Run` configuration.
All authorization requests are proxied to an authorization server. Any OAuth2.0 compliant authorization server can be connected to the EHR by changing the `auth_base` property in the `application.yml` file.

These were last used with IntelliJ IDEA 2021.2.2 (Community Edition) and Microsoft Edge DevTools.
This server provides a `/_services/smart/Launch` endpoint for session creation. A client POSTs a payload consisting of a `launchUrl`, `redirectUri`, and `parameters`, and receives a `launchId`.

### Steps:
The `launchId` is a unique ID which lets the SMART app maintain its state through the authorization process. This is not a standard process. Apps like the [Request Generator](https://github.com/mcode/request-generator), which are within the EHR ecosystem but not directly connected, might make use of this endpoint to create SMART sessions and launch SMART apps.

1. Select "Boot Run" as a Run Configuration from the dropdown menu.
2. Put a breakpoint (red dot) on the desired line, e.g. line 43 of `test-ehr/src/main/java/org/hl7/davinci/ehrserver/interceptor/QuestionnaireResponseSearchParameterInterceptor.java`.
3. Click the debug icon (green bug) up top.
4. Go to http://localhost:3000 (where a locally run request-generator is served at) and try to select a patient. You may have to wait for bootRun to finish starting up if you see a "Network Request Failed Error". request-generator will ask test-ehr for QuestionnaireResponse resources (to get the list of in-progress forms).
5. request-generator will pause as the breakpoint at line 43 gets hit. Hit F12 to open up DevTools on http://localhost:3000. You will see the QuestionnaireResponse (and other FHIR resources) have yet to be received.
## Server endpoints

| Relative URL | Endpoint Description |
| -------------- | ------------------------------------------------------ |
| `/test-ehr/` | Base server endpoint |
| `/test-ehr/r4` | EHR FHIR Server endpoint (will not resolve in browser) |
| `/test-ehr/script/rxfill` | NCPDP SCRIPT endpoint that RxFill messages from the pharmacy can be sent to (will not resolve in browser) |
| `/_services/smart/Launch` | SMART on FHIR endpoint which produces a launch ID for SMART apps to use when launching |