Architektur

For the english version please click here.

Zum besseren Verständnis der Architektur von TerminoloGit werden Grundkenntnisse in den folgenden Technologien und/oder Systemen vorausgesetzt:

• Git
  • Branching and merging
  • Tags
  • Git logs
• GitLab
  • Merge requests
  • CI/CD
• HL7® FHIR®
  • REST API
• HL7® FHIR® IG Publisher

TerminoloGit und seine Komponenten

TerminoloGit ist ein Open Source Projekt, das aus mehreren interagierenden Repositories besteht und von der österreichischen ELGA GmbH initiiert wurde.

• TerminoloGit Dev
• TerminoloGit Dev HTML - Hostet statische HTML-Seiten, die die Versionierung von Terminologien ermöglichen.
• MaLaC-CT (auch Standalone) - Konvertiert zwischen unterstützten Dateiformaten.
• TerminoloGit Template - Formatiert statische HTML-Seiten.
• fsh-ing-grounds oder docker image elgagmbh/fsh-ing-grounds - Docker-Image, das für die Ausführung des HL7® FHIR® IG Publisher vorbereitet ist
• external HL7® FHIR® IG Publisher - Wird verwendet, um statische HTML-Seiten zu erzeugen.

TerminoloGit und FHIR® Server

Soll TerminoloGit in Verbindung mit einem FHIR® Server eingesetzt werden, so bietet sich das Projekt TerminoloGit tergi an, das die Einrichtung eines vollwertigen FHIR® Servers ergänzt durch ein leichtgewichtiges Git Repository ermöglicht.

Struktur des Repositorys

In diesem Kapitel wird kurz die Struktur eines TerminoloGit-Repositorys erläutert:

• . - enthält die README, den CODE_OF_CONDUCT, das CONTRIBUTING, das CHANGELOG, die LICENSE, sowie eine Menge Skripte, die während eines Pipeline-Laufs verwendet werden.
• input/files/ - enthält einige Vorlagen, die für die Erstellung von Terminologie verwendet werden.
• input/fsh/ - wird beibehalten, um TerminoloGit-Benutzern mitzuteilen, dass keine fsh-Dateien in diesem Verzeichnis abgelegt werden sollen.
• input/images/ - Bilder, die in der Dokumentation verwendet werden.
• input/includes/ - für jede Terminologie wird ein Fragment für ihre Downloads und ihre früheren Versionen in diesem Verzeichnis bereitgestellt. Diese Fragmente werden später von der TerminoloGit-Vorlage verarbeitet.
• input/pagecontent/ - mehrere Markdown-Dateien, die die Dokumentation von TerminoloGit bilden.
• input/redirects/ - für jede Terminologie existiert eine redirects-Datei, die den Zugriff auf die Terminologien auf der Grundlage ihres kanonischen Namens ermöglicht.
• input/resources/ - FHIR®-Ressourcen, die nicht von MaLaC-CT verarbeitet werden sollen, werden in diesem Verzeichnis abgelegt, z.B. ConceptMaps oder intensionale ValueSets.
• input/sitemap/ - Meta-Informationen für Web-Crawler, wo die Sitemap zu finden ist und welche Seiten indiziert werden sollen.
• terminologies/ - für jede Terminologie existiert ein Verzeichnis (Muster [CodeSystem | ValueSet]-[id]). Außerdem enthält es die terminologiesMetadata.csv.

Die Datei terminologies/terminologiesMeta.csv enthält einige wichtige Meta-Informationen über alle Terminologien, die von TerminoloGit verwaltet werden:

1. name - [CodeSystem | ValueSet]-[id]
2. canonical - [TERMGIT_CANONICAL]/[CodeSystem | ValueSet]/[id]
3. oid - OID der Terminologie
4. version - Version der Terminologie
5. id - die id der Terminologie
6. typ - [CodeSystem | ValueSet].
7. metadata-change-timestamp - der Zeitpunkt der letzten Änderung der Terminologie-Metadaten

