Difference between revisions of "Design Principles for Alignment, Review and Constraint of V3 Publishing Content"
Line 134: | Line 134: | ||
Thus the MessageReferences.xml file represents all of the content that has been submitted for generation in a single package that can be analyzed for errors, lost dependencies, etc. The analysis steps applied to this include: | Thus the MessageReferences.xml file represents all of the content that has been submitted for generation in a single package that can be analyzed for errors, lost dependencies, etc. The analysis steps applied to this include: | ||
*Create '''visioHref.ini''' and '''msgToHmdRefs.xml''' files that supports Visio in producing html graphic overlays for use with the few older models still maintained as "hmd" files. | *Create '''visioHref.ini''' and '''msgToHmdRefs.xml''' files that supports Visio in producing html graphic overlays for use with the few older models still maintained as "hmd" files. | ||
− | * | + | *Builds a '''proposed replacement cmetInfoExport'''. Working with MessageReferences.xml, it: |
+ | **Assembles a node set of '''''mergedSources''''' - message designs that '''should be listed''' based either on their being referenced in other designs or being fully listed in COCT domain. The set contains: | ||
+ | ***All message designs (msgElement[@elemType='msg']) where: | ||
+ | **** the message design has been referenced as a CMET in another design or | ||
+ | **** the message esign is defined in CMET pubDB but not referenced as a CMET in another design | ||
+ | *** (and) All Cmets defined in CMET PubDb (msgElement[@elemType='msgdef']) and referenced as a CMET in another design, BUT for which there is no message desiogn (msgElement[@elemType='msg']) |
Revision as of 16:06, 31 October 2010
Contents
Background
The HL7 V3 design process is predicated on three, inherently conflicting objectives -
- To allow individual Work Groups to focus on the material or subject matter with which they are experts;
- To provide coherent standards derived from singular high-level models for RIM, Vocabulary and Data Types;
- To re-use common specifications in order to reduce development effort increase efficiency; and
- 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 | ? |
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".
Assemble Ballot Cross-reference File
The first set of steps performed under "Preview Reference Integrity" are processes that build a single "sress-reference" file of all content submitted for publication in the Ballot. The file, MessageReferences.xml, is created in following sequence:
- (as part of ScenarioSetup)
- 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
- Working from InputFiles/CommonSourceFiles it analyzes rim.xml and vocabulary.mif to determine:
- (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.
- 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.
- (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.
- (as part of BuildMessageReferenceSources)
- Assembles a "statusPackage" for each staticModelPackage submitted listing:
- the model' that they are the design for;
- all CMET references that they contain;
- every vocabulary reference used that is unique within that model
- fatal serialization errors, principally associations that are not blocked in one direction (done only for VisioXml models); and
- anticipated MIF validation errors, principally invalid class and association names or names that are too long (done only for VisioXml models).
- In this process, the "intermediateDynamicModelReferences" and "CMET status package are used when analyzing VisioXml models in order to correct the reference version numbers and to correct the CMET name references in the message statusPackages.. This correction is not applied to the analysis of designs submitted as HMD files, but could be.
- Assembles a "statusPackage" for each staticModelPackage submitted listing:
- Assembles a mimimal vocabulary file (for speed of access) that contains only the elements that can be referenced from models - Concept Domains (by name), Concepts (by CodeSystem Name and Code), and Value Sets (by name).
- Concatenates all of the "statusPackage" (dynamic, non-domain, cmet, and static model) files into a single MessageReferences.xml file. This file is the foundation for detailed error analysis, alignment as source files are converted to MIF, and quality assurance reporting.
Analysis of Ballot Cross-Reference File
Thus the MessageReferences.xml file represents all of the content that has been submitted for generation in a single package that can be analyzed for errors, lost dependencies, etc. The analysis steps applied to this include:
- Create visioHref.ini and msgToHmdRefs.xml files that supports Visio in producing html graphic overlays for use with the few older models still maintained as "hmd" files.
- Builds a proposed replacement cmetInfoExport. Working with MessageReferences.xml, it:
- Assembles a node set of mergedSources - message designs that should be listed based either on their being referenced in other designs or being fully listed in COCT domain. The set contains:
- All message designs (msgElement[@elemType='msg']) where:
- the message design has been referenced as a CMET in another design or
- the message esign is defined in CMET pubDB but not referenced as a CMET in another design
- (and) All Cmets defined in CMET PubDb (msgElement[@elemType='msgdef']) and referenced as a CMET in another design, BUT for which there is no message desiogn (msgElement[@elemType='msg'])
- All message designs (msgElement[@elemType='msg']) where:
- Assembles a node set of mergedSources - message designs that should be listed based either on their being referenced in other designs or being fully listed in COCT domain. The set contains: