Merge pull request #25 from smart-on-fhir/mikix/resources

Add new Supported Resources page and some other improvements

.github/workflows/pages.yaml

@@ -28,9 +28,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Pull external sources
         run: ./prep.sh
       - name: Build with Jekyll
@@ -39,7 +39,7 @@ jobs:
           source: ./docs
           destination: ./_site
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
 
   # Deployment job
   deploy:
@@ -51,4 +51,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.gitignore

@@ -5,5 +5,7 @@
 .jekyll-metadata
 vendor
 
+/docs/aggregator/
+/docs/chart-review/
 /docs/etl/
 /docs/library/

docs/resources.md

@@ -0,0 +1,65 @@
+---
+title: Supported Resources
+_parent: Overview
+nav_order: 2
+# audience: non-programmers vaguely familiar with Cumulus
+# type: explanation
+---
+
+# Supported FHIR Resources
+
+## What's a Resource?
+
+The [FHIR specification](https://www.hl7.org/fhir/R4/) describes many kinds of _resources_,
+which are individual logical bundles of data.
+For example: [Patients](https://www.hl7.org/fhir/R4/patient.html),
+[Encounters](https://www.hl7.org/fhir/R4/encounter.html),
+or [Devices](https://www.hl7.org/fhir/R4/device.html).
+
+Resources are the atomic units of data that flow through the Cumulus pipeline.
+
+You can bulk export them from your EHR.<br/>
+You can feed them through Cumulus ETL.<br/>
+And you can query them with Cumulus Library.
+
+## Levels of Support
+
+Only a subset of the FHIR resources are supported by Cumulus.
+And not every resource enjoys the same level of support.
+
+For a resource to enter the Cumulus pipeline, Cumulus ETL must support it.
+Any resource that the ETL supports can be directly queried in Athena. 
+
+But for more convenient querying,
+the Cumulus Library's `core` study has additional support for some resources.
+For example, the `core` study abstracts the complexities of querying medication
+codes for you, because it has special knowledge of MedicationRequests and
+Medications.
+
+If a resource isn't supported by the `core` study, it can still be queried!
+It just may not be as convenient,
+as you'll have to handle directly querying FHIR nested layouts yourself.
+
+Over time, more resources will be added to the `core` study.
+
+## Support List
+
+| Resource           | ETL           | `core` |
+|--------------------|---------------|--------|
+| AllergyIntolerance | ✅             | ❌      |
+| Condition          | ✅             | ✅      |
+| Device             | ✅             | ❌      |
+| DiagnosticReport   | ✅             | ❌      |
+| DocumentReference  | ✅             | ✅      |
+| Encounter          | ✅             | ✅      |
+| Immunization       | ✅             | ❌      |
+| Medication         | ✅<sup>1</sup> | ✅      |
+| MedicationRequest  | ✅             | ✅      |
+| Observation        | ✅             | ✅      |
+| Patient            | ✅             | ✅      |
+| Procedure          | ✅             | ❌      |
+| ServiceRequest     | ✅             | ❌      |
+
+1. Medications are not usually bulk-exportable.
+Instead, as the ETL processes MedicationRequest resources,
+it downloads any linked Medication resources as well.

prep.sh

@@ -45,6 +45,13 @@ copy_docs()
   set_nav_order $TARGET_PATH/index.md $ORDER
 }
 
+rewind_submodule_to_last_tag()
+{
+  REPO=sources/$1
+  LATEST_TAG=$(git -C $REPO describe --abbrev=0 --tags)
+  git -C $REPO checkout "$LATEST_TAG"
+}
+
 while getopts ":d" option; do
    case $option in
       d) # dev (local) mode, assumes that we are siblings of other source packages
@@ -55,6 +62,13 @@ done
 
 git submodule update --init --remote
 
+# Some projects do proper releases, and for those we should only
+# reference the latest tagged release. Other projects (like the
+# ETL or aggregator) don't do normal releases and so can just
+# pull from main.
+rewind_submodule_to_last_tag cumulus-library
+rewind_submodule_to_last_tag chart-review
+
 # Only use nav_order 10-20 for submodules
 copy_docs cumulus-etl etl 10
 copy_docs cumulus-library library 11