Ehscda:Artdecor-governance

From eHealth Suisse
Jump to: navigation, search


Document Information

Status Draft
Document version 1.1
Authors
  • Johannes Gnägi (eHealth Suisse)
  • Sang-Il Kim (eHealth Suisse)
  • Kai Heitmann (Heitmann Consulting and Services , ART-DECOR Open Tools)
  • Jürg Bleuer (eHealth Suisse)
  • Tony Schaller (IHE Suisse)
  • Oliver Egger (HL7 Benutzergruppe Schweiz)
Stakeholder Contributor(s) HL7 Schweiz, IHE Suisse, Heitmann Consulting and Services

Summary

This document contains Guidelines and Governance Information about using Art-Decor® and the Wiki Documentation within Switzerland.

Guidelines

A minimum of best practices and recommendation is provided to ensure a national and also international conformity and harmonized approach when using the tools. These Guidelines where developed in several physical and virtual Workshops between eHealth Suisse, Kai Heitmann, Tony Schaller and Oliver Egger. This document is a living document and updated as soon as users of the tool reach new consensus.

Governance

This document defines the necessary responsibilities und processes to guarantee clear structures for collaboration within Art-Decor and the Wiki. This covers the responsibility for Art-Decor Repositories, Quality Assurance and coverage of Support for the Tools.

Introduction

Purpose

eHealth Suisse decided by the end of 2015 to actively use Art-Decor and Mediawiki as the tools to specify the national exchange formats for HL7 CDA documents. The migration of existing specifications along with new developments showed the different approach between countries (e.g. Switzerland, Germany and Austria) for the development of such specifications and involved a revision of the already existing ones in Switzerland.

The shift from text-based specifications to electronic (and computable) specification in a collaborative environment with Art-Decor and Mediawiki, also lead to a rethinking of governance structures and best practices. The aim of this document is to define the relevant governance and best practices for Switzerland when using these tools.

Scope

The document does not address how HL7 CDA documents are modelled but describes mainly the usage of the tools Art-Decor and Mediawiki, accompanied with Do's and Don'ts for Switzerland. It defines rules and structures which have to be followed by all users of these tools.

Process of developing

This document has been developed as follows:

  • Collection of issues and questions about the handling of the tool by the Users
  • Several physical and virtual workshops were held between November 2016 and February 2017, by the users and eHealth Suisse to discuss the relevant questions and to define the next steps.
  • End of February 2017, a draft was sent to the participants of the meeting and HL7 Switzerland and IHE Switzerland.
  • After the review, a first version was issued and published on the Wiki.

Evolving document

This document is meant to be a living document that contains the newest questions and decisions about the work with Art-Decor and Mediawiki within Switzerland.

New inputs can be submitted to Trello via email. Please send any input to the following address: Governance: Request Update eMail

New inputs are also going to be collected during regular HL7 Technical Committee meetings and then reviewed by the relevant stakeholders (i.e. eHealth Suisse, HL7 Switzerland and IHE Suisse) and cosidered for inclusion.

Guidelines

Languages

Art-Decor

All documentation of Art-Decor artefacts shall be written in English (includes also documentation of the project). This ensures the understanding across the different countries using Art-Decor and enables a better sharing. The owner of a project is free to use German, French or Italian in addition but is responsible that the descriptions are up-to-date with the newest Version in Art-Decor.

When appropriate, Art-Decor datasets shall contain display names and captions in English, German, French and Italian. Description of codes and comments shall follow the same rules as described before for Art-Decor.

Art-Decor export to Wiki

The primary language exported to the Mediawiki is also English. Other available languages will be exported too, when available. If no description is available in an export language, the default language of the project will be exported.

Wiki

The narrative part of an implementation guide – containing introduction, use cases, target audience, etc. – has to manually be documented in the Mediawiki and shall be written in German and French.

Implementation guides / exchange formats

As a result of the preceding language guidelines, an implementation guide (= Swiss exchange format) will exist in the Wiki in German as well as in French with the same meaning. These editions both contain the normative part as an export from Art-Decor in English, only.

OIDs

Implementation Guide

For each Implementation Guide an OID with the following child nodes shall be created:

Governance oid impl-guide.png

Governance oid impl-guide.png

[Abbildung 1] OID structure for Swiss implementation guides based on HL7 CDA

Art-Decor root OIDs

All Art-Decor templates shall be placed below the OID 2.16.756.5.30.1.1.10 (hl7-ch-domains/decor-templates). All Art-Decor value-sets shall be placed below the OID 2.16.756.5.30.1.1.11 (hl7-ch-domains/decor-valuesets).

Governance oid temp-val.png

Governance oid temp-val.png

[Abbildung 2] OID tree for Art-Decor templates and value sets