CI/CD-Ablauf

Die CI/CD-Pipeline in TerminoloGit besteht aus mehreren Phasen und den dazugehörigen Jobs und ist wie folgt aufgebaut. Bitte beachten Sie, dass weder alle Phasen noch alle Jobs in jeder Pipeline ausgeführt werden, sondern dass Regeln bestimmen, welche ausgeführt werden.

• Stage manual_trigger
  • Job manual_trigger - Ein manueller Auslöser zum Starten der Pipeline in anderen braches als dem Standardbranch. Auf dem Standardbranch wird die Pipeline automatisch gestartet, wenn neue Commits erfolgen.
• Stage check_variables
  • Job check_variables - Überprüft, ob die erforderlichen Umgebungsvariablen gesetzt sind.
• Stage run_malac-ct - Abhängig von den Umständen wird einer der folgenden Jobs ausgeführt.
  • Job run_malac-ct - Dieser Job erkennt automatisch neue/aktualisierte Terminologien im Verzeichnis terminologies/ und konvertiert sie mit Hilfe von MaLaC-CT in alle Dateiformate.
  • Job run_malac-ct_integration_test - Dieser Job ist nicht Teil der Standard-Pipeline in einem TerminoloGit-Projekt. Er kann aus einem MaLaC-CT-Repository heraus ausgelöst werden und wird dann anstelle des üblichen run_malac-ct ausgeführt. Er konvertiert alle vorhandenen Terminologien eines bestimmten TerminoloGit-Repositorys unter Verwendung eines bestimmten Dateiformats als Quelle.
  • Job skip_malac-ct - Dieser Job kann ausgelöst werden, wenn ein Commit mit SKIP_MALAC vorangestellt wird. Infolgedessen wird keine Terminologie von MaLaC-CT verarbeitet. Bitte beachten Sie, dass neue Geschäftsversionen/business versions in diesem Fall NICHT erkannt werden.
• Stage version_ig_files
  • Job version_ig_files- Dieser Job behandelt die Erstellung früherer Versionen (außer für Pipelines, die mit einem SKIP_MALAC Commit gestartet wurden)
• Stage run_ig
  • parallele Jobs run_ig - Diese Jobs kümmern sich in logisch zusammenhängenden Gruppen aufgeteilt um das Starten mehrerer HL7® FHIR® IG Publisher, der die statischen HTML-Seiten erstellt. Außerdem sorgen dieses Jobs dafür, dass für jede Terminologie zwei Git-Tags erstellt werden, die kontinuierlich auf die aktuelle Version der jeweiligen Terminologie verweisen (siehe Abrufen von Metainformationen zu einem Git-Tag).
• Stage html - Es wird immer prepare_output_and_update_html ausgeführt, außer bei Pipelines die aus anderen Pipelines starten, wie den MaLaC-CT Integrationstests. In diesem Fall wird prepare_output ausgeführt.
  • Job prepare_output_and_update_html - Die Ergebnisse von run_ig werden zusammengeführt und in das TERMGIT_HTML_PROJECT gepusht. Der Name des Branches ist derselbe wie im TerminoloGit-Projekt, dies gilt auch für den default-Branch.
  • Job prepare_output - Die Ergebnisse von run_ig werden vorbereitet und dem folgenden pages Job bereitgestellt.
• Stage publish - Die folgenden Jobs laufen parallel.
  • Job pages - Aktualisiert die GitLab-Seiten des TerminoloGit-Projekts.
  • Job upload_input_resources - Lädt alle Ressourcen im Verzeichnis input/resources/ auf die angegebenen FHIR®-Server hoch.

Im Folgenden werden die drei häufigsten Abläufe der CI/CD-Pipeline visualisiert. Details finden Sie in der Datei .gitlab-ci.yml.

Standard Terminologiepflege

