Governance für die CDA-Leitfadenerstellung mit Art-Decor und Mediawiki

Aus HL7 Austria MediaWiki
Wechseln zu: Navigation, Suche
[unmarkierte Version][unmarkierte Version]
(Namespace)
(Struktur eines CDA-Implementierungsleitfadens)
Zeile 322: Zeile 322:
  
 
== Struktur eines CDA-Implementierungsleitfadens ==
 
== Struktur eines CDA-Implementierungsleitfadens ==
Um eine konsistente Vorgehensweise und Darstellung eines Implementierungsleitfadens zu gewährleisten, wird die folgende (minimale) Struktur empfohlen:
+
Ein Implementierungsleitfaden muss folgende Abschnitte enthalten:
 +
* eine [[Hilfe:Leitfaden_erstellen#Infobox |Infobox ]] (für den Leser nicht sichtbar)
 +
* die Hinweis, dass sich der Leitfaden [[Hilfe:Leitfaden_erstellen#Under_Construction|in Bearbeitung]] befindet (muss nach Fertigstellung entfernt werden)
 +
* [[Hilfe:Wiki#Strukturbespiel_einf.C3.BCgen|Strukturbeispiele]] in entsprechender Formatierung
 +
* ein [[#Typische_Gliederung_eines_Dokuments|Inhaltsverzeichnis]], das wie folgt strukturiert sein soll
  
TODO: STRUKTUR NOCH ABZUSTIMMEN!<br>
+
Optional stehen folgende Funktion bereit:
[https://wiki.hl7.at/index.php?title=Hilfe:Leitfaden_erstellen#Aufbau_eines_Implementierungsleitfadens "Aufbau eines Implementierungsleitfadens"].
+
* Vergabe eines [[Hilfe:Leitfaden_erstellen#Benutzerdefinierter_Titel|benutzerdefinierten Titels]]
 +
* [[Hilfe:Leitfaden_erstellen#SEO|Suchmaschinenoptimierung]]
 +
 
 +
Der textliche Teil eines Wiki Leitfadens, beinhaltet den eigentlichen Inhalt(/Beschreibung) eines Implementierungsleitfaden. Implementierungsleitfäden sind sehr lange Dokumente und umfassen meist eine Seitenanzahl von über 200 A4 Seiten. Deshalb ist es sinnvoll das Hauptdokument in Teildokumente zu unterteilen. Die Summe der Teildokumente ergibt somit einen Leitfaden.  
 +
 
 +
Es wird empfohlen, nur jene (allgemeinen) Textabschnitte in Teildokumente auszulagern, die zur Transklusion in andere Leitfäden verwendet werden könnten.
 +
 
 +
===Typische Gliederung eines Dokuments===
 +
Um eine konsistente Vorgehensweise bei der Erstellung und Darstellung eines Implementierungsleitfadens zu gewährleisten, wird folgende (minimale) Struktur vorgegeben:
 +
Ein Leitfaden wird typischerweise in folgende Abschnitte gliedert:
 +
* Informationen über dieses Dokument
 +
** Allgemeines
 +
** Sprachliche Gleichbehandlung
 +
** Verbindlichkeit
 +
** Zielgruppe
 +
** Hinweis auf verwendete Grundlagen
 +
** Danksagung
 +
** Hinweise zur Nutzung des Leitfadens
 +
** Revisionsliste
 +
** Weitere unterstützende Materialien
 +
** Bedienungshinweise
 +
** Impressum
 +
* Harmonisierung
 +
* Einleitung
 +
** Ausgangssituation
 +
** Zweck
 +
** Hierarchie der Implementierungsleitfäden
 +
* Anwendungsfälle
 +
* Administrative Daten (CDA Header)
 +
* Fachlicher Inhalt (CDA Body)
 +
* Technische Konformitätsprüfung
 +
** Schema-Prüfung
 +
** Schematron-Prüfung
 +
** Online-Validation von CDA-Dokumenten
 +
* Anhang
 +
** Referenzen
 +
** Revisionsliste
 +
 
 +
===Hauptdokument===
 +
Das Hauptdokument bildet den eigentlichen Leitfaden im Wiki ab und ist in verschiedene Abschnitte eingeteilt. Diese Abschnitte sind im Wiki sogenannten Teildokumente die in Summe den gesamten Leitfaden abbilden. Um die Teildokumente in das richtige Hauptdokument zu transkludieren, müssen diese einem bestimmten Namensbereich zugeordnet sein. 
 +
Teildokumente werden im Wiki folgendermaßen eingebunden: <br/>
 +
<pre>ILF:Harmonisierung</pre>
 +
 
 +
===Teildokument===
 +
Die Teildokumente enthalten den eigentlichen Text und müssen ebenfalls dem Namespace "ILF" zugeordnet.
  
 
== Schematische Template-Darstellung ==
 
== Schematische Template-Darstellung ==

Version vom 7. November 2019, 12:33 Uhr


Zusammenfassung

Dieses Dokument enthält Richtlinien zur Erstellung von CDA-Implementierungsleitfäden mit Art-Decor® und Mediawiki in Österreich.

Diese Richtlinien sollen als Empfehlungen und Best Practices dienen, um eine nationale und auch internationale Konformität und eine harmonisierte Verwendung der Tools zu gewährleisten. Sie entstanden in Zusammenarbeit mit Tony Schaller (CH) und der ELGA GmbH (AT). Dieses Dokument wird laufend aktualisiert, sobald die Nutzer der Tools einen neuen Konsens erzielen.

Weiters werden die notwendigen Verantwortlichkeiten und Prozesse definert, um klare Strukturen für die Zusammenarbeit zwischen Art-Decor und dem Wiki zu gewährleisten. Dies umfasst die Verantwortung für Art-Decor Repositories, Qualitätssicherung und den Support der Tools.

Einleitung

Anwendungsbereich

Das Dokument geht nicht auf die Modellierung von HL7 CDA-Dokumenten ein, sondern beschreibt hauptsächlich den Einsatz der Tools Art-Decor und Mediawiki, begleitet von Do's und Don'ts für Österreich. Sie definiert Regeln und Strukturen, die von allen Anwendern dieser Werkzeuge eingehalten werden müssen.

Weiterentwicklung des Dokuments

Dieses Dokument enthält die aktuellsten Fragen und Entscheidungen bezüglich der Arbeit mit Art-Decor und Mediawiki in Österreich und wird laufend angepasst.

Wichtiger Hinweis: Anfragen hinsichtlich der Änderung oder Erweiterung dieses Dokuments stellen Sie bitte an cda@elga.gv.at.


Art-Decor

Sprache

ELGA Implementierungsleitfäden werden in deutscher Sprache verfasst. Dazu gehören textuelle Beschreibungen im Wiki, Art-Decor-Templates und Datasets.

Eine Ausnahme bilden Template-Namen. Diese sind grundsätzlich in englischer Sprache zu vergeben, sodass die Bezeichnungen entsprechend ihrer Definition in den anderen (internationalen) CDA-Leitfäden beibehalten werden können und die Wiederverwendbarkeit bestehender Templates in weiteren Leitfäden erleichtert wird. Nur Template-Namen im CDA-Body werden auf deutsch vergeben, da diese den in den Arbeitsgruppen abgestimmten Titel der Sektion tragen sollen.

Verwendung von OIDs

Im Zusammenhang mit der Verwendung von OIDs sind die österreichischen Richtlinen einzuhalten (Object Identifier (OID) Konzept für das österreichische Gesundheitswesen). Das österreichische OID Portal ist zu finden unter OID Portal Österreich.

OIDs für Implementierungsleitfäden

Wichtiger Hinweis: Für jeden Implementierungsleitfaden muss (über das OID-Portal) eine OID unterhalb des Knotens 1.2.40.0.34.7 (eHealth-Austria/documents) registriert werden.

Falls Dokumente in aufeinander aufbauenden Versionen vorliegen, kann dafür darunter eine zusätzliche Ebene angelegt werden.


Beispiel:

  • 1.2.40.0.34.7.18: Implementierungsleitfaden Meldung von antimikrobieller Resistenzen
  • 1.2.40.0.34.7.18.1: Implementierungsleitfaden Meldung von antimikrobieller Resistenzen - Version 1.00

Art-Decor Root OIDs

Als neuer Root-Knoten für Art-Decor wird 1.2.40.0.34.6.0 (eHealth-Austria/services) verwendet. Er enthält OID für Value Sets und Templates.

Wichtiger Hinweis: Die Verwaltung der unter diesen Knoten liegenden Templates und Value-Sets unterliegt Art-Decor und benötigt daher keine Registrierung über das OID-Portal.

Die nächste freie OID für Templates und Value-Sets muss über die Art-Decor Governance Group, unter "List of Artefacts under this Governance Group" ermittelt werden.


Root OIDs für Templates

Alle Art-Decor Templates müssen unterhalb des OID-Knotes 1.2.40.0.34.6.0.11 liegen (eHealth-Austria/services/art-decor/templates). Die OIDs der Art-Decor Templates sollen außerdem entsprechend ihres CDA-Template-Typs aus folgender Unterknoten vergeben werden:

.0 Document-Level Template
.1 Header-Level Template
.2 Section-Level Template
.3 Entry-Level Template
.9 other CDA Fragment Template

Beispiele:

  • Header-Level-Template:
1.2.40.0.34.6.0.11.1.2 Author (eHealth-Austria/services/art-decor/templates/header/xxx)
  • Entry-Level-Template:
1.2.40.0.34.6.0.11.3.15 Antikörper-Bestimmung Data Processing Entry (eHealth-Austria/services/art-decor/templates/entry/xxx)

Root OIDs für Value Sets

Alle Art-Decor Value-Sets müssen unterhalb des OID-Knotes 1.2.40.0.34.6.0.10 liegen (eHealth-Austria/services/art-decor/value-sets).

Versionierung

Versionierung von Templates

Document-Level Templates

Für jede neue Version eines Document-Level Templates ist eine neue OID zu verwenden. Der Bezug zur alten OID ist anzugeben. Dadurch wird die Anwendung der korrekten Schematron-Regeln gemäß dem getesteten CDA-Dokument sichergestellt.

Alle anderen Templates

TODO

Versionierung von Value-Sets

Die OIDs der Value-Sets bleiben für alle Versionen gleich, werden aber durch das Gültigkeitsdatum "effectiveDate" unterschieden ("Gültig ab"). Darüber hinaus kann eine Value-Set ein offizielles Freigabedatum tragen.

Best Practices für die Erstellung und Pflege von Value Sets müssen angewendet werden, z.B. können Konzeptcodes hinzugefügt, aber nicht gelöscht werden, nur auf den Status "deprecated" gesetzt werden. Wenn sich die Gesamtbedeutung der Codes in einem Value-Set ändert, muss die neue Version des Value-Sets eine neue OID erhalten.

Bei der Aktualisierung eines Value Sets muss das effectiveDate auf das aktuelle Datum (Gültig ab-Datum) geändert werden.

Beispiel:
  • Versions-Label: YYYYMM.Korrekturnummer(-beta)

Hinweise:
Die "Korrekturnummer" ist optional: bei Änderungen innerhalb eines Monats wird diese angehängt.
"Beta" wird nur bei Value Sets verwendet, die noch bearbeitet werden. Sobald die Version gültig ist, wird das "beta" entfernt.

Repositories

Art-Decor Building Block Repository

In Österreich kann derzeit folgendes bereichsspezifische Building Block Repository (BBR) verwendet werden:

  • ATCDABBR: Dies soll in Zukunft alle für Österreich relevanten Basis-Templates enthalten, die für spezifische Anwendungen (e-Health und ELGA) in die einzelnen Projektverzeichnisse abgeleitet verwendet werden können.
Derzeit sind Templates für den CDA-Header sowie Basis-Templates für den e-Impfpass vorhanden. Dieses Verzeichnis wird laufend erweitert. Nach Fertigstellung von CDA-Leitfäden sollen entsprechende Templates in dieses Verzeichnis übernommen werden.
Die im ATCDABBR befindlichen Templates dürfen nur von einem eingeschränkten Benutzerkreis bearbeitet werden.
Verantwortlichkeiten und Prozesse sind im Kapitel #Revision beschrieben.

Projektverzeichnisse

  • e-Impfpass (Pilot)
  • Basisleitfäden (alte Versionen)
  • TODO

Governance Groups

Governance-Gruppen sind organisatorische Einheiten, die dazu dienen, die Verantwortung für Artefakte in Art-Decor darzustellen. Unter Governance-Gruppen sind alle Projekte der Gruppe sichtbar, sowie alle angelegten Artefakte mit OID, Displayname, #Artefaktstatus, BBR und Projekte, die das Template oder Value-Set referenzieren.

Artefaktstatus

In einem Repository werden Artefakte zunächst im Status "Entwurf" erstellt. Nach Abschluss, Überprüfung und Bestätigung kann der Status eines Artefakts im Repository gemäß den Regeln der zuständigen Governance-Gruppe geändert werden (siehe "Changing the status of a template"). Das Kapitel #Repositories enthält die Beschreibung des detaillierten Prozesses und der Verantwortlichkeiten.

Das folgende Zustandsdiagramm zeigt die Standardzustände und möglichen Übergänge für ein Artefakt in Art-Decor:

Governance state machine.png

[Abbildung 1] Default state diagram for Art-Decor artefacts

TODO: Beschreibung, wann von draft in active wechseln.
TODO: Example for CH anpassen, nicht verwendete Zustände aus Tabelle entfernen


[Tabelle 1] Art-Decor state machine

Status Action Trigger / Description Example for CDA-CH Responsibility
Kyellow.png draft activate Artefact is finished and it is considered as final (no review needed). n/a for CDA-CH as review necessary. Developer
consider If an artefact is considered to be moved into a repository, this action is applied and the artefact has to be reviewed by the owner/team of the repository. final draft for a CDA-CH V2 template ready to review. Developer (info to the Reviewer)
cancel If an artefact is not further developed, it is cancelled. any developed draft template not to be used anymore. Developer
Korange.png pending activate Upon decision of the review team. CDA-CH V2 template has been reviewed within HL7 Switzerland and was considered to be ready for release. Review team of the repository.
reject If the artefact is considered as not appropriate for the repository, it's rejected. HL7 Switzerland does not consider the template. Review team of the repository.
Kpurple.png rejected Decision necessary for what next status applies, it is recommended to set the status to draft and re-evaluate it for a repository or set is as active only within the project. As appropriate, propose to set it to draft again or move it to another BBR. Developer
Kgreen.png active review Maintenance or update of a project/repository. Review CDA-CH template to consider it for CDA-CH v2. Repository / Project owner
retire In case of a new version, the old version is retired in order to have only one valid version of an artefact. A CDA-CH template is not used anymore or replaced by another one. Repository / Project owner
Korange.png pre-publication review reactivate If updated and considered as final by the responsible person, the artefact is re-activated. template is reviewed within HL7 Switzerland and considered to be ready for release. Repository / Project owner
retire A CDA-CH template is not used anymore or replaced by another one.

Dokumentation

Templates

Elemente und Attribute, die im Template verwendet werden, sind zu dokumentieren. Die Beziehung zu anderen Templates ist anzugeben, um festzuhalten, wie sie sich zueinander verhalten (z.B. Spezialisierung, Anpassung usw.).

TODO: prüfen
Other elements that were in addition available according the HL7 CDA standard shall not be mentioned in the Art-Decor template.

  • Open vs. Closed Templates

Standard-Referenzen

Daten- und Template-Elemente sollen in ihrem Label zu der entsprechenden Spezifikation verlinken, auf der sie basieren (z.B. IHE PHARM, Kap. 4.4). Dies liegt in der Verantwortung des Entwicklers.

Datasets

Die Verwendung von Art-Decor-Datensätzen wird für neue Projekte empfohlen. Diese bilden die funktionalen Anforderungen an das Projekt ab und sind Diskussionsgrundlage bei Fachexpertengesprächen (erfordern kein technisches Hintergrundwissen).
Wenn möglich, soll von bereits vorhanden Elementen geerbt werden und diese, falls erforderlich, enterbt und den speziellen Anforderungen angepasst werden.
Folgende Inhalte eines Dataset-Elements sind mindestens anzugeben:

  • Name
  • Beschreibung
  • Datentyp


wenn vorhanden:

  • Auswahllisten
  • Link zu kodierten Konzepten / Value-Sets (Terminologien)

Szenarios

Das Erstellen von Transaktionen im Rahmen von Szenarios ist für die Generierung von Schematron-Regeln zwingend erforderlich.
Die Angabe von Kardinalität (optional, wiederholbar) und Konformität (erforderlich, obligatorisch) für die einzelnen Elemente des Datasets wird empfohlen.

Dataset-Mapping

Die Zuordnung von Datensatz-Elementen und erstellten Templates wird empfohlen. Dadurch sind alle mit einem Template assoziierten Konzepte in der Template-Beschreibung zusammengefasst, sowie direkt beim assoziierten CDA-Element bzw. Attribut des Templates ersichtlich. Dies dient der Kontrolle, dass alle erforderlichen Datensatz-Elemente in den Templates modelliert wurden.

Namenskonventionen

Versions-Label

Im Version-Label wird prinzipiell die Jahrzahl der Verabschiedung des Templates, des Value-Sets bzw. des Datasets eingetragen. Sollte die Angabe des Jahres nicht ausreichend sein, wird sie mit .Monat ergänzt. Gleiches gilt für tagesaktuelle Versionen.

Beispiele:
  • 2019
  • 2019.01
  • 2019.01.16

Item-Label

Der im Item-Label des Document-Level Templates angegebene Name wird von Art-Decor später automatisch als Name für das entsprechende Schematron verwendet, z.B. „elgaimpf‑UpdateImmunisierungsstatus“.

Namenskonventionen für Templates

Die Namen von Templates werden wie folgt angegeben: [Präfix]_[Template-Typ]_[ElementName]
Wobei folgendes gilt:

[Präfix]
Als Präfix dient das Projektkürzel (Name des Repositories) in CamelCase-Notation, z.B. "atcdabrr"
[Template-Typ]
Der Template-Typ muss einen der folgenden Template-Typen enthalten:
  • "document"
  • "header"
  • "section"
  • "entry"
  • "other"
[ElementName]
Bezeichnung des Templates in CamelCase-Notation. Als Trenner fungieren Unterstriche "_".

Beispiele:

  • Template einer unkodierten Sektion im Repository AT-CDA-BBR:
Name: "atcdabrr_section_FruehereErkrankungUnkodiert"
DisplayName: "Frühere Erkrankungen - unkodiert"
  • Template einer kodierten Sektion im ELGA e-Impfpass Repository:
Name: "eimpf_section_ImpfrelevanteErkrankungenKodiert"
DisplayName: "Impfrelevante Erkrankungen - kodiert"
  • Document Level Template im ELGA e-Impfpass Repository:
Name: "eimpf_document_KompletterImmunisierungsstatus"
DisplayName: "Kompletter Immunisierungsstatus"
  • Entry im AT-CDA-BBR:
Name: "atcdabbr_entry_Immunization"
DisplayName: "Immunization Entry"
  • Template aus der Kategorie "Other" im AT-CDA-BBR:
Name: atcdabbr_other_TextElementWithReferenceToNarrativeText
DisplayName: Narrative Text Reference

Namenskonventionen für Value-Sets

Die Namen von Value-Sets werden wie folgt angegeben: [Präfix]_[ValueSetsName]_VS

"Displayname" und "Name" des Value-Sets sind identisch.

Beispiel:
  • Name: eimpf_Abrechenbarkeit_VS
  • Wiedergabename: eimpf_Abrechenbarkeit_VS

Mediawiki

Leitfaden erstellen

Wichtige Informationen hinsichtlich der technischen Erstellung eines CDA-Leitfadens mit Mediawiki sind unter "Leitfaden erstellen" nachzulesen.

Namespace

Der Verwendung von Namespaces ist wesentlich für Versionierung der Wiki-Seiten mit Flagged Revisions.

Wichtiger Hinweis:Alle Seiten von CDA-Leitfäden im Namespace ["ILF"] erstellt werden.


Struktur eines CDA-Implementierungsleitfadens

Ein Implementierungsleitfaden muss folgende Abschnitte enthalten:

Optional stehen folgende Funktion bereit:

Der textliche Teil eines Wiki Leitfadens, beinhaltet den eigentlichen Inhalt(/Beschreibung) eines Implementierungsleitfaden. Implementierungsleitfäden sind sehr lange Dokumente und umfassen meist eine Seitenanzahl von über 200 A4 Seiten. Deshalb ist es sinnvoll das Hauptdokument in Teildokumente zu unterteilen. Die Summe der Teildokumente ergibt somit einen Leitfaden.

Es wird empfohlen, nur jene (allgemeinen) Textabschnitte in Teildokumente auszulagern, die zur Transklusion in andere Leitfäden verwendet werden könnten.

Typische Gliederung eines Dokuments

Um eine konsistente Vorgehensweise bei der Erstellung und Darstellung eines Implementierungsleitfadens zu gewährleisten, wird folgende (minimale) Struktur vorgegeben: Ein Leitfaden wird typischerweise in folgende Abschnitte gliedert:

  • Informationen über dieses Dokument
    • Allgemeines
    • Sprachliche Gleichbehandlung
    • Verbindlichkeit
    • Zielgruppe
    • Hinweis auf verwendete Grundlagen
    • Danksagung
    • Hinweise zur Nutzung des Leitfadens
    • Revisionsliste
    • Weitere unterstützende Materialien
    • Bedienungshinweise
    • Impressum
  • Harmonisierung
  • Einleitung
    • Ausgangssituation
    • Zweck
    • Hierarchie der Implementierungsleitfäden
  • Anwendungsfälle
  • Administrative Daten (CDA Header)
  • Fachlicher Inhalt (CDA Body)
  • Technische Konformitätsprüfung
    • Schema-Prüfung
    • Schematron-Prüfung
    • Online-Validation von CDA-Dokumenten
  • Anhang
    • Referenzen
    • Revisionsliste

Hauptdokument

Das Hauptdokument bildet den eigentlichen Leitfaden im Wiki ab und ist in verschiedene Abschnitte eingeteilt. Diese Abschnitte sind im Wiki sogenannten Teildokumente die in Summe den gesamten Leitfaden abbilden. Um die Teildokumente in das richtige Hauptdokument zu transkludieren, müssen diese einem bestimmten Namensbereich zugeordnet sein. Teildokumente werden im Wiki folgendermaßen eingebunden:

ILF:Harmonisierung

Teildokument

Die Teildokumente enthalten den eigentlichen Text und müssen ebenfalls dem Namespace "ILF" zugeordnet.

Schematische Template-Darstellung

TODO: evtl. Grafikvorlage

Revision

TODO:

Releases

Art-Decor

TODO

Wiki

Check before finalizing

Thew folowing checks help to identify possible errors or missing includes from Art-Decor. Templates from other repositories than under the governance from eHealth Suisse need to be imported separatly. Please send the necessary OID and related project information to the Art-Decor Support.

  • Perform search for:
    • "/dynamic"
    • "/static"
    • "Cannot find"
    • ...

Afterwards: Create a revision according to Wiki revisions.

Verantwortliche Personen

Support for Art-Decor

TODO

Governance Groups

TODO

Repositories

TODO

Wiki

TODO

Quality Assurance & Review =

Art-Decor Repository

TODO

Implementation Guides

TODO

ELGA Implementierungsleitfäden

TODO: Prozess # muss eingehalten werden

Anhang

Links

Abbildungsverzeichnis

  1. Default state diagram for Art-Decor artefacts

Tabellenverzeichnis

  1. Art-Decor state machine

Zur Diskussion stehende Änderungsvorschläge

TODO