Dette repoet er tiltenkt å fungerer som et monorepo for kildekoden til alle NAV sine FHIR Implementation Guides (IG). De forskjellige IG-ene genereres og publiseres automatisk som github-pages:
Repoet inneholder FHIR Shorthand (FSH) prosjekter. FSH er et deklarativt og utviklervennelig språk for å definere FHIR-ressursene som inngår i profiler. FHIR-ressurser genereres vha. SUSHI: En kompilator som transformerer FSH til FHIR-ressurser. Dette repoet inneholde derfor ikke FHIR-ressurser av type ImplementationGuide, StructureDefinition, CodeSystem, ValueSet etc.
SUSHI bruker sushi-config.yaml for å generere package-list.json og menu.xml som kreves av IG Publisher, disse filene er derfor heller ikke med.
NAV har valgt å bruke FSH istedenfor Forge: Et GUI-verktøy som generer FHIR-ressurser. Fordi det gir bedre kildekodekontroll og lettere lar seg integerere i CI\CD-pipelines. Forge krever også lisens og fungerer bare på Windows.
For å eksperimentere med FSH kan web-verktøyet FSH Online anbefales.
I FHIR-verden brukes ofte begrepene implementasjonsguide, pakke, profiler og kontrakter\datamodeller om hverandre. Dette kan være forvirrende og vi skal prøve å oppklare:
- En FHIR-profil er en kontrakt (datamodell+regler) for bruk av en FHIR-ressurs (f.eks Patient). En profil er implementert som egne FHIR-ressurser (json/xml) laget for dette formålet, f.eks StructureDefinition.
- En FHIR Implementation Guide er en samling av:
- FHIR-ressurser som utgjør profiler.
- En HTML-side for human-readable dokumentasjon.
- Generell metadata implementert som en egen FHIR-ressurs som også heter ImplementationGuide.
- Eksempler på FHIR-ressurser som er ihht. profilene.
- En FHIR NPM Package er IG-en uten dokumentasjon pakket som en NPM-pakke. Avengigheter til andre IG-er er gjenngitt som versionerte dependencies i package.json. En slik pakke kan brukes til validering og testing av FHIR-ressurser.
Mao. er det en 1:1:1 mapping mellom FSH-project, IG og FHIR Package.
IG Publisher er en open source java applikasjon (github) som tar FHIR-ressurser, markdown og bilder som input og bruker Jekyll til å generere en statisk HTML-side som kan brukes som dokumentasjon. Dette pakker den også i en FHIR NPM Package for distribuering.
Et FSH-prosjekt følger en bestemt struktur, denne strukturen har likheter med strukturen som forventes av IG Publisher. Tidligere var det slik at SUSHI måtte kjøres på et FSH-prosjekt for å generere inputen til IG Publisher, men fra og med v1.0.75 kjører IG Publisher SUSHI automatisk dersom den finner en /fsh-mappe.
Testing av profiler gjøres ved å bruke den offisielle FHIR-validatoren. Her bruker vi fhir-validator-junit-engine for å definere og kjøre test-scenarioer i YAML-filer og generere test-reports.
Generering og deployment av IG-ene gjøres vha. github-actions som kjører IG Publisher og committer artefaktene (html, css, js, assets) til en egen gh-pages branch som hostes med github-pages. Dette kan alternativt bli gjort av HL7 sin Auto-IG-builder, men da mister vi litt fleksibilitet, vi må f.eks bruke domenet: https://build.fhir.org/ig.
Publisering av releases til FHIR Package Registry krever en del manuelle steg som er dokumentert her. Vi har prøvd å automatisere dette så mye som mulig vha. GitHub-actions.
Gitt at følgende kriterier for en IG gjelder:
- Version i sushi-config.yaml er oppdatert.
- ReleaseLabel i sushi-config.yaml er satt til release.
- Versionen er dokumentert i
{ig}/input/pagecontent/CHANGELOG.md.
Når nevnte kriterier er oppfyllt vil en ny repository-release lages og package-feed.xml oppdateres. Hvis feed-en er registrert i HL7 sin package-feeds.json vil pakken automatisk publiseres til FHIR Package Registry. Husk at en versionert pakke-publikasjon er immutable og ikke kan slettes.
For å bygge IG-er lokalt trenger du SUSHI, IG Publisher og alle avhengighetene. Dette kan du installere ved å følge de respektive installasjonsveiledningene, alternativt kan du bruke et docker-image, isåfall må du installere Docker.
Det er en package.json som inkluderer dependencies og pre-definerte skript for å automatisere vanlige oppgaver som: bygg, test, validate, clean++. Disse skriptene skal fungere på både linux, osx og windows.
Sørg først for å installere JDK (>1.8) samt Node. Deretter åpner du et terminalvindu i root-katalogen og kjør npm ci, dette installere alle node-modules samt laster ned nødvendige .jar filer.
NPM tasks kan kjøres vha. en terminal eller gjennom vscode, følgende tasks er definert:
- build:docker: Bygger docker-imaget som brukes for kjøre IG-publisher.
- build:ig: Kjører IG Publisher vha. docker-imaget bygd av build:docker.
- build:package-feed: Genererer package-feed.xml vha. liquid template og GitHub releases API.
- build:sushi : Transformerer FSH filer til FHIR json ressurser.
- clean: Sletter genererte filer.
- test: Kjører tester som verifiserer at FHIR Validering av test ressurser vha. IG gir forventet resultat.
- validate: Validerer FHIR ressursene som inngår i IG-en.
Eksempel på kjøring av en NPM-task:
npm run validate
Flere av task-ene kjører mot en IG. For å velge IG må du editere .npmrc filen.
For utvikling av IG-er er det greit å bruke vscode.
vscode-language-fsh extension hjelper med litt syntax-highlighting og IntelliSense, og skal komme som en anbefaling når du åpner repoet i vscode.
Vi har lagt til FHIR json-schema referanse i .vscode/settings.json slik at du får IntelliSense dersom du jobber med FHIR json-ressurser direkte.
Det er laget egne tasks i .vscode/tasks.json som kan brukes for å bygge og teste IG-en, SUSHI er registrert som en bygg-task og kan dermed kjøres vha. ctrl+shift+b hurtigtast, de andre task-ene kan du velge ved å trykke F1 og deretter skrive Tasks: Run task.
Denne seksjonen trenger du ikke forholde deg til dersom du bruker Tasks i npm eller vscode.
Fordi transformeringen av et FSH-prosjekt til en IG krever mange dependencies (java, nodejs, npm, ruby, jekyll, sushi, ig-publisher etc.) har vi laget en Dockerfile for å bygge et docker-image som inneholder både SUSHI, IG Publisher og FHIR Validator + alle nødvendige dependencies.
Kjør følgende kommando fra .docker katalogen til dette repoet for å bygge docker-imaget, dette tar ca 4 minutter.
docker build -t navikt/fhir-ig-dev .
SUSHI kjøres med følgende kommando, dette tar normalt noen sekunder og vil generere en fsh-generated katalog med FHIR-ressurser innenfor FSH-prosjektet.
docker run --rm -v {fsh-project-dir}:/data navikt/fhir-ig-dev sushi /data
## Eksempel på windows:
docker run --rm -v c:\repos\fhir\igs\MessagingCore:/data navikt/fhir-ig-dev sushi /data
FHIR Validator brukes for å validere FHIR-ressurser. F.eks kan ressursene generert av SUSHI valideres med følgende kommando:
docker run --rm -v {fsh-project-dir}:/data navikt/fhir-ig-dev validator /data/fsh-generated/resources
IG Publisher kjøres med følgende kommando, dette tar gjerne 3-4 minutter og vil generere en rekke kataloger innenfor prosjektet.
docker run --rm -v {fsh-project-dir}:/data navikt/fhir-ig-dev publisher -ig /data/ig.ini
Eksemplene over bruker alle --rm flagget som gjør at containeren slettes etter kjøringen, dette vil si at alle pakker må lastes ned for hver gang og det kan derfor være greit å lage et eget volume for package-cache, i tillegg kan det være greit å bruke -it flagget slik at du kan bruke ctrl+c for å avbryte kjøringer. Eksempel med SUSHI blir da følgende (gjelder også validator og publisher):
docker run -it --rm -v package-cache:/root/.fhir -v c:\repos\fhir\igs\MessagingCore:/data navikt/fhir-ig-dev sushi /data