Integrationstest

SKIP_MALAC

Parallele run_ig Jobs und ihre logischen Terminologie-Gruppen

Um den Flaschenhals der IG Publisher Ausführung für das HTML-Rendering der FHIR-Ressourcen zu umgehen und dadurch einen deutlich beschleunigten Publikationsprozess zu erreichen, können logische Terminologie-Gruppen verwendet werden, die parallel in eigenen run_ig-Jobs abgearbeitet und danach zusammengeführt werden.

​Diese logischen Gruppen werden in der Datei terminologies/logical_groups_for_parallel_runs.yml definiert (mittels TERMINOLOGY_LOGICAL_GROUP). In dieser Datei besteht außerdem die Möglichkeit, einzelnen CI/CD Variablen (siehe CI/CD-Variablen), die im jeweiligen run_ig-Job verwendet werden, spezielle Werte zuzuweisen.

Eine logische Gruppe macht idealerweise nur Sinn, wenn sie eine oder mehrere Terminologien beinhaltet. Dabei sollte eine logische Gruppe so erstellt werden, dass sich untereinander abhängige Terminologien (Value-Sets und die dazugehörigen Codesysteme) in einer logischen Gruppe befinden, damit der IG Publisher die Referenzen untereinander korrekt aufbauen kann. Terminologien werden in der Datei terminologies/term_to_logical_groups.csv in der Form von [Resourcentyp]-[id],[TERMINOLOGY_LOGICAL_GROUP] der jeweiligen logischen Gruppe zugeordnet.

Neben diesen logischen Gruppen mit Terminologien gibt es zwei Arten von speziellen logischen Gruppen, die folgenden Formatvorschriften folgen müssen:

Spezielle __-Gruppen

__-Gruppen,

• die keine spezifischen Terminologien behandeln,
• nur für die Lösung von technischen TerminoloGit-Problemen erstellt wurden und
• auch außerhalb von der Datei divide_n_conquer.py Einfluss auf die Ausführung der Pipeline haben,

sollten mit einem doppelten Unterstrich (__) beginnen. Diese Gruppen sollten nicht in der Datei terminologies/term_to_logical_groups.csv aufgeführt werden.

Ein Beispiel einer solchen __-Gruppe ist die logische Gruppe __no_terminologies. Durch diese wird ein run_ig-Job ohne Terminologien-Ressourcen ausgeführt, um eine artifacts.html für den Other artifacts Menüpunkt zusammenzustellen.

Spezielle _-Gruppen,

_-Gruppen,

• die eine oder mehrere Terminologien implizit oder explizit enthalten,
• die zur Lösung spezieller Verarbeitungsprobleme erstellt wurden und nicht nur für übliche Gruppierungen verwendet werden und
• die nur in der Datei divide_n_conquer.py Einfluss auf die Ausführung der Pipeline haben,

sollten mit einem Unterstrich (_) beginnen. Diese Gruppen können, müssen aber nicht in der terminologies/term_to_logical_groups.csv aufgeführt werden.

Ein Beispiel einer solchen _-Gruppe ist die logische Gruppe _all_other_terminologies. Durch diese wird ein run_ig-Job mit allen Terminologien ausgeführt, die nicht explizit einer Gruppe zugeordnet wurden. Wird diese Gruppe gelöscht oder übersprungen, werden nur die in der Datei terminologies/term_to_logical_groups.csv angeführten Terminologien im HTML-Rendering vorhanden sein.

Für eine funktionierende TerminoloGit-Pipeline sollen __-Gruppen jedes Mal ausgeführt und nicht bearbeitet oder aus der Datei terminologies/logical_groups_for_parallel_runs.yml entfernt werden. Im Gegensatz dazu können _-Gruppen übersprungen, bearbeitet oder sogar vollständig aus der Datei terminologies/logical_groups_for_parallel_runs.yml entfernt werden, ohne die Funktionsweise von TerminoloGit zu beeinträchtigen.

