This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Design Principles for Alignment, Review and Constraint of V3 Publishing Content

From HL7Wiki
Jump to navigation Jump to search

Background

The HL7 V3 design process is predicated on three, inherently conflicting objectives -

  1. To allow individual Work Groups to focus on the material or subject matter with which they are experts;
  2. To provide coherent standards derived from singular high-level models for RIM, Vocabulary and Data Types;
  3. To re-use common specifications in order to reduce development effort increase efficiency; and
  4. To provide parallel development in order the provide standards that are respnosive to the evolving needs of the implementers.

Over the years, processes to support these objectives have been developed, including:

  • Harmonization to provide singular models for RIM, Vocabulary and Data types;
  • Definition of shared common structures for CDA, CMETs and selected message types; and
  • Tools to support the parallel development within a Work Group of both static model designs and the documentation of the domain framework in which those designs are used.

Where this all comes together is in "publishing." Four times a year (three ballots and a Normative Edition), the HL7 Director of Technical Publications receives material from myriad Work Groups that must be gathered, analyzed, corrected, and packaged to produce either a reliable ballot, or a formal Normative Edition. This must be done, in collaboration with the facilitators who make up the V3 Publishing Work Group, in a matter of a few weeks, starting with the initial content dead lines, and ending when the ballot opens.

This document attempts to lay out the rules and principles under which this activity proceeds, with a goal to "automating" as much of the process as possible.

Content Sources and Source Types

As noted, the content providers are the work groups, of which there may be many, but the material they provide and the types of content provided differ, and the treatment of this content may differ depending upon whether or not its primary intended use as a "common" shared content, or an implementable package.

The table at the end of this section (which is followed by a legend for the table) displays for each different grouping of submissions, whether those submissions primarily are for common use, the form(s) that the submissions are provided in, and the dependencies that these submissions have upon other submissions. (This table ignores "graphics" used to augment textual documentation in the submissions.)

For a typical ballot in May-2010, V3 Publishing processed:

  • 35 PubDbs with
    • 6 for common content and
    • 29 for general domains
  • 397 StaticModels (all but 17 of them as VisioXml) with
    • 233 for common content and
    • 164 for general domains
  • 50 non-domain specifications (of which roughly 30 were in PubXml)
  • 6 MIF or PubXml files for common content (RIM, Vocab, etc.)

Need less to say, the analysis and management of this content must be (and is) supported by automated analysis and needs more a linkages between the analysis and automated processing steps. After processing, this source came together to produce a web-site with about 17,000 files. This "explosion" of source is somewhat controlled. For example a single static model will result in 16 separate files as: 4 Mif files (MT and HMD in each of mif 1.1 and Mif 2.x), 3 graphics-related (overlay, thumb-nail and large), 2 table-views (MT and HMD), 1 Excel view, 4 schema files (HMD and MT in both Xsd and HTMl), and (on average) results in 2 interaction schema filess (xsd and html).

Submission Common? Source Forms Dependencies
Primary Design Supplemental RIM/Vocab/DT Wrappers CMETs CommonMsgs
RIM and DTs Y RimXml or PubXml Y
Vocabulary Y MIF Y
CMETs Y PubDb StaticModel PubDb Y Y
Wrappers Y PubDb StaticModel PubDb Y Y Y
CommonMsgs Y PubDb StaticModel PubDb Y Y Y Y
Domains PubDb StaticModel PubDb or PDF Y Y Y Y
Non-Domain Specs MIF or PubXml or PDF PDF ?

