Difference between revisions of "Packaging Domains for XML-MIF Publishing"
Line 146: | Line 146: | ||
The files can be found [[Media:ExampleConversionOfUvpaXmlToMif.zip | on this Wiki.]] | The files can be found [[Media:ExampleConversionOfUvpaXmlToMif.zip | on this Wiki.]] | ||
+ | |||
+ | The '''NOTE:''' that begins "'''<code>NOTE: In the above, the @parameterName</code>'''" in the package example is readily resolved with an '''existing''' support file from the v3-Generator that includes both the possible parameter names for a wrapper, and the type of the root element for the "wrapped". Together, these make the problem soluble. |
Revision as of 01:05, 18 September 2009
Contents
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
A pair of example files uvpa-Publication.mif and uvpa-Package.mif were created from the domain xml (uvpa.xml) for Patient Administration. The example package includes only one or two examples of each element type, and includes the larger text blocks within a comment in order to avoid converting the low-level mark-up. The two MIF files include a number of comments, most starting as NOTE:, where there are issues.
The files can be found on this Wiki.
The NOTE: that begins "NOTE: In the above, the @parameterName
" in the package example is readily resolved with an existing support file from the v3-Generator that includes both the possible parameter names for a wrapper, and the type of the root element for the "wrapped". Together, these make the problem soluble.