Fully dressed use case diagram

Das gesamte Konzept wird in einem fully dressed use case diagram dargestellt, unter dem die schriftlichen Anwendungsfälle auf Unterfunktions-/Fischebene zu finden sind. Bitte beachten Sie, dass dieses Diagramm nicht vollständig mit dem Cockburn-Diagramm für fully dressed use case diagram konform ist. Es wurden ein paar Änderungen vorgenommen, um alle benötigten Informationen in einem Diagramm darzustellen.

Parameter für alle Use Cases:

1. Akteure:
   • es wird nur zwischen GitLab-Rollen und dem GitLab-Dienst selbst unterschieden, zusätzliche Rollen können pro Governance in jedem Produktionssystem festgelegt werden
2. Geltungsbereich:
   • eine Terminologie wie ein Codesystem oder ein Value-Set
3. Ebene:
   • Unterfunktion/Fisch

#1 Konto erstellen, authentifizieren und autorisieren

1. Akteure:
   • Gast (Mensch)
   • Dienst (Maschine)
2. Kurzbeschreibung: Ein Gast benötigt ein GitLab-Konto für spezielle Interaktionen (z. B. das Abonnieren eines Tags einer Terminologie über GitLab) und erstellt eines über GitLab.
3. Postkonditionen:
   1. Minimalgarantien: keine
   2. Erfolgsgarantien:
      • Es wurde ein Benutzerkonto erstellt
4. Voraussetzungen:
   • Die für TerminoloGit benötigten GitLab-Projekte wurden erstellt
5. Auslöser:
   • Ein Gast möchte eine spezielle Interaktion durchführen
6. Grundlegender Ablauf:
   1. Anlegen eines Kontos auf GitLab und ggf. Beantragung individueller Berechtigungen
   2. Anmeldung bei GitLab
7. Erweiterungen: keine
8. Software:
   • Jeder Browser
9. Hardware:
   • Jeder Client mit einem Browser
10. Dienste:
    • GitLab.com oder eigenes GitLab CE Hosting

#2 Abonnement

1. Akteure:
   • Dienst (Maschine)
   • Abonnent (Mensch - ein Gast, der einige Terminologien abonniert hat)
2. Kurzbeschreibung: Die Abonnenten werden automatisch per E-Mail informiert, weil eine neue oder bearbeitete Terminologiedatei veröffentlicht wurde.
3. Postkonditionen:
   1. Minimalgarantien: keine
   2. Erfolgsgarantien:
      • Ein Teilnehmer wird über eine neue Terminologie informiert
4. Voraussetzungen:
   • Ein Gast hat das GitLab-Projekt TerminoloGit abonniert
5. Auslöser:
   • Eine Terminologie wurde hinzugefügt oder aktualisiert
6. Grundlegender Ablauf:
   1. GitLab sendet die Änderung an alle Abonnenten
7. Erweiterungen: keine
8. Software:
   • Jedes E-Mail-Programm
9. Hardware:
   • Jeder Client mit einem E-Mail-Programm
10. Dienste:
    • GitLab zum Versenden der Änderung an die Abonnenten

#3 Verwendung von FHIR® IG und FHIR-tx

1. Akteure:
   • Gast (Mensch oder Maschine)
   • Service (Maschine)
2. Kurzbeschreibung: Eine Terminologie wie ein Codesystem oder ein Value-Set wird über die GitLab GUI, TerminoloGit GUI, GitLab REST API oder FHIR-tx REST API Schnittstelle abgefragt
3. Postconditions:
   1. Minimalgarantien: keine
   2. Erfolgsgarantien:
      • wenn die gesuchte Terminologie existiert
        • Empfangen einer Terminologie
4. Voraussetzungen:
   • Das TerminoloGit GitLab Projekt existiert
   • Die FHIR® IG ist veröffentlicht
   • Die FHIR-tx ist auf dem neuesten Stand