Root OIDs for templates

OIDs for Art-Decor templates shall be drawn according to their CDA template types from the corresponding following child nodes:

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

Versioning of document-level templates

A new OID shall be used for each new Document-Level Template Version. The relation to the old OID shall be indicated. This ensures the application of the correct schematron rules according to the tested CDA document.

Versioning of value sets

OIDs for Value Sets remains the same for all of its versions, while value set versions are distinguished by the effective date (Version as of ...). In addition, a value set may carry an official release date. Best practice for the creation and maintenance of Value Sets needs to be applied, e.g. concept codes may be added but not deleted, only deprecated. If the overall meaning of the set of codes in a value set change the new version of the value set must get a new OID.

OIDs to be registered

It is recommended to only register the root node for Templates and Value Sets in the OID Registry (Refdata) and to provide links to the appropriate Art-Decor Views, where the relevant Templates and Value sets are listed (e.g. per Governance Group). This avoids duplication of work and maintenance.

Art-Decor

Repositories

Art-Decor BBR

In Switzerland, the following domain specific Art-Decor Building Block Repository (BBR) shall be used (others may be created later, if needed):

  • CH-HL7 CDA: Contains the base templates, defined by CDA-CH.
  • CH-PaLM: Contains national extensions to the IHE Pathology and Laboratory Medicine Technical Framework (PaLM; i.e. XD-LAB content profile).
  • CH-PHARM: Contains national extensions to the IHE Pharmacy Technical Framework (PHARM; i.e. PRE, PADV, DIS, PML, MTP content profiles).
  • CH-PCC: Contains national extensions to the IHE Patient Care Coordination Technical Framework (PCC; i.e. MS, IC content profiles).

Responsibilities and processes are described in chapter #Revisions.

Governance Groups

Governance Groups are organizational entities used to show the responsibility for artefacts in Art-Decor. Everyone is free to create a new Governance Group.

Artefact status in repositories

In a repository, artefacts shall be initially created in the status 'draft'. When finished, reviewed and endorsed, an artefact’s status can be changed in the repository according the rules of the responsible governance group (see Art-Decor.org/Template Editor for the Art-Decor default state/event diagram). Chapter #Repositories contains the description of the detailed process and responsibilities.

Documentation

Templates

Elements and attributes which are really used in the template shall be documented. Relationship to other templates shall be included to indicate how they relate (e. g. specialization, adaption etc.).

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

Standard references

Data and Template elements shall document Links in their Label to the appropriate specification they are based on (e.g. IHE PHARM, Ch. 4.4). Inclusion is in the responsibility of the developer. See CH - IHE Pharmaceutical Advice Concern Entry Content Module as Example.

Datasets

Language

See chapter #Languages for language guidelines.

Optionality

The usage of Art-Decor Datasets is recommended for new projects to document the understanding and functional requirements for non-technical Reviewers.

Official Swiss exchange formats

Art-Decor Datasets shall be used for official Swiss exchange formats and shall be updated in promoted projects.

Minimum Description

In order to be useful (e.g. for domain experts with no technical background), the following information shall be provided for each data element:

  • Name
  • Description
  • Datatype
  • Choice Lists, where appropriate
  • Link to Coded Concepts / Value Sets (Terminology Bindings), where appropriate

Scenarios should be provided, were additional information is specified:

  • Cardinality (optional, repeatable)
  • Conformance (required, mandatory)

Naming conventions for templates

Business names of Templates are created using CamelCase notation according to the element which wraps further content (e.g. LegalAuthenticator).

Templates shall be named without any prefixes. The prefixes CDA and CH, that have been used in the past shall no longer be used, as the repository indicates the origin of the template. The display name of the Template may not be an abbreviation only (like “AUTE”) but shall be an appropriate human readable name that carries the intention of the Template (e.g. “Author”). Abbreviations may be used in the business name of a template, though.

Naming conventions for value sets

For Value Sets, the same naming conventions are applicable as for templates.

Mediawiki

Structure of an Implementation Guide

