|
| 1 | +# Implementation of IPS FHIR IG on Aidbox FHIR platform |
| 2 | + |
| 3 | +[Demo](https://ips.hz.aidbox.dev/fhir/Patient/2b90dd2b-2dab-4c75-9bb9-a355e07401e8/$summary) | [Inferno International Patient Summary Test Kit](https://inferno-qa.healthit.gov/suites/ips/Zb7EriZknW) |
| 4 | + |
| 5 | +This repository contains pre-configured Aidbox instance and implementation of `$summary` operation defined by IPS. |
| 6 | + |
| 7 | +## About IPS (International Patient Summary) |
| 8 | + |
| 9 | +The IPS is intended to support the provision of essential healthcare information for a patient, regardless of where they are receiving care. It includes critical information such as allergies, medications, past surgeries, and other significant medical history details. See [IPS Specification](https://build.fhir.org/ig/HL7/fhir-ips/index.html) |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +- [Docker](https://www.docker.com/) |
| 14 | + |
| 15 | +## STEP 1: Environment and Aidbox license |
| 16 | + |
| 17 | +Copy `.env.tpl` file into `.env` file: |
| 18 | + |
| 19 | +```shell |
| 20 | +cp .env.tpl .env |
| 21 | +``` |
| 22 | + |
| 23 | +If you are hosting Aidbox on your local computer, obtain the self-hosted license as described in the [documentation](https://docs.aidbox.app/getting-started/run-aidbox-locally-with-docker). |
| 24 | + |
| 25 | +Add the license (`AIDBOX_LICENSE`) int the .env file. |
| 26 | + |
| 27 | +## STEP 2: Run aidbox and node-app in Docker |
| 28 | + |
| 29 | +```shell |
| 30 | +docker compose up --build |
| 31 | +``` |
| 32 | + |
| 33 | +On start, the node-app will [upload](./src/index.ts#L142) a sample FHIR [Bundle](./src/patientData.ts) with patient data. |
| 34 | + |
| 35 | +## Step 3: Open and log in into Aidbox instance |
| 36 | + |
| 37 | +Open in browser http://localhost:8888 |
| 38 | + |
| 39 | +And log in witn username: `admin` and password: `password` |
| 40 | + |
| 41 | +## Step 4: Request $summary using REST Console |
| 42 | + |
| 43 | +In the Aidbox admin window, navigate to the APIs section and choose REST Console. |
| 44 | + |
| 45 | +The [$summary](https://build.fhir.org/ig/HL7/fhir-ips/OperationDefinition-summary.html) operation requires either the logical ID (`Patient.id`) or a business identifier (`Patient.identifier`) of the patient. |
| 46 | +You can use the following request to view all available patients: |
| 47 | + |
| 48 | +``` |
| 49 | +GET /fhir/Patient?_elements=id,identifier |
| 50 | +``` |
| 51 | + |
| 52 | +To request the IPS "document" _Bundle_ for a specific patient using the REST Console, you can use the following request: |
| 53 | + |
| 54 | +``` |
| 55 | +GET /fhir/Patient/[id]/$summary |
| 56 | +``` |
| 57 | + |
| 58 | +Replace [id] with the logical ID of the patient you want to retrieve the IPS document for. |
| 59 | + |
| 60 | +For example: |
| 61 | + |
| 62 | +``` |
| 63 | +GET /fhir/Patient/2b90dd2b-2dab-4c75-9bb9-a355e07401e8/$summary |
| 64 | +``` |
| 65 | + |
| 66 | +Or you can use request with `identifier` search parameter: |
| 67 | + |
| 68 | +``` |
| 69 | +GET /fhir/Patient/$summary?identifier=<patient-identifier> |
| 70 | +``` |
| 71 | + |
| 72 | +For example: |
| 73 | + |
| 74 | +``` |
| 75 | +GET /fhir/Patient/$summary?identifier=574687583 |
| 76 | +``` |
| 77 | + |
| 78 | +## Step 5: Request $summary using HTTP Client |
| 79 | + |
| 80 | +If you're starting the Aidbox FHIR server for the first time, the initial step involves creating a _Client_ resource with an ID and secret. |
| 81 | +Since the newly created client does not have default permissions to access the Aidbox REST API, the next step is to configure access policies. |
| 82 | +Refer to the documentation: [Create and test access control](https://docs.aidbox.app/modules-1/security-and-access-control/auth/basic-auth) |
| 83 | + |
| 84 | +The easiest way to achieve this is by navigating to Auth > Sandbox in the Aidbox Web Admin UI and performing REST queries to create the 'basic' client and assign the AccessPolicy. |
| 85 | + |
| 86 | +Once the client is created, you can perform the `$summary` operation using an HTTP tool, similar to the following example: |
| 87 | + |
| 88 | +``` |
| 89 | +curl --location 'http://localhost:8888/fhir/Patient?_elements=id%2Cidentifier' \ |
| 90 | +--header 'Content-Type: application/json' \ |
| 91 | +--header 'Authorization: Basic YmFzaWM6c2VjcmV0' \ |
| 92 | +--data '' |
| 93 | +``` |
| 94 | + |
| 95 | +## Deploy |
| 96 | + |
| 97 | +This application works with [aidbox running](https://docs.aidbox.app/getting-started/run-aidbox-in-kubernetes/deploy-aidbox-in-kubernetes) under the following settings (envs): |
| 98 | + |
| 99 | +```yaml |
| 100 | +AIDBOX_FHIR_VERSION=4.0.1 |
| 101 | +AIDBOX_FHIR_SCHEMA_VALIDATION=true |
| 102 | +AIDBOX_FHIR_PACKAGES=hl7.fhir.r4.core#4.0.1:hl7.fhir.uv.ips#1.1.0 |
| 103 | +AIDBOX_VALIDATE_BINDING_URL="https://r4.ontoserver.csiro.au/fhir/ValueSet/\$validate-code" |
| 104 | +``` |
| 105 | + |
| 106 | +It is possible to deploy Aidbox with [Helm charts](https://github.com/Aidbox/helm-charts/tree/main). To do so, follow the steps outlined below: |
| 107 | + |
| 108 | +### 1. Add aidbox helm repo |
| 109 | + |
| 110 | +``` |
| 111 | +helm repo add aidbox https://aidbox.github.io/helm-charts |
| 112 | +``` |
| 113 | + |
| 114 | +### 2. Prepare database config |
| 115 | + |
| 116 | +```yaml |
| 117 | +config: |- |
| 118 | + listen_addresses = '*' |
| 119 | + shared_buffers = '2GB' |
| 120 | + max_wal_size = '4GB' |
| 121 | + pg_stat_statements.max = 500 |
| 122 | + pg_stat_statements.save = false |
| 123 | + pg_stat_statements.track = top |
| 124 | + pg_stat_statements.track_utility = true |
| 125 | + shared_preload_libraries = 'pg_stat_statements' |
| 126 | + track_io_timing = on |
| 127 | + wal_level = logical |
| 128 | + wal_log_hints = on |
| 129 | + archive_command = 'wal-g wal-push %p' |
| 130 | + restore_command = 'wal-g wal-fetch %f %p' |
| 131 | +
|
| 132 | +env: |
| 133 | + PGDATA: /data/pg |
| 134 | + POSTGRES_DB: postgres |
| 135 | + POSTGRES_PASSWORD: <your-postgres-password> |
| 136 | + |
| 137 | +image.repository: healthsamurai/aidboxdb |
| 138 | +image.tag: "16.1" |
| 139 | +storage: |
| 140 | + size: "10Gi" |
| 141 | + className: <your-storage-className> |
| 142 | +``` |
| 143 | +
|
| 144 | +### and apply it |
| 145 | +
|
| 146 | +``` |
| 147 | +helm upgrade --install aidboxdb aidbox/aidboxdb \ |
| 148 | + --namespace ips --create-namespace \ |
| 149 | + --values /path/to/db-config.yaml |
| 150 | +``` |
| 151 | + |
| 152 | +### 3. Prepare Aidbox config |
| 153 | + |
| 154 | +```yaml |
| 155 | +host: <your-aidbox-host> |
| 156 | +protocol: https |
| 157 | + |
| 158 | +config: |
| 159 | + PGHOST: aidboxdb.ips.svc.cluster.local |
| 160 | + PGDATABASE: postgres |
| 161 | + PGUSER: postgres |
| 162 | + PGPASSWORD: <your-postgres-password> |
| 163 | + AIDBOX_CLIENT_ID: <your-aidbox-client-id> |
| 164 | + AIDBOX_CLIENT_SECRET: <your-aidbox-client-password> |
| 165 | + AIDBOX_ADMIN_ID: <your-aidbox-admin-id> |
| 166 | + AIDBOX_ADMIN_PASSWORD: <your-aidbox-admin-password> |
| 167 | + AIDBOX_LICENSE: <aidbox-license> |
| 168 | + AIDBOX_DEV_MODE: true |
| 169 | + AIDBOX_FHIR_VERSION: 4.0.1 |
| 170 | + AIDBOX_FHIR_SCHEMA_VALIDATION: true |
| 171 | + AIDBOX_FHIR_PACKAGES: hl7.fhir.r4.core#4.0.1:hl7.fhir.uv.ips#1.1.0 |
| 172 | + AIDBOX_VALIDATE_BINDING_URL: "https://r4.ontoserver.csiro.au/fhir/ValueSet/$validate-code" |
| 173 | + AIDBOX_BASE_URL: <your-base-url> |
| 174 | + AIDBOX_PORT: 8888 |
| 175 | + AIDBOX_COMPLIANCE: enabled |
| 176 | + |
| 177 | +ingress: |
| 178 | + annotations: |
| 179 | + acme.cert-manager.io/http01-ingress-class: nginx |
| 180 | + cert-manager.io/cluster-issuer: letsencrypt |
| 181 | + kubernetes.io/ingress.class: nginx |
| 182 | +``` |
| 183 | +
|
| 184 | +### and apply it |
| 185 | +
|
| 186 | +``` |
| 187 | +helm upgrade --install aidbox aidbox/aidbox \ |
| 188 | + --namespace ips --create-namespace \ |
| 189 | + --values /path/to/aidbox-config.yaml |
| 190 | +``` |
| 191 | + |
| 192 | +To deploy the application use [prepared](./k8s.yaml) k8s config. Additionally, you have to add to the config resource `Secret`: |
| 193 | + |
| 194 | +```yaml |
| 195 | +apiVersion: v1 |
| 196 | +kind: Secret |
| 197 | +metadata: |
| 198 | + name: ips-app |
| 199 | + namespace: ips |
| 200 | +stringData: |
| 201 | + AIDBOX_CLIENT_ID: <your_aidbox_client_id> |
| 202 | + AIDBOX_CLIENT_SECRET: <your_aidbox_client_secret> |
| 203 | + APP_SECRET: <your_app_secret> # allows aidbox safely communicate with this app |
| 204 | +``` |
| 205 | +
|
| 206 | +## Run Inferno IPS tests |
| 207 | +
|
| 208 | +To run Inferno IPS tests against this implementation: |
| 209 | +
|
| 210 | +1. Copy the prepared [configuration](./ips-inferno-config.json) for the test suite. |
| 211 | +2. Create a test session on the [Inferno website](https://inferno-qa.healthit.gov/test-kits/international-patient-summary/). |
| 212 | +3. Click on the "RUN ALL TESTS" button. |
| 213 | +4. Paste the copied configuration into the JSON field and submit. |
0 commit comments