5. Auslöser:
   • Eine Terminologie muss abgerufen werden
6. Grundlegender Ablauf:
   1. Durch Aufrufen der FHIR® IG-Website erhält ein Gast ein durchsuchbares Format aller Terminologien mit der Möglichkeit, sie in einem beliebigen Format herunterzuladen
   2. Beim Aufruf der GitLab-Website erhält der Gast eine Liste aller Formate aller Terminologien mit der Möglichkeit, sie herunterzuladen
   3. Durch die Verwendung von REST-Operationen für FHIR® ValueSet- oder CodeSystem-Ressourcen werden die Terminologien von einer Maschine abgerufen
   4. Beim Betrieb mit der GitLab REST API werden die Terminologien von einer Maschine abgerufen
7. Erweiterungen:
   • Eine Validierung von Konzepten in ValueSet- oder CodeSystem-Ressourcen ist mit $validate-code möglich.
   • Ein Hierarchiestatus zwischen zwei Konzepten in einem CodeSystem ist durch $subsumes möglich.
   • Eine detaillierte Ansicht eines Konzepts in einem CodeSystem ist mit $lookup möglich.
8. Software:
   • Ein Browser oder REST-Client
9. Hardware:
   • Client zum Durchsuchen oder Senden von REST-Anfragen
10. Dienste:
    • GitLab für die Veröffentlichung von Terminologien
    • ein FHIR®-Server für REST-Anfragen

#4 CRUD und Übertragung einer Terminologie an GitLab

1. Akteure:
   • Entwickler (Mensch)
   • Dienst (Maschine)
2. Kurzbeschreibung: Eine neue Terminologiedatei wird erstellt oder bearbeitet und an das GitLab-Projekt übergeben
3. Postconditions:
   1. Minimalgarantien:
      • eine Rückmeldung, was bei dem Commit oder Push falsch gelaufen ist
   2. Erfolgsgarantien:
      • Die neue, bearbeitete oder als gelöscht gekennzeichnete Terminologiedatei wird im TerminoloGit GitLab Projekt veröffentlicht. Die CI/CD-Pipeline wird automatisch oder manuell angestoßen
4. Voraussetzungen:
   • Das TerminoloGit GitLab Projekt existiert
   • Ein lokaler Git-Client und ein Editor sind auf einem Client installiert oder es wird eine WebIDE von GitLab verwendet
5. Auslöser:
   • Eine Terminologie muss erstellt oder aktualisiert werden
6. Grundlegender Ablauf:
   1. Mit einem Editor (z.B. Notepad++, Visual Studio Code) oder einer WebIDE wird eine Terminologiedatei im lokalen Git-Repository erstellt, aktualisiert oder gelöscht, indem der Status auf retired gesetzt wird.
   2. In Ihrem lokalen Git-Client wird ein neuer Commit erstellt und an das entfernte TerminoloGit-Repository übertragen
7. Erweiterungen:
   • Ein Branching neben dem Standardbranch könnte darauf hinweisen, dass eine neue Übergabe zu Test- oder Genehmigungszwecken durchgeführt wird. In diesem Fall ist das CI/CD von GitLab das gleiche wie für den Standardbranch, mit dem einzigen Unterschied, dass das Ergebnis nur auf einer separaten Seite sichtbar ist.
8. Software:
   • ein lokaler Git-Client oder ein Browser
   • ein Editor (z. B. Notepad++, Visual Studio Code) oder ein Browser
9. Hardware:
   • Client für die Bearbeitung von Textdateien und Git
10. Dienste:
    • GitLab für die Veröffentlichung von Terminologien

#5 Kontinuierliche Lieferung an FHIR® IG und FHIR-tx

1. Akteure:
   • Service (Maschine)