A legend for the above table follows:

  • CMETs - Common Model Element Types
  • Common - Material whose primary intent is to provide re-usable specifications for use in defining RIM-derived static model or for use in assembling "Domain" content.
  • CommonMsgs - Shared messages and interactions, primarily for acknowledgment transmittals
  • Domains - Every content specification that is not intended primarily as "Common", that includes RIM-derived, implementable static models, and that relies on a defined behavioral framework.
  • DTs - Data Types Specifications
  • MIF - File in Model Interchange Format (replacing PubXml and VisioXml formats
  • Non-DomainSpecs - Content specifications that are not intended primarily as "Common content" and that are not "Domains"
  • PDF - Page Description Format files for document publication.
  • Primary - This column under Source Forms lists the primary content format or a specification.
  • PubDb - Publication data base, which is expressed as PubXml
  • PubXml - File in HL7's XML document type definition defined in 2000.
  • RIM - Reference Information Model
  • RimXml - File in HL7's XML document type definition for RIM defined in 2000.
  • StaticModel - Form for expressing static models. In 2010 this is principally VisioXML and Visio "vsd" files. In future will be MIF with both graphics and design content.
  • VisioXML - File in HL7's XML type used to represent the design content of a static model defined in Hl7's RMIM Designer in Visio.
  • Wrappers - Transmission, Query, and Control Act Wrappers

Content Alignments

The critical step in content alignment is to assure references from one component to another connect correctly. This is principally a task of assuring that the identifier assigned an element as it is defined is the same as the identifier asserted in any references to that element. The critical kinds of identifier are listed in the table below along with the designation of the source document that acts as the "source of truth" for that identifier, the likely cause(s) of mis-alignment that may occur, and how alignment is effected.

Identifier "Source of Truth" Causes of Mis-Alignment How aligned?
All Artifact IDs in a PubDb Are governed by the HL7_artfactBallotStatus table in the PubDb. Responsibility for these rests with the Publishing Facilitator. Failure to maintain the current status in the "HL7_artfactBallotStatus" table. Automatically. The IDs are assigned as the content is extracted from the PubDb into PubXml format.
Static Model - BaseID SHARED between the PubDb in which it is defined and the static model design document. These sources are developed independently in PubDb and Visio and either of two different authors may err. These MUST be aligned by the facilitator for proper publishing. Accomplished by manually editing one or both sources.
Static Model - Version The PubDb in which the static model is defined rules on this version portion of the static model designer. This is determined by the ballot status that is documented in the "master" PubDB. The version on the static models is automatically updated to match the data from the defining PubDb.
CMET Name CmetInfoExport.txt is the master file of CMET Name/Identifier coordination . The file is maintained by MnM and incorporated as generator input. CMETs are bound to their using models by name, drawing data from the CmetInfo.txt files. However, tooling allows manual entry which may not be represented in CmetInfo. The Static Model Name is forced to align with CmetInfo , and all CMET references in other static models "look up" the correct name from CmetInfo and use that. Neither the name in the defining PubDb nor in the source design rules, but both SHOULD agree with CmetInfo.
RIM Content The rim.xml file placed in CommonSourceFiles sub-directory of Generator/InputFiles determines both the RIM version to be used and which data types release (determined by the binding in rim.xml) to use in Generation. As presently established, the only way to make an error is to place the wrong rim.xml file in the Generator. This should be changed in future. There should be a Generator parameter(s) that determines RIM and DT versions and then selects the appropiate RIM.xml file to use for generation. Any errant reference must be fixed manually. All references are to codes or names that are guaranteed to be unique within their name space.
Vocabulary and Data Type Content The "CoreMif" file for the vocabulary and PubXml for Data Types. Erroneous manual entry in a PubDb or static model design. Any errant reference must be fixed manually. All references are to codes or names that are guaranteed to be unique within their name space.
Graphic File Names The reference should be to the name of the graphic file itself Erroneous manual entry in a PubDb or static model design. Any errant reference must be fixed manually. The facilitator must assure uniqueness of these file names within their domain.

Review And Correction of Alignment Issues

The detection and reporting of content alignment issues is performed by the Quality Assurance Preview process that is the first step in all Generator runs and that can be invoked using publishing target 03.10...Process_Initial_QA.

The Publishing process first assures that all PubXml, MIF, and Static Model VisioXml are positioned in the InputFiles directories of the Generator. Next it "kicks off" the Generator "Preview Reference Integrity". This process performs a number of critical steps to initiate and analyze content alignment. In sequence:

  • Working from InputFiles/CommonSourceFiles it analyzes rim.xml and vocabulary.mif to determine:
    • the rimVersion to be used from the generator (the release or version of rim.xml);
    • the rimDatatypeVersion to be used (determined by the data types used in rim.xml); and
    • the vocabRealm and vocabUVVersion identifier (determined from vocabulary.mif)
    (Although these can be over-ridden as other targets are invoked, it is likely to lead to an invalid rim.coremif in which the declarted data types binding may disagree with the actual data types used in the RIM.)
  • Loads the config.txt properties and prepares all directories
  • (as part of BuildModelDefinitionReferenceSource)
    • Analyzes the individual content of all domain-created PubXml files to produce "statusPackage" files that hold the definition (type, name, and combined Id) of artifacts - RMIMs, HMDs, MTs and interactions (for their references to other MTs.
      [Suspect that this should be extended to include ALL artifacts - Story Boards, Application Roles, Trigger Events, the references from interactions to TEs and ARs, and the references from interaction/receiverResponsibility to other, potentially external TEs and interactions.]
    • Assembles (concatenates) the status packages into "intermediateDynamicModelReferences.xml" file that holds all of the PubDb definitions.
  • (as part of BuildApprovalStatusPackage) done but not used
  • (as part of BuildCMETReferenceSource)
    • Builds CmetInfo.xml from CmetInfoExport.txt
    • Assembles a Cmet "statusPackage" to provide reference access to the CMET listings
  • (as part of BuildNonModelReferenceSource)
    • Analyzes the individual content of all non-domain PubXml files to produce "statusPackage" files that references these files use as graphic references spec-references and URL links.