Packaging Domains for XML-MIF Publishing

Introduction

Preliminary mappings convince us that there is plenty of "power" in MIF2 to represent a domain, but we must select the optimum packaging strategy to support both development, publication and implementation. This started out as an explication of the problem, but having documented the alternatives, I have reached the conclusion that package-based Packaging is the only realistic strategy. The basis for this conclusion is laid out below.

Background

Current Domain Structures:

• A domain contains: Preface, Introduction and Scope, one or more DMIMs, zero or more Storyboards; one or more topics, 0..* Annex (where we have put Implementation Guides.
• A topic contains: Introduction and Scope, 0..* Story Board, 0..* App Roles, 0..* TEs; 1..* RMIMs, HMDs, and MTs; 0..* Interactions, 0..* Annex (where we have put Implementation Guides.
• Ballot status and Normative Status and Release packaging occurs either at the level of whole domain, or at the level of Topic, but each artifact also carries its own status.
• Release number and artifact version number are only related by happenstance.

MIF Structures:

• publication - provides the surrounding content for the formal artifact definitions; it provides for a single instance of approvalInfo (Ballot status, etc) that applies to the whole of the publication; it holds 1..* groups and items, and a group may also hold 1..* groups and items. Items reference content through the compound id embodied in packageLocation
• package - packages anything - individual artifacts (trigger, static model, etc.) other packages, publications - each package can hold its own approvalInfo, and some the package contents can carry their own approvalInfo, others cannot. Specifically:
  • Package content with own approvalInfo: freehandDocument; datatypeModelLibrary; staticModelInterfacePackage; vocabularyModel; staticModel; serializedStaticModel; derivedStaticModel; interactionProfile; conformanceProfile; publication; package
  • Package content without approvalInfo: domainAnalysisModel; structuredDocument; domainInstanceExample; storyboard; triggerEvent; interaction; applicationRole; testScenario
    MIF NOTE: the first two of these - domainAnalysisModel and structuredDocument surprise me since they are currently being balloted and approved within HL7 as stand-alone specifications.

Primary Packaging Alternatives

Mapping the domain and MIF structures exposes two obvious alternatives, although it should be clear that a blend of these could also be followed.

package-based Packaging

In simple terms, one takes advantage of the hierarchy available through the MIF package to create a parallel to the current "domain XML" files and uses a simple "publication" to carry the authors, etc.. Hierarchically, one will see:

• package at domain-level (with header/approvalInfo for the domain) annotations and contents include:
  • annotations/documentation/description holds the Domain intro and scope
  • annotations/documentation/appendix holds the domain annex(es) (if any)
  • staticModel(s) for the DMIMs
  • storyboard(s) at domain-level
  • package(s) for each "topic" (with header/approvalInfo for the topic) annotations and contents include:
    • annotations/documentation/description holds the topic intro and scope
    • annotations/documentation/appendix holds the topic annex(es) (if any)
    • storyboard(s)
    • applicationRole(s)
    • triggerEvent(s)
    • staticModel(s) for RMIMs, HMDs and MT.
      Note: These will provide only the relationships and walk-through. They will reference the full static model from another file. How is this done?
    • interaction(s)
• publication for the domain.
  • Info on authors, etc. in header
  • annotations/documentation/description holds the preface (Notes to balloters)
  • publishedItem for the domain package

publication-based Packaging

In simple terms, one takes advantage of the hierarchy available through the publication/publishedGroup to create a parallel to the current "domain XML" files and uses a simple "flat" package. Hierarchically, one will see:

• package for the domain (scope and introduction are in package/annotations) contents include:
  • storyboard(s)
  • applicationRole(s)
  • triggerEvent(s)
  • staticModel(s) for DMIMs, RMIMs, HMDs and MT.
  • interaction(s)
• publication for the domain. The preface (Notes to readers or voters) resides in the annotations.
  • publishedItem for the domain introduction and scope
  • publishedGroup for the DMIMs (precedingText is boiler-plate)
    • publishedItem for each DMIM
  • publishedGroup for the Domain storyboards(precedingText is boiler-plate)
    • publishedItem for each domain storyboard
  • publishedGroup for each topic
    • precedingText for Intro and Scope of topic
    • publishedGroup for storyboards
      • publishedItem for each storyboard
    • publishedGroup for applicationRoles
      • publishedItem for each applicationRole
    • publishedGroup for triggerEvents
      • publishedItem for each triggerEvent
    • publishedGroup for staticModels
      • publishedItem for each staticModel
    • publishedGroup for interactions
      • publishedItem for each interaction
    • followingText for annexes
  • publishedItem for annexes

Decision for package-based Packaging

I initially attempted to structure a pair of documents to implement publication-based Packaging, and began to run into snags. In order to articulate those problems, I created this document, and then realized that the snags would be almost insurmountable.

The problem, simply stated, is that a "flat" domain package as used in publication-based Packaging does not permit adequate control over approvalInfo. This style provides for approvalInfo in only two places - the package and the publication. This does not permit he assignment of different approvalInfo for storyboards, interactions, etc. when those elements are in topics whose approval level differs. The only way to circumvent this is to create sub-packages within the main package for each level of approval, but this is coming very close being the same as package-based Packaging.

There were additional considerations, as well. With publication-based Packaging:

• there is a requirement to keep two complex documents (package and publication) in synchrony ratgher than only one
• distribution to implementers will require both 'package' and 'publication' whereas the latter is not required with package-based Packaging.

Identifier Structures For MIF - and Mapping from Domain XML

In order to correctly map from one locale to another, we will use the following MIF attributes in packageLocation to identify a package or artifact:

Mapped Item	root	domain	artifact	name	id	realmNsp	version	Old ID
PA Domain	DEFN	PA				UV		PRPA_DO000000UV
"Person" Topic	DEFN	PA		Person		UV
DMIM	DEFN	PA	DM		000001	UV		PRPA_DM000001UV
Storyboard	DEFN	PA	SB		101202	UV	02	PRPA_ST101202UV02
StaticModel	DEFN	PA	RM		102345	UV	02	PRPA_RM102345UV02

Questions for the MIF-guru

Although the above will "work" I would be a LOT more comfortable if there were an artifact "kind" for a topic (perhaps "TO", "TC" or "BC") (the latter for base class topic). These are now concrete things, not just handy organizers. HL7 is currently joint-balloting a Topic (Individual Case Safety Report) as an ISO Standard. Thus it is very clear that we will need to be able to package this unambiguously in the future. Using an empty @artifact and a valued @name is at least unique, but a little too "loose" for my tastes.

Example Files

For testing these concepts, I created a pair of example files, using package-based Packaging, and named uvxx-Publication.mif and uvxx-Package.mif were created from the domain xml (uvxx.xml) for two different domains. These are Patient Administration (xx="pa") and CMETs (xx="ct"). (The example package includes only one or two examples of each element type, and embeds the larger text blocks in a comment in order to avoid converting the low-level mark-up.)

These examples were chosen because PA is a fairly large domain that is representative of the other domains, and CT is an outlier with a different domain XML pattern (it has no topics).

The files can be downloaded from this Wiki for Patient Administration and for CMETs.

Example Conversion Notes

The two MIF files include a number of comments, most starting as NOTE:, where there are issues or questions out-standing.

1. The NOTE: in PA that begins "NOTE: In the above, the @parameterName" in the package example is readily solved with an existing support file from the v3-Generator that includes both the possible parameter names for the stubs in a wrapper, and the type of the root element for the "wrapped" message. Together, these make the problem easy to address. This file MessageReferences.xml is large, but can be reduced radically to meet the limited needs of these conversions. Note also that this same file addresses the question of static model source type needed to resolve the @relationship question raised in a later note.
2. When CMETs were done, I realized that we will want a header/approvalInfo element in each of the CMET static models, because there is no other way to convey their multiple status values (NormativeStandard and NonStandardAvailable).
   1. In order to be consistent, I also added these elements to the RM, HD and MT files for PA, even though these could also inherit their approval status from their parent "topic" package.
   2. The inheritance is simply that if approval status is documented at the topic-level package, it will apply to all artifacts defined within that package, but, certain elements, principally the flavors of staticModel can have an assigned approval status that over-rides the inherited status.
3. Perusal of the examples will show that there is no consistent value for the @relationship attribute of derivedFrom. In HL7 work, the value should be either "restriction" or "unchanged". As a general rule, if the "RMIM" is defined in a Visio XML file, then the relationship for both the HMD and MessageType is "unchanged", but if the definition comes from a RoseTree "hmd" file, then the value will have to be "restriction" because there is no way to be sure whether RoseTree was used to restrict the model. The restriction MessageReferences.xml file mentioned above has the information needed to make this determination.
4. When creating these transforms, we will run into the issue of how does the source file generator (RoseTree) determine the correct value for the status of staticModels defined in other domains. This is particularly critical for: Message Wrappers, Control Act Wrappers and CMETs.

   The simple answer is that the domain XML in which the message is defined (CI, AI and CT in the previous examples) rules. However, this rule is only partially implemented in the current Generator. Specifically, the Generator corrects all CMET references for the values specified in the "uvct.xml" file.

   In the future, we will wish to correct the values for the wrappers as the conversion is made, and it will be necessary to either re-convert, or post-process the converted MIF files if the content of one of these source domains changes.

Gschadow 03:55, 25 September 2009 (UTC): I have a request. Can we please leave off the human readable name piece from the file name? I am trying to read these mif files out of JAR files automatically and I can't if there is anything unpredictable in the name.