2. Kurzbeschreibung: Eine neue oder bearbeitete Terminologiedatei wird von einem Runner vom GitLab-Service in andere Terminologieformate konvertiert
3. Postconditions:
   1. Minimalgarantien:
      • Es liegt ein CI/CD-Fehler vor
   2. Erfolgsgarantien:
      • Es wird von MaLaC-CT konvertiert, vom IGVer versioniert, vom IG Publisher gerendert und auf einer Gitlab-Seite angezeigt
4. Voraussetzungen:
   • Das TerminoloGit GitLab CI/CD ist konfiguriert
5. Auslöser:
   • Eine Terminologie wurde hinzugefügt oder aktualisiert
6. Grundlegender Ablauf:
   1. Ein GitLab-Runner für das CI/CD wird gestartet, weil ein neuer Commit gepusht wurde
   2. der Runner konvertiert die Terminologie in alle anderen Dateiformate
   3. wenn die Konvertierung erfolgreich war, wird der IGVer und anschließend der IG Publisher gestartet
   4. wenn der IG Publisher bestanden hat, wird der Upload zu FHIR-tx gestartet
7. Erweiterungen: keine
8. Software: keine
9. Hardware: keine
10. Dienste:
    • GitLab für die Ausführung des Läufers

#6 In Branches schieben, genehmigen und in Master zusammenführen

1. Akteure:
   • Entwickler (Mensch)
   • Dienst (Maschine)
2. Kurzbeschreibung: Neue oder bearbeitete Terminologiedateien werden in einen Branch übertragen und für eine Zusammenführung mit Master angefordert.
3. Postconditions:
   1. Minimalgarantien:
      • Wenn eine Korrektur erforderlich ist:
        • Warten, dass der Entwickler mit einem neuen Commit korrigiert
   2. Erfolgsgarantien:
      • ein Branch wurde nach Master zusammengeführt
4. Voraussetzungen:
   • Das TerminoloGit-Projekt ist für das Branching konfiguriert
5. Auslöser:
   • Eine Terminologie wurde zu einem Branch hinzugefügt oder aktualisiert
6. Grundlegender Ablauf:
   1. der Entwickler erstellt einen Branch für seine Commits
   2. der Entwickler erstellt einen Commit mit seinen Änderungen
   3. der Entwickler beantragt eine Zusammenführung mit dem Master oder einem anderen geschützten Branch
   4. ein anderer Entwickler kommentiert die Anfrage und verlangt Änderungen oder akzeptiert diesen Branch
   5. der Entwickler führt ihn mit dem Master zusammen
7. Erweiterungen: keine
8. Software:
   • ein Browser
9. Hardware:
   • eine Maschine mit einem Browser
10. Dienste:
    • GitLab zum Ausführen des Läufers

BigPicture

Das folgende BigPicture zeigt die verschiedenen Möglichkeiten der Verwendung von TerminoloGit, einschließlich der möglichen kaskadierenden Systemabhängigkeiten.

Die kaskadierende Synchronisierung zwischen TerminoloGit-Instanzen wird durch Merge Requests empfohlen. Sie können Merge Requests zu und von jedem geforketen Projekt erstellen, Sie können sogar nachträglich Fork-Relationen hinzufügen. Beachten Sie, dass Sie bei Fehlern während des Posts (z. B. einem internen Serverfehler von 500) die alte Fork-Relation vorher löschen müssen. Sie können auch die Git-Funktion Submodule oder Subtree verwenden. Darüber hinaus ist es möglich, die Synchronisation über CI/CD im eigenen System oder über "Mirroring"- oder "Sync"-Funktionen zu automatisieren, wenn Sie selbst keine Anpassungen/Erweiterungen an den Terminologien vornehmen.

Die kaskadierende Synchronisation zwischen einer TerminoloGit-Instanz und einer tergi-Instanz muss in Ihrer TerminoloGit-Instanz eingerichtet werden, siehe das README im tergi-Repo für weitere Informationen.