To ensure a consistent approach and display of the implementation guide, the following (minimum, German) structure is recommended:

  • Identifikation Dokument
  • Impressum
  • Autoren
  • Zweck Positionierung
  • Gleichstellung Mann & Frau
  • Elektronische Version
  • Zusammenfassung
  • Einleitung
    • Ausgangslage und Motivation
    • Status und Zweck des Dokuments
    • Angesprochene Leserschaft
    • Ziele und Abgrenzungen
      • Interoperabilität als Voraussetzung
      • Ziele
      • Abgrenzungen
    • Grundlagen und Basistechnologien
    • Verantwortlichkeiten
  • Formelle Grundlagen
    • Bezug zu anderen Standards und Leitfäden
      • IHE Integrationsprofile
      • HL7 V3
      • HL7 Clinical Document Architecture (CDA)
    • Gesetzgebung Elektronisches Patientendossier (EPDG)
    • Übersetzungen
  • Begriffsdefinitionen
  • Anwendungsfälle
    • Einführung
      • Storyboard
      • Fallbeispiele
  • Empfehlungen
    • Transportmechanismus
  • Spezifikation (normativ)
    • Vereinfachte Zusammenfassung der CDA Struktur
      • CDA Header
      • CDA Body
      • Vereinfachte grafische Darstellung des Dokumenteninhalts
    • Allgemeines
      • Schlüsselwörter
      • Optionalität
      • nullFlavor
      • Hierarchie der Spezifikationen
    • Akteure und Transaktionen
    • CDA Struktur
      • CDA Document Level Templates
      • CDA Header Level Templates
      • CDA Section Level Templates
      • CDA Entry Level Templates
    • Codes und Wertebereiche
  • (Tutorial zu IHE Integrationsprofilen)
  • (Abkürzungen und Glossar)
  • Validierung, Technologien und Tools
    • CDA Beispieldokumente
  • Anhang
    • Lizenzen
    • Referenzen

A template for this structure is available on the wiki: Implementation Guide multilingual template. Templates for static contents are avalavle in German and French. German contents are selected by default, the corresponding french templates are subpages, e.g. /fr for French.

Schematic View of Templates

To have a simple hierarchical view of the used Art-Decor templates, the following visualization shall be used. The Power Point template is available here Powerpoint template CDA structure

Governance cda schema.jpg

Governance cda schema.jpg

[Abbildung 3] Example CDA structure

Revisions

In order to create a versioned extract (freeze) of a wikipage, follow these steps:

  • Mark the Wikipage with comment "official version" ("markieren").
  • Generate the PDF of the Page with a unique version number (e.g. YYYYmmdd_Specification-Name_language). This is currently performed with prince. You can find the necesary scripts, css and javascript on github.

Releases

Art-Decor

On the project site of Art-Decor, go to the "Version information" tab. On the right side, click "+" to start the release process.

  • Description: project notes / changes, for example from the project wiki (optional)
  • Type: intermediate Version or Release, Release Label: X.Y.Z (dd.mm.YYYY)
  • Publication Request: activate for official releases (pre-publication-review or final) - publicated resources will appear on the eHealth Suisse Art-Decor Publication page.
  • Status: tbd by project team
  • Publication parameters:
    • General
      • Development: not checked
    • ISO schematron generation
      • Create schematron: checked
      • Closed schematron: not checked (tbd)
      • Closed warnings on open schematrons: checked (tbd)
      • Create explicit includes: not checked (tbd)
    • Human readable publication
      • Create HTML: checked
      • PDF generation: checked

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.

Governance

Responsibilities

Support for Art-Decor

eHealth Suisse mandates

Developers who are mandated by eHealth Suisse will receive support for issues with Art-Decor by the Art-Decor team.

Other mandates

Developers in projects without the collaboration of eHealth Suisse, will need a separate service agreement with the Art-Decor team in order to get support.

Governance Groups

The following Table shows the existing Governance Groups within Switzerland and the responsible contacts:

[Tabelle 1] Swiss Governance Groups

Governance Group Contact
eHealth Suisse info@e-health-suisse.ch
HL7 Switzerland info@hl7.ch
Interverband Rettungswesen (IVR) info@ivr.ch

Repositories

The following table shows the responsible contacts for each repository

[Tabelle 2] Swiss Art-Decor repositories

Repository Responsibility
CH-HL7 CDA Oliver Egger
CH-PaLM Tony Schaller
CH-PHARM Oliver Egger
CH-PCC Tony Schaller

Wiki

eHealth Suisse is responsible of running and maintain the eHealth Wiki.

Art-Decor artifact states

The following state/event diagram shows the default states and possbile transitions for an artifact within Art-Decor:

Governance state machine.png

Governance state machine.png

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

Each Governance Group may decide to avoid some of these states. It is not recommended to add new states by a Governance Group.


[Tabelle 3] 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.

Quality Assurance & Review

Art-Decor Repository

Quality assurance for each template stored in an Art-Decor repository requires peer review by at least one expert. The responsible person for a repository has to ensure, that the templates are peer-reviewed.

Implementation Guides

Reviews are required for each Implementation Guide. At least one health professional, one HL7 expert and one IHE expert needs to review an Implementation Guide before it is submitted for a public consultation.

Official Swiss exchange formats

