feat: support Implementation Guides (#266)

* feat: add Implementation Guides compiler script (#192) * feat: load compiled implementation guides (#199) * feat: add Implementation Guides integ tests (#205) * chore: add compile-igs yarn script * feat: add HAPI validator lambda fn (#221) * feat: Compile IG StructureDefinitions (#235) * feat: add useHapiValidator CFN parameter (#236) * test: IGs: Validation during create/update and supportedProfile in CapStatement (#237) * feat: specify paths to IG resources (#241) * fix: copy IG files to webpack deployment package (#247) * chore: add third party attributions file (#251) * feat: add support for DSTU3 on Java Hapi validator (#254) * docs: add IGs documentation (#256) * chore: update gh actions tu build and deploy hapi validator (#257) * feat: support Implementation Guides * docs: fix changelog headers * chore: update version in package.json Co-authored-by: justinusmenzel <[email protected]> Co-authored-by: Justinus Menzel <[email protected]> Co-authored-by: Emil Diaz <[email protected]> Co-authored-by: Tim Nguyen <[email protected]> Co-authored-by: shyogesh-sw <[email protected]>
awslabs · Mar 29, 2021 · 393846b · 393846b
1 parent a7c47bc
commit 393846b
Show file tree

Hide file tree

Showing 317 changed files with 5,901 additions and 53 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -25,6 +25,8 @@ module.exports = {
         'no-empty-function': 'off',
         '@typescript-eslint/no-empty-function': 'error',
         'import/no-extraneous-dependencies': ['error', {'devDependencies': ['**/*.test.ts', 'integration-tests/*']}],
+        'no-shadow': 'off', // replaced by ts-eslint rule below
+        '@typescript-eslint/no-shadow': 'error'
     },
     settings: {
         'import/resolver': {

diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
@@ -19,6 +19,9 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: 12
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
       - name: Install dependencies
         run: |
           cd auditLogMover
@@ -33,6 +36,11 @@ jobs:
           yarn release
           cd ..
           yarn release
+      - name: Build Hapi validator
+        run: |
+          cd javaHapiValidatorLambda
+          mvn --batch-mode --update-snapshots --no-transfer-progress clean install
+          cd ..
   pre-deployment-check:
     needs: build-validate
     runs-on: ubuntu-18.04
@@ -55,19 +63,38 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: 12
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
       - name: Setup config file
         env:
           DEV_AWS_USER_ACCOUNT_ARN: ${{ secrets.DEV_AWS_USER_ACCOUNT_ARN }}
         run: sed "s#<dev-arn>#$DEV_AWS_USER_ACCOUNT_ARN#g" serverless_config.template.json > serverless_config.json
+      - name: Install npm dependencies
+        run: yarn install
+      - name: Download US Core IG
+        run: |
+          mkdir -p implementationGuides
+          curl https://www.hl7.org/fhir/us/core/package.tgz | tar xz -C implementationGuides
+      - name: Compile IGs
+        run: yarn run compile-igs
       - name: Install serverless
         run: npm install -g serverless
+      - name: Deploy Hapi validator
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID}}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        run: |
+          cd javaHapiValidatorLambda
+          mvn --batch-mode --update-snapshots --no-transfer-progress clean install
+          serverless deploy --stage dev --region us-west-2 --conceal
+          cd ..
       - name: Deploy FHIR Server and ddbToEs
         env:
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID}}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          yarn install
           serverless deploy --stage dev --region us-west-2 --conceal
       - name: Deploy auditLogMover
         env:

diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,6 @@ serverless_config.json
 .yalc
 yalc.lock
 
+/implementationGuides
+/compiledImplementationGuides
+/.webpack/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.5.0] - 2021-03-29
+
+### Added
+- Add support for Implementation Guides(IGs).
+
+   IG packages can now be included as part of the deployment. This enables search parameters and validation rules from profiles
+   included in the IG. The capability statement is also updated to reflect those changes.
+
+   Check out our [IGs documentation](USING_IMPLEMENTATION_GUIDES.md) for more details.
+
 ## [2.4.0] - 2021-01-13
 
 ### Added

