Hilfe:Implementierungsleitfaden: Unterschied zwischen den Versionen

Aus Hl7wiki
Wechseln zu: Navigation, Suche
(→‎Angaben zu HL7 V3 Klassen-Attributen)
(→‎Voraussetzungen)
 
(55 dazwischenliegende Versionen von 4 Benutzern werden nicht angezeigt)
Zeile 7: Zeile 7:
  
 
==Grundsätzliches und Gute Praxis der Wiki-Leitfäden==
 
==Grundsätzliches und Gute Praxis der Wiki-Leitfäden==
 +
 +
Alle Seiten des Wiki unterliegen dem ''Flagged Revisions'' Verfahren, das es ermöglicht, Seitenversionen zu markieren sowie eine stabile Seitenversion festzulegen (https://www.mediawiki.org/wiki/Extension:FlaggedRevs). Die Seiten werden von so genannten Sichtern freigegeben.
 +
 
Leitfäden sind meist lange Dokumente. Es ist deshalb sinnvoll, diese in Teildokumente zu unterteilen, die dann zu einem einzigen Leitfaden zusammengefügt werden.
 
Leitfäden sind meist lange Dokumente. Es ist deshalb sinnvoll, diese in Teildokumente zu unterteilen, die dann zu einem einzigen Leitfaden zusammengefügt werden.
  
Zeile 85: Zeile 88:
 
Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen.
 
Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen.
 
{{AlertBox|
 
{{AlertBox|
−
Dazu ist es nicht ausreichend, dass den Dokumenten ein Präfix mit abschließendem ''':''' vorangestellt wird, sondern die ausgezeichneten Wiki-Namespaces müssen gesondert vom Administrator '''vor Anlegen eines Dokuments''' eingetragen werden, damit sie als solche bekannt sind.}}
+
Dazu ist es nicht ausreichend, dass den Dokumenten ein Präfix mit abschließendem ''':''' vorangestellt wird, sondern die ausgezeichneten Wiki-Namespaces müssen gesondert vom Administrator '''vor Anlegen eines Dokuments''' eingetragen werden, damit sie als solche bekannt sind. Die Eintragungen nimmt der Administrator auf in der Datei MediaWiki:ExtraNamespaces vor.}}
  
 
Beispiel:  
 
Beispiel:  
Zeile 97: Zeile 100:
  
 
Beispiele: Der Leitfaden ''Digitaler Mutterpass auf der Basis von CDA R2'' ist in seine Kapitel aufgeteilt. Bei Leitfaden ''Datentypen'' ist die ebenso der Fall, zusätzlich sind hier die Beschreibungen der einzelnen Datentypen auch noch als kleine Teildokumente vorhanden, damit man ihren Text in anderen Dokumenten transkludieren oder referenzieren kann.
 
Beispiele: Der Leitfaden ''Digitaler Mutterpass auf der Basis von CDA R2'' ist in seine Kapitel aufgeteilt. Bei Leitfaden ''Datentypen'' ist die ebenso der Fall, zusätzlich sind hier die Beschreibungen der einzelnen Datentypen auch noch als kleine Teildokumente vorhanden, damit man ihren Text in anderen Dokumenten transkludieren oder referenzieren kann.
 +
 +
===Typische Kapitel/Abschnitte===
 +
Ein typischer Leitfaden hat die folgenden Abschnitte bzw. Kapitel. Abschnitte in (Klammern) sind nur zu nennen, wenn es unbedingt notwendig erscheint.
 +
*Dokumenteninformation
 +
**Impressum
 +
**Ansprechpartner
 +
**Disclaimer
 +
**Autoren
 +
**Copyright-Hinweis, Nutzungshinweise
 +
**Danksagung
 +
*Einleitung
 +
**Rationale
 +
**Zielsetzung
 +
**Vorarbeiten
 +
**Abgrenzung
 +
*(Grundlagen)
 +
*Struktureller Aufbau
 +
**Verwendeter Standard
 +
**Übersicht CDA Header und Body
 +
**(Verwendung von Templates)
 +
*CDA Document Level Templates
 +
*CDA Header Level Templates
 +
*CDA Section Level Templates
 +
*CDA Entry Level Templates
 +
*Terminologien
 +
**Value Sets
 +
**Kodesysteme
 +
*Anhang (nicht normativ)
 +
**Beschreibung der Use Cases und Storyboards
 +
**Lizenzen
 +
*Referenzen
  
 
==Erstellen / Umsetzen der Spezifikation==
 
==Erstellen / Umsetzen der Spezifikation==
 
Grundsätzlich können die üblichen Mediawiki-Möglichkeiten genutzt werden. Im Zuge der Vereinheitlichung von Leitfäden, ihrem Layout und ihrer möglichen Wiedergabe als PDF sind einige Vorschläge und Regeln zu beachten.
 
Grundsätzlich können die üblichen Mediawiki-Möglichkeiten genutzt werden. Im Zuge der Vereinheitlichung von Leitfäden, ihrem Layout und ihrer möglichen Wiedergabe als PDF sind einige Vorschläge und Regeln zu beachten.
 +
 +
===Hochauflösende Bilder===
 +
Grundsätzlich sollten Bilder im SVG Format oder als JPG oder PNG mit mindestens 200dpi eingebunden werden, damit sich in der Druckausgabe damit noch etwas anfangen lässt.
 +
 +
Ohne weitere Maßnahmen werden eingebundene Bilder so im PDF wiedergegeben, wie sie angegeben sind. Das heißt, dass ein Bild, das hochauflösend ist, aber auf nur 300px herunterskaliert ist, auch nur in der schlechteren Auflösung gerastert in in das Druckdokument übernommen wird. Ein übliches Beispiel:
 +
<syntaxhighlight lang="xml">
 +
[[Datei:Bild.jpg|300px]]
 +
</syntaxhighlight>
 +
Um vorhandene hochauflösende Bilder dennoch im PDF mit der maximalen Auflösung wiederzugeben, besteht das Template {{HL7img|bilddatei|xpx|ppc}, wobei eine Bilddatei ''bilddatei'' (vorzugsweise SVG bzw. JPG oder PNG mit mindestens 200dpi) im Onlineformat mit ''xpx'' Pixeln skaliert wird (wie in einer Image-Anweisung) und für die Druckausgabe ''ppc'' % der Seitenbreite einnimmt. Die Skalierung für die Druckausgabe ist dabei wesentlich verlustfreier, da von dem hochauflösenden Original bei der Pdf-Konvertierung skaliert wird. Das vorige Beispiel sieht dann im Quelltext zum Beispiel so aus:
 +
<syntaxhighlight lang="xml">
 +
{{HL7img|Datei:Bild.jpg|300px|80%}}
 +
</syntaxhighlight>
  
 
===Verwendung von Hinweisboxen mit Symbolen===
 
===Verwendung von Hinweisboxen mit Symbolen===
 +
Grundsätzlich sollte erwogen werden, dass alle Entwürfe wie folgt gekennzeichnet sind.
 +
<syntaxhighlight lang="xml">
 +
{{Underconstruction}}
 +
</syntaxhighlight>
 +
Das ergibt:
 +
{{Underconstruction}}
 +
 
Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden.
 
Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden.
 
{{:Legenda/Boxen}}
 
{{:Legenda/Boxen}}
 +
 +
Beispiel eines Wiki-Textes:
 +
<syntaxhighlight lang="xml">
 +
{{FAQBox|Diese Information wird in diesem Leitfaden zunächst nicht verwendet.}}
 +
</syntaxhighlight>
 +
 +
Die anderen Stichwort lassen sich aus nachfolgender Liste ableiten.
  
 
Siehe dazu die folgenden Vorlagen:
 
Siehe dazu die folgenden Vorlagen:
Zeile 115: Zeile 175:
 
* [[Vorlage:HL7deBox]]
 
* [[Vorlage:HL7deBox]]
 
* [[Vorlage:HL7intBox]]
 
* [[Vorlage:HL7intBox]]
 +
* [[Vorlage:BestPracticeBox]]
 +
 +
== Literatur- und Quellenhinweise, Referenzen, Abbildungs- und Tabellenunterschriften==
 +
Literatur- und andere Quellenhinweise werden über das ref-Element angegeben.
 +
<syntaxhighlight lang="xml">
 +
Es wurde eine XML<ref>Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/</ref>
 +
bzw. JSON <ref>JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org</ref>
 +
Entwicklung angestoßen.
 +
</syntaxhighlight>
 +
<div style="border: 1pt grey solid; padding: 10px;">
 +
Es wurde eine XML<ref>Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/</ref>
 +
bzw. JSON <ref>JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org</ref>
 +
Entwicklung angestoßen.
 +
</div>
 +
Abbildungen und Tabellen können mit automatisch durchnummerierten Referenzen versehen werden. Hierzu werden die Schlüsselworte "Abbildung" bzw "Tabelle" verwendet.
 +
<syntaxhighlight lang="xml">
 +
{{HL7img|Ukfpmp1.jpg|300px|40%}}
 +
<ref group="Abbildung">Die ist der Text, der bei der Bildreferenz angezeigt wird</ref> ''Dies ist der erklärende Text zur Abbildung als Bildunterschrift''
 +
</syntaxhighlight>
 +
Hier wird eine Abbildung referenziert und mit der entsprechenden Bildunterschrift versehen.
 +
<div style="border: 1pt grey solid; padding: 10px;">
 +
{{HL7img|Ukfpmp1.jpg|300px|40%}}
 +
<ref group="Abbildung">Die ist der Text, der bei der Bildreferenz angezeigt wird</ref> ''Dies ist der erklärende Text zur Abbildung als Bildunterschrift''
 +
</div>
 +
<syntaxhighlight lang="xml">
 +
{| class="hl7table"
 +
|-
 +
!Section!!LOINC-Code
 +
|-
 +
|... || ...
 +
|}
 +
<ref group="Tabelle">Text der bei der Tabellenreferenz angezeigt wird</ref> ''Dies ist der erklärende Text als Tabellenunterschrift''
 +
</syntaxhighlight>
 +
 +
Hier ist eine Tabelle mit entsprechender Tabellenunterschrift aufgeführt.
 +
<div style="border: 1pt grey solid; padding: 10px;">
 +
{| class="hl7table"
 +
|-
 +
!Section!!LOINC-Code
 +
|-
 +
|... || ...
 +
|}
 +
<ref group="Tabelle">Text der bei der Tabellenreferenz angezeigt wird</ref> ''Dies ist der erklärende Text als Tabellenunterschrift''
 +
</div>
 +
Am Ende des Dokuments/Abschnitts muss dazu das entsprechende Referenz-Tag eingelöst werden, um die Referenzen alle aufzulisten.
 +
 +
<syntaxhighlight lang="xml">
 +
Referenzen
 +
<references/>
 +
 +
Abbildungen
 +
<references group="Abbildung" />
 +
 +
Tabellen
 +
<references group="Tabelle" />
 +
</syntaxhighlight>
 +
<div style="border: 1pt grey solid; padding: 10px;">
 +
Referenzen
 +
<references/>
 +
 +
Abbildungen
 +
<references group="Abbildung" />
 +
 +
Tabellen
 +
<references group="Tabelle" />
 +
</div>
 +
Wiederholentlich genutzt Referenzen können einen Namen bekommen
 +
<syntaxhighlight lang="xml">
 +
<ref name="xyzref">Die Referenz</ref>
 +
</syntaxhighlight>
 +
...und an anderer Stelle einfach erneut durch Nennung des Namens
 +
<syntaxhighlight lang="xml">
 +
<ref name="xyzref"/>
 +
</syntaxhighlight>
 +
...referenziert werden.
  
 
===Einbinden von farbigen Boxen für verschiedene Zwecke===
 
===Einbinden von farbigen Boxen für verschiedene Zwecke===
Zeile 129: Zeile 264:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
====Storyboards im laufenden Text====
 
====Storyboards im laufenden Text====
−
...sollten markiert werden mit einer violetten Box.
+
...sollten markiert werden mit einer violetten Box (BeginPurpleBox, EndPurpleBox):
 
{{BeginPurpleBox|Ich bin ein Überschrift}}
 
{{BeginPurpleBox|Ich bin ein Überschrift}}
 
Dies ist der Text in der Box
 
Dies ist der Text in der Box
 
{{EndPurpleBox}}
 
{{EndPurpleBox}}
 +
 
====Weitere Boxen====
 
====Weitere Boxen====
−
...stehen mit BeginGreenBox/EndGreenBox und BeginRedBox/EndRedBox zur Verfügung.
+
...stehen mit BeginGreenBox / EndGreenBox, BeginRedBox / EndRedBox und BeginGrayBox / EndGrayBox zur Verfügung.
 
{{BeginGreenBox|Ich bin eine Überschrift}}
 
{{BeginGreenBox|Ich bin eine Überschrift}}
 
Dies ist der Text in der Box
 
Dies ist der Text in der Box
Zeile 141: Zeile 277:
 
Dies ist der Text in der Box
 
Dies ist der Text in der Box
 
{{EndRedBox}}
 
{{EndRedBox}}
 +
{{BeginGrayBox|Ich bin eine Überschrift}}
 +
Dies ist der Text in der Box
 +
{{EndGrayBox}}
  
 
===XML-Darstellung===
 
===XML-Darstellung===
Zeile 168: Zeile 307:
  
 
===Angaben zu HL7 V3 Klassen-Attributen===
 
===Angaben zu HL7 V3 Klassen-Attributen===
−
Klassen-Attribute in HL7 V3 werden grundsätzlich über die Vorlage [[Vorlage:AttDesc|AttDesc]] in die Spezifikationen eingebunden.
+
{{NoteBox|Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft der Output des Tools ART-DECOR für die Objekt- und Attributdefinition verwendet. Dabei können Templates einfach in den Wiki-Originaltext transkludiert werden. Voraussetzung dafür ist natürlich, dass die Templates in ART-DECOR eingebracht sind. Mehr dazu unter [[Hilfe:Templates]].
 +
 
 +
Zum Beispiel ergibt
 +
<syntaxhighlight lang="text">
 +
{{:1.2.276.0.76.10.2010/dynamic}}
 +
</syntaxhighlight>
 +
...folgende Ausgabe
 +
{{:1.2.276.0.76.10.2010/dynamic}}
 +
}}
 +
 
 +
Klassen-Attribute in HL7 V3 werden grundsätzlich über die Vorlage [[Vorlage:AttDesc|AttDesc]] in die Spezifikationen eingebunden. Führend ist hier, ob ein Klassen-Attribut als XML-Element oder XML-Attribut wiedergegeben wird.
  
−
Wiki-Text:
+
Wiki-Text für Elemente:
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
−
{ {AttDesc
+
{{AttDesc
 
| ae = elm
 
| ae = elm
 
| rim = act, ent, role, part
 
| rim = act, ent, role, part
−
| name = id
+
| name = Encounter
−
| desc = Id des Dokuments
+
| desc = Begegnung
−
| dt = II
+
| dt =  
 
| card = 1..1
 
| card = 1..1
 
| conf = M
 
| conf = M
Zeile 187: Zeile 336:
 
| ae = elm
 
| ae = elm
 
| rim = act
 
| rim = act
−
| name = id
+
| name = Encounter
−
| desc = Id des Dokuments
+
| desc = Begegnung
−
| dt = II
+
| dt =  
 
| card = 1..1
 
| card = 1..1
 
| conf = M
 
| conf = M
Zeile 196: Zeile 345:
 
Im Falle einer Einschränkung auf ein Attribut kann dieses separat oder direkt beim Attribut niedergelegt werden.
 
Im Falle einer Einschränkung auf ein Attribut kann dieses separat oder direkt beim Attribut niedergelegt werden.
  
−
Wiki-Text:
+
Wiki-Text für Attribute:
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
 
{{AttDesc
 
{{AttDesc
−
| ae = elm
+
| ae = att
 
| rim = act, ent, role, part
 
| rim = act, ent, role, part
 
| name = id
 
| name = id
 
| desc = Id des Dokuments
 
| desc = Id des Dokuments
−
{{ ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten. }}
 
 
| dt = II
 
| dt = II
 
| card = 1..1
 
| card = 1..1
Zeile 212: Zeile 360:
 
Beispiel:
 
Beispiel:
 
{{AttDesc
 
{{AttDesc
−
| ae = elm
+
| ae = att
 
| rim = act
 
| rim = act
 
| name = id
 
| name = id
 
| desc = Id des Dokuments
 
| desc = Id des Dokuments
 +
 
{{ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.}}
 
{{ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.}}
 
| dt = II
 
| dt = II
Zeile 224: Zeile 373:
 
oder auch als:
 
oder auch als:
 
{{AttDesc
 
{{AttDesc
−
| ae = elm
+
| ae = att
 
| rim = act
 
| rim = act
 
| name = id
 
| name = id
Zeile 232: Zeile 381:
 
| conf = M
 
| conf = M
 
}}
 
}}
 +
 
{{ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.}}
 
{{ConstraintBox|Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.}}
 +
 +
==Strukturierung von Leitfäden und deren Inhalten==
 +
 +
===Abschnitte (Sektionen und Entries)===
 +
 +
* Die Abschnitte werden alle beginnend auf der zweiten Ebene formatiert.
 +
* Überschrift2: "Section: <Beschreibung>" bzw. "Entry: <Beschreibung>"
 +
* Die Abschnitte enthalten alle zu Beginn einen kleinen Header, der die Identifikation erleichtert:
 +
 +
====Template-Metadaten-Tabelle====
 +
 +
{{NoteBox|Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft art-decor für die Objekt- und Attributdefinition verwendet}}
 +
 +
{| class="hl7table"
 +
|bgcolor="ddddff"| || bgcolor="ddddff"| Template-Metadaten
 +
|-
 +
|bgcolor="ddddff"|Template-Typ|| Header oder Section oder Entry
 +
|-
 +
|bgcolor="ddddff"|Template ID|| <OID für das Template>
 +
|-
 +
|bgcolor="ddddff"|generischeres Template || <Verweis auf das Template>
 +
|-
 +
|bgcolor="ddddff"|genutztes Templates || <Verweis auf das Template>
 +
|-
 +
|bgcolor="ddddff"|nutzende Templates || <Verweis auf das Template>
 +
|-
 +
|bgcolor="ddddff"|abgeleitete Templates || <Verweis auf das Template>
 +
|-
 +
|bgcolor="ddddff"|Schwester-Templates ||  <Verweis auf das Template>
 +
|-
 +
|bgcolor="ddddff"|Generelle Beschreibung||  < direkte Kurzbeschreibung >
 +
|-
 +
|bgcolor="ddddff"|allg. Erläuterung||  < Verweis auf eine allgemeine Erläuterungsseite >
 +
|-
 +
|bgcolor="ddddff"|Verhältnis zu IHE||  dt.Übersetzung oder Ergänzung oder neu
 +
|-
 +
|bgcolor="ddddff"|Ballotierungsstatus||  < Status der Verabschiedung >
 +
|-
 +
|bgcolor="ddddff"|Erweiterbarkeit||  offen oder geschlossen
 +
|}
 +
 +
* Nach dem Template folgt die Beschreibung mit einer optionalen kleinen Grafik, die den Zusammenhang zwischen den einzelnen Klassen erläutert.
 +
* Danach folgt eine Tabelle, in der die Klassen und ihre Attribute aufgelistet werden:
 +
** Diese Tabelle wird zukünftig durch ART-DECOR ersetzt. Bis dahin dient sie der Sammlung der notwendigen Informationen.
 +
** Lvl: Schachtelungstiefe gemäß XML-Darstellung
 +
** RIM-Element (Attribute werden mit "@" dargestellt.
 +
** Hier sollte sich auf die Inhalte konzentriert werden.
 +
 +
{| class="hl7table"
 +
! Lvl
 +
! RIM
 +
! Name
 +
! DT
 +
! Kard
 +
! Conf
 +
! Beschreibung
 +
 +
|-
 +
|1
 +
|bgcolor="ff8888"|act
 +
|observation
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
|2
 +
|bgcolor="ff8888"|act
 +
|templateID
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
|2
 +
|bgcolor="ff8888"|act
 +
|code
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
|2
 +
|bgcolor="ff8888"|act
 +
|value
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
| 2
 +
|bgcolor="ffaaaa"| rel
 +
|
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
| 1
 +
|bgcolor="ccffff"| part
 +
|
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
| 2
 +
|bgcolor="ffff88"| role
 +
|
 +
|
 +
|
 +
|
 +
|
 +
 +
|-
 +
|4
 +
|bgcolor="88ff88"|ent
 +
|
 +
|
 +
|
 +
|
 +
|
 +
 +
|}
 +
 +
 +
* Lvl
 +
** Schachtelungsebene für XML
 +
* RIM
 +
** farbliche Kodierung des RIM-Elementes
 +
* Name
 +
** das RIM-Element, d.h. Element oder Attribut-Name (letzterer mit "@" als Präfix)
 +
* DT
 +
** Datentyp mit Nutzung von nationalen Flavors
 +
* Kard
 +
** Kardinalität
 +
* Conf
 +
** M = Mandatory (MUSS-Feld mit gefülltem Inhalt, Null-Flavors nicht erlaubt
 +
** R = required (MUSS-Feld mit Null-Flavors)
 +
** opt. = optional (KANN-Feld)
 +
** NP = not Permitted (verboten)
 +
* Beschreibung
 +
** textliche Beschreibung des Elements
 +
* An die tabellarische Darstellung der Inhalte schließen sich die Vokabularien an.
 +
* Zu guter Letzt kommt ein Beispiel (in XML).
 +
 +
 +
{{NoteBox|
 +
Bei Wiederverwendung von anderen Templates sollten die Links aufgeführt und die Angaben auf ein Minimum reduziert werden.
 +
}}
 +
 +
==Ballotierungsstatus==
 +
 +
Folgende Status werden im Idealfall bei der Ballotierung durchlaufen. Daraus ist ersichtlich wie weit die Arbeiten zu den Templates, Implementierungsleitfäden oder Spezifikationen im Allgemeinen abgeschlossen sind. Der jeweilige Status lässt sich aus der Metadaten-Tabelle (z.B. Template-Metadaten-Tabelle) entnehmen.
 +
 +
* Entwurf (draft)
 +
* in Abstimmung (review)
 +
* Verabschiedet (active)
 +
* Veraltet (retired)
 +
 +
===Ballotierungsstatus für Dokumente/Implementierungsleitfäden===
 +
(s.o)
 +
 +
===Ballotierungsstatus für Templates===
 +
(s.o)

Aktuelle Version vom 17. April 2019, 10:51 Uhr

Wie übertrage bzw. erstelle ich einen Implementierungsleitfaden im HL7 Wiki

Einleitung

HL7 Deutschland hat sich zum Ziel gesetzt, alle Implementierungsleitfäden und dazugehörige Dokumente, Terminologien, Templates und sonstiges im Wiki verfügbar zu machen. Um einen Leitfaden hier zu veröffentlichen, sind eine Reihe von Voraussetzungen zu erfüllen und die Leifäden bzw. die zugehörigen Teildokumente müssen nach bestimmten Kriterien erstellt werden, um als Leitfäden oder Teilen davon erkannt zu werden und um die Extraktionsmöglichkeit als PDF-Dokument zu ermöglichen.

Wiki-Hilfe

Das Wiki bietet selbst eine Einführung, wie grundsätzlich mit einem Wiki gearbeitet wird und welche Markups zur Verfügung stehen: http://de.wikipedia.org/wiki/Hilfe:Textgestaltung

Grundsätzliches und Gute Praxis der Wiki-Leitfäden

Alle Seiten des Wiki unterliegen dem Flagged Revisions Verfahren, das es ermöglicht, Seitenversionen zu markieren sowie eine stabile Seitenversion festzulegen (https://www.mediawiki.org/wiki/Extension:FlaggedRevs). Die Seiten werden von so genannten Sichtern freigegeben.

Leitfäden sind meist lange Dokumente. Es ist deshalb sinnvoll, diese in Teildokumente zu unterteilen, die dann zu einem einzigen Leitfaden zusammengefügt werden.

Hauptdokument

Das Hauptdokument enthält folgende verpflichtend anzugebenden Teile:

  • eine Infobox Dokument (auszufüllende Vorlage)
  • bei Bedarf eine Infobox Ballot (als Begin und End Vorlage) mit den bisherigen Stufen des Dokuments im Abstimmungsprozess
  • bei Bedarf eine Liste von Kontributoren dieses Leitfadens, also "vorgelegt von", "mit Beiträgen von", etc.
  • die trankludierten separat angelegten Abschnitte, eingefügt mit der Vorlage HL7transclude
  • ein abschließendes <references/> Tag zum Aufführen aller in Haupt- und Nebendokumenten erwähnten Referenzen.

aus werden die einzelnen Teildokumente transkludiert.

Beispiel 

<!--

    Implementierungsleitfaden "Digitaler Mutterpass auf der Basis von CDA R2"

-->
{{Infobox Dokument
|Title     = Digitaler Mutterpass auf Basis der<br/>HL7 Clinical Document Architecture Release 2<br/>für das deutsche Gesundheitswesen
|Short     = Digitaler Mutterpass auf der Basis von CDA R2
|Namespace = cdaemp
|Type      = Implementierungsleitfaden
|Version   = 1.20
|Date      = 15. Februar 2011
|Copyright = 2010-2011
|Status    = Final Draft
|Period    = Abstimmung
|OID       = n.n.
|Realm     = Deutschland
}}
<!--

-->
{{Infobox Ballot Begin}}
{{Ballot | Version = 1.00 | Date = 18.09.2010 | Status = Entwurf | Realm = Deutschland}}
{{Ballot | Version = 1.10 | Date = 15.02.2011 | Status = Abstimmung | Realm = Deutschland}}
{{Ballot | Version = 1.20 | Date = 15.06.2011 | Status = Kommentarauflösung | Realm = Deutschland}}
{{Infobox Ballot End}}

{{HL7transclude| cdaemp:Einleitung}}
{{HL7transclude| cdaemp:Grundlagen}}
{{HL7transclude| cdaemp:ImplementierungCDA}}
{{HL7transclude| cdaemp:Anhang}}
{{HL7transclude| cdaemp:Abkürzungsverzeichnis}}
{{HL7transclude| cdaemp:Literaturverzeichnis}}

= Referenzen =
<references/>

Teildokumente

Jedes Teildokument enthält neben dem eigentlichen Text ganz oben an als ersten Text die Vorlage DocumentPart um deutlich zu machen, dass dieses Dokument Teil eines Leitfadens ist. Diese Vorlage sorgt automatisch auch dafür, dass das Dokument zur zum Teildokumenten-Namespace gleichnamigen Kategorie hingefügt wird.

Zu beachten ist, dass Teildokumente in einem eigenen Namespace pro Leitfaden (Teildokumenten-Namespace) unterzubringen sind.

Beispiel: Inhalt des Dokuments cdaemp:Einleitung 

{{DocumentPart}}
= Einleitung =
== Motivation und Ziel ==

Seit der Einführung des... (Text)

Voraussetzungen

Namespaces

Jeder Implementierungsleitfaden ist ein eigenständiges Wiki-Dokument, dass im Wiki-Namespace IG: anzulegen und zu pflegen ist.

Beispiel: Das Hauptdokument des Leitfadens Digitaler Mutterpass auf der Basis von CDA R2 ist angelegt als 

IG:HL7_CDA_Mutterpass

Es ist zu beachten, dass die Leitfäden keine Versionsnummern oder dergleichen enthalten.

Alle zugehörigen Dokumente sind in einem eigenen Wiki-Namespace unterzubringen.

Attention icon.svg Dazu ist es nicht ausreichend, dass den Dokumenten ein Präfix mit abschließendem : vorangestellt wird, sondern die ausgezeichneten Wiki-Namespaces müssen gesondert vom Administrator vor Anlegen eines Dokuments eingetragen werden, damit sie als solche bekannt sind. Die Eintragungen nimmt der Administrator auf in der Datei MediaWiki:ExtraNamespaces vor.

Beispiel: 

cdaemp:

ist der ausgezeichneten Wiki-Namespace für alle Dokumente zum Leitfaden Digitaler Mutterpass auf der Basis von CDA R2. Alle zu diesem Leitfaden gehörenden Dokumente sind mit diesem Namespace-Präfix zu versehen. Das Hauptdokument des Leitfadens selbst ist im Namespace IG: angelegt.

Aufteilen der Dokumente

Der gesamte Leitfaden sollte in kleinere Abschnitte unterteilt werden. Sehr sinnvoll ist hier zum Beispiel das teilen in Kapitel oder in logische Abschnitte.

Beispiele: Der Leitfaden Digitaler Mutterpass auf der Basis von CDA R2 ist in seine Kapitel aufgeteilt. Bei Leitfaden Datentypen ist die ebenso der Fall, zusätzlich sind hier die Beschreibungen der einzelnen Datentypen auch noch als kleine Teildokumente vorhanden, damit man ihren Text in anderen Dokumenten transkludieren oder referenzieren kann.

Typische Kapitel/Abschnitte

Ein typischer Leitfaden hat die folgenden Abschnitte bzw. Kapitel. Abschnitte in (Klammern) sind nur zu nennen, wenn es unbedingt notwendig erscheint.

  • Dokumenteninformation
    • Impressum
    • Ansprechpartner
    • Disclaimer
    • Autoren
    • Copyright-Hinweis, Nutzungshinweise
    • Danksagung
  • Einleitung
    • Rationale
    • Zielsetzung
    • Vorarbeiten
    • Abgrenzung
  • (Grundlagen)
  • Struktureller Aufbau
    • Verwendeter Standard
    • Übersicht CDA Header und Body
    • (Verwendung von Templates)
  • CDA Document Level Templates
  • CDA Header Level Templates
  • CDA Section Level Templates
  • CDA Entry Level Templates
  • Terminologien
    • Value Sets
    • Kodesysteme
  • Anhang (nicht normativ)
    • Beschreibung der Use Cases und Storyboards
    • Lizenzen
  • Referenzen

Erstellen / Umsetzen der Spezifikation

Grundsätzlich können die üblichen Mediawiki-Möglichkeiten genutzt werden. Im Zuge der Vereinheitlichung von Leitfäden, ihrem Layout und ihrer möglichen Wiedergabe als PDF sind einige Vorschläge und Regeln zu beachten.

Hochauflösende Bilder

Grundsätzlich sollten Bilder im SVG Format oder als JPG oder PNG mit mindestens 200dpi eingebunden werden, damit sich in der Druckausgabe damit noch etwas anfangen lässt.

Ohne weitere Maßnahmen werden eingebundene Bilder so im PDF wiedergegeben, wie sie angegeben sind. Das heißt, dass ein Bild, das hochauflösend ist, aber auf nur 300px herunterskaliert ist, auch nur in der schlechteren Auflösung gerastert in in das Druckdokument übernommen wird. Ein übliches Beispiel: 

[[Datei:Bild.jpg|300px]]

Um vorhandene hochauflösende Bilder dennoch im PDF mit der maximalen Auflösung wiederzugeben, besteht das Template {{HL7img|bilddatei|xpx|ppc}, wobei eine Bilddatei bilddatei (vorzugsweise SVG bzw. JPG oder PNG mit mindestens 200dpi) im Onlineformat mit xpx Pixeln skaliert wird (wie in einer Image-Anweisung) und für die Druckausgabe ppc % der Seitenbreite einnimmt. Die Skalierung für die Druckausgabe ist dabei wesentlich verlustfreier, da von dem hochauflösenden Original bei der Pdf-Konvertierung skaliert wird. Das vorige Beispiel sieht dann im Quelltext zum Beispiel so aus: 

{{HL7img|Datei:Bild.jpg|300px|80%}}

Verwendung von Hinweisboxen mit Symbolen

Grundsätzlich sollte erwogen werden, dass alle Entwürfe wie folgt gekennzeichnet sind. 

{{Underconstruction}}

Das ergibt:

Under construction icon-blue.svg This article or section is in the middle of an expansion or major restructuring and is not yet ready for use. You are welcome to assist in its construction by editing it as well. If this article has not been edited in several days, please remove this template.
This page was last edited by Wikiadmin (talk| contribs) 5 years ago. (Purge)
Diese Seite oder Abschnitt ist derzeit ein Entwurf und ist noch nicht fertiggestellt. Du bist eingeladen, bei der Fertigstellung mitzuwirken. Wenn dieser Beitrag länger als einige Tage nicht editiert wurde, entferne diese Vorlage.
This page was last edited by Wikiadmin (talk| contribs) 5 years ago. (Purge)


Es können die folgenden mit Symbolen versehenen Hinweisboxen im laufenden Text gesetzt werden.

Talk.svg Dies ist ein Punkt, der besondere Aufmerksamkeit erfordert.
Information icon.svg Dies ist ein einfacher Hinweis.
Under construction icon-blue.svg Dies ist ein Hinweis auf einen Sachverhalt, der noch bearbeitet werden muss.
Issue.svg Dies ist ein bekanntes Problem / offener Punkt.
Faq.svg Dies ist eine häufig gestellte Frage mit Antwort.
Attention icon.svg Dies ist ein Punkt, der unbedingt zu beachten ist.
Conformance.svg Dies ist eine Einschränkungsregel.
Logo-hl7.svg Dieser Punkt muss in HL7 Deutschland noch besprochen/abgestimmt werden
Logo-hl7int.jpg Dieser Punkt muss in HL7 Deutschland oder HL7 International noch besprochen/abgestimmt werden
Bestpractice.svg Dies ist ein Hinweis auf empfehlenswertes Vorgehen (best practice)

Beispiel eines Wiki-Textes: 

{{FAQBox|Diese Information wird in diesem Leitfaden zunächst nicht verwendet.}}

Die anderen Stichwort lassen sich aus nachfolgender Liste ableiten.

Siehe dazu die folgenden Vorlagen:

Literatur- und Quellenhinweise, Referenzen, Abbildungs- und Tabellenunterschriften

Literatur- und andere Quellenhinweise werden über das ref-Element angegeben. 

Es wurde eine XML<ref>Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/</ref>
bzw. JSON <ref>JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org</ref>
Entwicklung angestoßen.

Es wurde eine XML[1] bzw. JSON [2] Entwicklung angestoßen.

Abbildungen und Tabellen können mit automatisch durchnummerierten Referenzen versehen werden. Hierzu werden die Schlüsselworte "Abbildung" bzw "Tabelle" verwendet. 

{{HL7img|Ukfpmp1.jpg|300px|40%}}
<ref group="Abbildung">Die ist der Text, der bei der Bildreferenz angezeigt wird</ref> ''Dies ist der erklärende Text zur Abbildung als Bildunterschrift''

Hier wird eine Abbildung referenziert und mit der entsprechenden Bildunterschrift versehen.

Ukfpmp1.jpg
Ukfpmp1.jpg

[Abbildung 1] Dies ist der erklärende Text zur Abbildung als Bildunterschrift 

{| class="hl7table"
|-
!Section!!LOINC-Code
|-
|... || ...
|}
<ref group="Tabelle">Text der bei der Tabellenreferenz angezeigt wird</ref> ''Dies ist der erklärende Text als Tabellenunterschrift''

Hier ist eine Tabelle mit entsprechender Tabellenunterschrift aufgeführt.

Section LOINC-Code
... ...

[Tabelle 1] Dies ist der erklärende Text als Tabellenunterschrift

Am Ende des Dokuments/Abschnitts muss dazu das entsprechende Referenz-Tag eingelöst werden, um die Referenzen alle aufzulisten. 

Referenzen
<references/>

Abbildungen
<references group="Abbildung" />

Tabellen
<references group="Tabelle" />

Referenzen

  1. ↑ Extensible Markup Language (XML) - W3C, https://www.w3.org/XML/
  2. ↑ JavaScript Object Notation (JSON): https://tools.ietf.org/html/rfc4627, http://www.json.org

Abbildungen

  1. ↑ Die ist der Text, der bei der Bildreferenz angezeigt wird

Tabellen

  1. ↑ Text der bei der Tabellenreferenz angezeigt wird

Wiederholentlich genutzt Referenzen können einen Namen bekommen 

<ref name="xyzref">Die Referenz</ref>

...und an anderer Stelle einfach erneut durch Nennung des Namens 

<ref name="xyzref"/>

...referenziert werden.

Einbinden von farbigen Boxen für verschiedene Zwecke

Beispiele im laufenden Text

...sollten markiert werden mit einer blauen Box.

Ich bin ein Beispiel

Dies ist der Text in der babyblauen Box

Die Syntax ist 

{{BeginBlueBox|Ich bin ein Beispiel}}
Dies ist der Text in der babyblauen Box
{{EndBlueBox}}

Storyboards im laufenden Text

...sollten markiert werden mit einer violetten Box (BeginPurpleBox, EndPurpleBox):

Ich bin ein Überschrift

Dies ist der Text in der Box

Weitere Boxen

...stehen mit BeginGreenBox / EndGreenBox, BeginRedBox / EndRedBox und BeginGrayBox / EndGrayBox zur Verfügung.

Ich bin eine Überschrift

Dies ist der Text in der Box

Ich bin eine Überschrift

Dies ist der Text in der Box

Ich bin eine Überschrift

Dies ist der Text in der Box

XML-Darstellung

Soll XML eingebunden werden, ist dies mit dem Tag syntaxhighlight wie folgt anzugeben. 

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>

     oder (als default)

<?xml version="1.0"?>
</syntaxhighlight>

und erscheint dann zum Beispiel als: 

<?xml version="1.0" encoding="utf-8"?>

     oder (als default)

<?xml version="1.0"?>

Mehr dazu findet sich in der Hilfe zu Hilfe:Syntaxhervorhebung.

Angaben zu HL7 V3 Klassen-Attributen

Information icon.svg Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft der Output des Tools ART-DECOR für die Objekt- und Attributdefinition verwendet. Dabei können Templates einfach in den Wiki-Originaltext transkludiert werden. Voraussetzung dafür ist natürlich, dass die Templates in ART-DECOR eingebracht sind. Mehr dazu unter Hilfe:Templates.

Zum Beispiel ergibt 

{{:1.2.276.0.76.10.2010/dynamic}}

...folgende Ausgabe

Id1.2.276.0.76.10.2010Gültigkeit gültig ab 2013‑07‑10
StatusKyellow.png EntwurfVersions-Label
NameHeader​Information​RecipientNotifiableDiseaseAnzeigenameCDA informationRecipient Meldepflichtige Krankheiten
Beschreibung
Labelhirnd
KlassifikationCDA Header Level Template
Offen/GeschlossenOffen (auch andere als die definierten Elemente sind erlaubt)
Benutzt von / Benutzt
Benutzt von 2 Templates, Benutzt 1 Template
Benutzt von Template-Id als NameVersion
1.2.276.0.76.10.1010Arztmeldung nach §6 IfSG2013‑07‑15
1.2.276.0.76.10.1011Labormeldung nach §7 Abs. 1, 2 und 3 IfSG2014‑07‑13
Benutzt Template-Id als NameVersion
1.2.276.0.76.10.90011InklusionOrganizationElementsDYNAMIC
BeziehungAdaptation: Template 1.2.276.0.76.10.2005 (DYNAMIC)
Beispiel
Beispiel
<informationRecipient typeCode="PRCP">
  <intendedRecipient>
    <id extension="4736437" root="1.2.276.0.76.3.1.14.4711.1011.1.2"/>
    <receivedOrganization>
      <name>Gesundheitsamt Gallierdorf</name>      <telecom use="WP" value="023458474"/>
      <addr>
        <streetName>Ostring</streetName>        <houseNumber>30</houseNumber>        <postalCode>44341</postalCode>        <city>Bochum</city>      </addr>    </receivedOrganization>  </intendedRecipient></informationRecipient>
ItemDTKardKonfBeschreibungLabel
hl7:information​Recipient
hirnd
Treetree.png@typeCode
cs1 … 1R
 CONF
@typeCode muss "PRCP" sein
oder
@typeCode muss "TRC" sein
Treetree.pnghl7:intended​Recipient
1 … 1Mhirnd
Treeblank.pngTreetree.pnghl7:id
II0 … *hirnd
Treeblank.pngTreetree.pnghl7:received​Organization
1 … 1Mhirnd
Eingefügt  von 1.2.276.0.76.10.90011 CDA Organization Elements (DYNAMIC)
Treeblank.pngTreeblank.pngTreetree.png@classCode
0 … 1FORG
Treeblank.pngTreeblank.pngTreetree.png@determiner​Code
0 … 1FINSTANCE
Treeblank.pngTreeblank.pngTreetree.pnghl7:id
II0 … *hirnd
Treeblank.pngTreeblank.pngTreetree.pnghl7:name
ON1 … 1hirnd
Treeblank.pngTreeblank.pngTreetree.pnghl7:telecom
TEL0 … *hirnd
Treeblank.pngTreeblank.pngTreetree.pnghl7:addr
AD0 … 1hirnd

Klassen-Attribute in HL7 V3 werden grundsätzlich über die Vorlage AttDesc in die Spezifikationen eingebunden. Führend ist hier, ob ein Klassen-Attribut als XML-Element oder XML-Attribut wiedergegeben wird.

Wiki-Text für Elemente: 

{{AttDesc
| ae = elm
| rim = act, ent, role, part
| name = Encounter
| desc = Begegnung
| dt = 
| card = 1..1
| conf = M
}}

Beispiel:

< Element DT Card Conf Beschreibung
Encounter 1..1 M Begegnung


Im Falle einer Einschränkung auf ein Attribut kann dieses separat oder direkt beim Attribut niedergelegt werden.

Wiki-Text für Attribute: 

{{AttDesc
| ae = att
| rim = act, ent, role, part
| name = id
| desc = Id des Dokuments
| dt = II
| card = 1..1
| conf = M
}}

Beispiel:

@ Attribut DT Card Conf Beschreibung
id II 1..1 M Id des Dokuments
Conformance.svg Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.


oder auch als:

@ Attribut DT Card Conf Beschreibung
id II 1..1 M Id des Dokuments


Conformance.svg Mindestens eine id MUSS als @root 2.1.3.4.5.6 PatientenNummerDeutschland enthalten.

Strukturierung von Leitfäden und deren Inhalten

Abschnitte (Sektionen und Entries)

  • Die Abschnitte werden alle beginnend auf der zweiten Ebene formatiert.
  • Überschrift2: "Section: <Beschreibung>" bzw. "Entry: <Beschreibung>"
  • Die Abschnitte enthalten alle zu Beginn einen kleinen Header, der die Identifikation erleichtert:

Template-Metadaten-Tabelle

Information icon.svg Hinweis: Diese Darstellung ist veraltet. Für CDA-Leitfäden wird in Zukunft art-decor für die Objekt- und Attributdefinition verwendet
Template-Metadaten
Template-Typ Header oder Section oder Entry
Template ID <OID für das Template>
generischeres Template <Verweis auf das Template>
genutztes Templates <Verweis auf das Template>
nutzende Templates <Verweis auf das Template>
abgeleitete Templates <Verweis auf das Template>
Schwester-Templates <Verweis auf das Template>
Generelle Beschreibung < direkte Kurzbeschreibung >
allg. Erläuterung < Verweis auf eine allgemeine Erläuterungsseite >
Verhältnis zu IHE dt.Übersetzung oder Ergänzung oder neu
Ballotierungsstatus < Status der Verabschiedung >
Erweiterbarkeit offen oder geschlossen
  • Nach dem Template folgt die Beschreibung mit einer optionalen kleinen Grafik, die den Zusammenhang zwischen den einzelnen Klassen erläutert.
  • Danach folgt eine Tabelle, in der die Klassen und ihre Attribute aufgelistet werden:
    • Diese Tabelle wird zukünftig durch ART-DECOR ersetzt. Bis dahin dient sie der Sammlung der notwendigen Informationen.
    • Lvl: Schachtelungstiefe gemäß XML-Darstellung
    • RIM-Element (Attribute werden mit "@" dargestellt.
    • Hier sollte sich auf die Inhalte konzentriert werden.
Lvl RIM Name DT Kard Conf Beschreibung
1 act observation
2 act templateID
2 act code
2 act value
2 rel
1 part
2 role
4 ent


  • Lvl
    • Schachtelungsebene für XML
  • RIM
    • farbliche Kodierung des RIM-Elementes
  • Name
    • das RIM-Element, d.h. Element oder Attribut-Name (letzterer mit "@" als Präfix)
  • DT
    • Datentyp mit Nutzung von nationalen Flavors
  • Kard
    • Kardinalität
  • Conf
    • M = Mandatory (MUSS-Feld mit gefülltem Inhalt, Null-Flavors nicht erlaubt
    • R = required (MUSS-Feld mit Null-Flavors)
    • opt. = optional (KANN-Feld)
    • NP = not Permitted (verboten)
  • Beschreibung
    • textliche Beschreibung des Elements
  • An die tabellarische Darstellung der Inhalte schließen sich die Vokabularien an.
  • Zu guter Letzt kommt ein Beispiel (in XML).


Information icon.svg Bei Wiederverwendung von anderen Templates sollten die Links aufgeführt und die Angaben auf ein Minimum reduziert werden.

Ballotierungsstatus

Folgende Status werden im Idealfall bei der Ballotierung durchlaufen. Daraus ist ersichtlich wie weit die Arbeiten zu den Templates, Implementierungsleitfäden oder Spezifikationen im Allgemeinen abgeschlossen sind. Der jeweilige Status lässt sich aus der Metadaten-Tabelle (z.B. Template-Metadaten-Tabelle) entnehmen.

  • Entwurf (draft)
  • in Abstimmung (review)
  • Verabschiedet (active)
  • Veraltet (retired)

Ballotierungsstatus für Dokumente/Implementierungsleitfäden

(s.o)

Ballotierungsstatus für Templates

(s.o)

Abgerufen von „https://wiki.hl7.de/index.php?title=Hilfe:Implementierungsleitfaden&oldid=57312“