To promote an Implementation Guide to an official Swiss exchange format, the [#sprungmarke0_12 process] defined by eHealth Suisse has to be performed.

Annex

Links

List of Figures

  1. OID structure for Swiss implementation guides based on HL7 CDA
  2. OID tree for Art-Decor templates and value sets
  3. Example CDA structure
  4. Default state diagram for Art-Decor artefacts

List of Tables

  1. Example CDA structure
  2. Swiss Art-Decor repositories
  3. Art-Decor state machine

List of future definitions

  • Repositories shall not contain document templates (Exchange Document) as this is project specific.
  • Sollte für die Berichte angeschaut werden und z.B. beim Austrittsbericht angewendet werden / für kommende AF sollen diese Interoperabilitätsstufen berücksichtigt werden.
  • Tony erfasst ein Gerüst angelehnt an ELGA Interop-Stufen. Für LREP und VACD schaut Tony welche Stufe passen würde und erstellt ggf. unterschiedliche Templates.
  • Nullflavor so weit wie möglich vermeiden und nur in begründeten Fällen erlauben
  • Breaking Change soll in neuer Template ID resultieren. Minor Changes die Rückwärtskompatibel sind, können aber dann nicht speziell geprüft werden. Referenzen werden für einen freeze auf statisch gesetzt. Ein minor Change resultiert in einer neuen Revision des Templates mit der gleicher OID. Eine normative Version enthält nur statische Template verweise (Art-Decor Support anfragen).
  • Wir sind aktuell in der Entwicklung der Austauschformate, es wäre gut die Implementierungserfahrungen ab zu warten. Neue Erkenntnisse können dann gemeinsam definiert werden und es muss nicht unbedingt in einem geschlossenen definiert werden. CH wird weiterhin offene Templates definieren.
  • Nummerierung von Datasets bzw. Konkruenz mit EPD Inhalten
  • EPD Dokumenttemplates müssen vom OID Knoten
  • Sprachen: http://e-health-wiki.ch/index.php/Ehscda:Artdecor-governance#Art-Decor_export_to_Wiki nennt: Other available languages will be exported too, when available.

Das stimmt nicht, denn z.B. CDA-CH-LREP enthält auch deutsche descriptions. Diese findet man aber nicht im Wiki. Ich schlage vor, den Satz zu entfernen und nur Englisch zu rendern.

Hier würde ich noch ergänzen, dass diese OIDs in oid.refdata.ch eingetragen werden müssen und dass diese OIDs als Template-ID in den ART-DECOR Document Level Templates mit der Kardinalität 0..1 genannt werden müssen (This is an informational reference, only). Beispiel: https://art-decor.org/art-decor/decor-templates--cdachlrep-?section=templates&id=2.16.756.5.30.1.1.10.2.55

Hier würde ich diesen Satz folgendermassen präzisieren: «All Art-Decor value-sets that are specific for the given exchange format shall be placed below the OID 2.16.756.5.30.1.1.11 (hl7-ch-domains/decor-valuesets). Others may be referenced. ». Grund: Es gibt zahlreiche andere root OIDs für Value-Sets, die in einem Austauschformat verwendet werden (z.B. IHE mit 1.3.6.1.4.1.19376.1.3.11.xxx, HL7 mit 2.16.840.1.113883.1.11.xxx, EPDG Metadaten mit 2.16.756.5.30.1.127.3.10.xxx, was ich im Übrigen sehr unglücklich finde dass für die Value-Sets zum EPDG nicht die 11 als unterknoten verwendet worden ist…)

Dieses Kapitel kann man aus meiner Sicht entfernen, da ja alle Templates unter 2.16.756.5.30.1.1.10 und alle Value-Sets unter 2.16.756.5.30.1.1.11 abgelegt werden sollen und diese beiden Knoten sind in oid.refdata.ch bereits registriert.

Könnt ihr hier bitte ein Beispiel ergänzen, mit welchem Element in ART-DECOR das gemacht werden soll. Am liebsten als Auszug aus Temple und ein Link auf ein gutes Beispiel. Aus meiner Sicht, macht das vor allem bei den BBRs Sinn, wo wir auf IHE Templates verweisen also CH-PALM, CH-PCC und CH-PHARM. Bei den Austauschformaten sehe ich das nicht. Wenn Ihre damit einverstanden seid, dann bitte gleich auch die Governance entsprechend präzisieren, danke.

  • Die Hinweise zur Versionierung und Flagged Revisions verfahren sind gut, aber wir sollten hier noch festlegen wer welche Rechte hat, wann eine Flagged Revision festgehalten werden soll, etc.
  • Die Verwaltung der eHS Vorlagen (Abkürzungen, wann eine Vorlage machen, etc.), Namespases und Teildokumenten-Namespaces sollte auch beschrieben werden (inkl. einer Anweisung, wann welche Variante genutzt werden soll).