diff --git a/README.md b/README.md
@@ -31,6 +31,8 @@ git clone https://github.com/awslabs/fhir-works-on-aws-deployment.git
 - [Windows](./INSTALL.md#windows-installation)
 - [Docker](./INSTALL.md#docker-installation)
 
+If you intend to use FHIR Implementation Guides read the [Using Implementation Guides](./USING_IMPLEMENTATION_GUIDES.md) documentation first. 
+
 ### Development
 
 [Instructions for making local code changes](./DEVELOPMENT.md)

diff --git a/USING_IMPLEMENTATION_GUIDES.md b/USING_IMPLEMENTATION_GUIDES.md
@@ -0,0 +1,155 @@
+# Using FHIR Implementation Guides
+
+An [Implementation Guide (IG)](https://www.hl7.org/fhir/implementationguide.html) is a set of rules that describe how FHIR resources should be used to solve a particular problem. Using IGs, you can make your FHIR server compliant for country-specific set of rules. IGs can also describe a proper way to represent particular content in FHIR (for example, the breast cancer medical diagnostic process).
+
+IGs are distributed as [packages similar to NPM packages](https://confluence.hl7.org/display/FHIR/NPM+Package+Specification)
+
+## Prerequisites
+
+The prerequisites for FHIR IGs are same as in the FHIR [installation documentation](INSTALL.md). In addition, you need the following: 
+
+1. Java 8 or higher. We recommend using [Amazon Corretto](https://aws.amazon.com/corretto/)
+2. [Maven](https://maven.apache.org/install.html)
+
+## Installation Steps
+
+1. Download the IG packages. IG packages can be downloaded from different sources. The most common sources are the corresponding official IG website (for example, [download](https://www.hl7.org/fhir/us/core/package.tgz) from the [US Core website](https://www.hl7.org/fhir/us/core/downloads.html) or the [FHIR Package Registry](https://registry.fhir.org/).
+
+1. Copy the unzipped IG deployment packages to the `implementationGuides` directory
+
+    Example:
+    ```
+    .
+    └── implementationGuides/
+        ├── hl7.fhir.us.core
+        └── hl7.fhir.us.carin-bb
+    ```
+
+1. Compile the IGs using the `compile-igs` command:
+    ```bash
+    #fhir-works-on-aws-deployment
+    yarn run compile-igs
+    ```
+1. Deploy the Hapi Validator using the following commands:
+    ```bash
+    #fhir-works-on-aws-deployment/javaHapiValidatorLambda
+    mvn clean install
+    serverless deploy
+    ```
+   **Note:** By default the Hapi Validator is set up with FHIR R4. If you want to use FHIR STU3, follow the
+   comments on [pom.xml](javaHapiValidatorLambda/pom.xml) to update the dependencies and deploy using the `fhirVersion` parameter: 
+   ```bash
+   #fhir-works-on-aws-deployment/javaHapiValidatorLambda
+   serverless deploy --fhirVersion '3.0.1'
+   ```
+1. Deploy the FHIR Works on AWS server using the `deploy` command: 
+    ```bash
+    #fhir-works-on-aws-deployment
+    serverless deploy --useHapiValidator true
+    ```
+
+Note: For more information on how to set up AWS credentials or how to deploy to a specific stage or region, refer to the [installation documentation](INSTALL.md#manual-installation)
+
+## Supported IG features in FHIR Works on AWS
+
+After you apply an Implementation Guide to FHIR Works on AWS, the following changes are effective: 
+
+### Search Parameters
+
+Additional search parameters described in IGs are parsed and available on the FHIR Works on AWS server.
+
+For example, when US Core IG is applied, the patient details are searched by ethnicity using the ethnicity search parameter `GET <API_endpoint>/Patient?ethnicity=<etnicity_code>`.
+
+Search parameters are built using the resources of type SearchParameter available in the IG package.
+
+### Input Validation
+
+Input validation is enhanced to apply validation rules specific to the profiles defined on the IGs. Validation is performed using the  [HAPI FHIR Validator](https://hapifhir.io/).
+
+For example, applying the US Core IG adds the [us-core-patient profile](https://www.hl7.org/fhir/us/core/StructureDefinition-us-core-patient.html) which adds validation rules for patients, such as rejecting patients with a missing gender field, or patients with ethnicity information that do not conform to the definition of the `us-core-ethnicity` extension.
+
+The following code snippet displays a valid US core patient:
+
+```
+{
+  "resourceType": "Patient",
+  "id": "example",
+  "meta": {
+    "profile": [
+      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
+    ]
+  },
+  "extension": [
+    {
+      "extension": [
+        {
+          "url": "ombCategory",
+          "valueCoding": {
+            "system": "urn:oid:2.16.840.1.113883.6.238",
+            "code": "2135-2",
+            "display": "Hispanic or Latino"
+          }
+        },
+        {
+          "url": "text",
+          "valueString": "Hispanic or Latino"
+        }
+      ],
+      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity"
+    }
+  ],
+  "identifier": [
+    {
+      "use": "usual",
+      "type": {
+        "coding": [
+          {
+            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
+            "code": "MR",
+            "display": "Medical Record Number"
+          }
+        ],
+        "text": "Medical Record Number"
+      },
+      "system": "http://hospital.smarthealthit.org",
+      "value": "1032702"
+    }
+  ],
+  "name": [
+    {
+      "family": "Shaw",
+      "given": [
+        "Amy",
+        "V."
+      ]
+    }
+  ],
+  "gender": "female"
+}
+```
+
+Input validation utilizes the resources of type `StructureDefinition`, `ValueSet`, and `CodeSystem` available in the IG package.
+
+### Capability Statement
+
+The server capability statement returned by `GET <API_endpoint>/metadata` is updated to reflect the above features. Specifically, the `supportedProfile` field is populated and additional search parameters have a corresponding `searchParam` entry.
+
+For example, after applying the US Core IG, the fragment of the capability statement related to the patient resource is updated to include the following:
+```
+{
+  "type": "Patient",
+  "supportedProfile": [
+    "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
+  ],
+  "searchParam": [
+    {
+      "name": "ethnicity",
+      "definition": "http://hl7.org/fhir/us/core/SearchParameter/us-core-ethnicity",
+      "type": "token",
+      "documentation": "Returns patients with an ethnicity extension matching the specified code."
+    },
+    ...
+  ],
+  ...
+}
+```