Desktop Publication Documentation

Desktop Publication

Desktop Publication is a capability whereby Publishing Facilitators for particular domains or projects can manage their content, validate the completeness of that content, evaluate it for quality assurance issues, package it for submission as ballot content, and most importantly create a local replica of what their content will look like when included in a ballot.

This capability reflects a combination of processes from various tools operating in a controlled file environment, and using ANT driven scripts to invoke sub-processes supported by those tools. The tools involved include:

1. Publishing Processes - the set of ANT scripts and transforms used at HL7 Head Quarters (HQ) to produce and test each V3 ballot site.
2. V3 Generator - the set of ANT scripts and transforms used by HL7 HQ and others to convert the output files from the PubDb and Static Model Designer (see below) into MIF2 representation files; complete message and interaction schemas; html "table views" of each static model; and an Excel view of each static model.
3. PubDb The Set of VBA code, table and form definitions that allows use of an Access data base to define and manage individual domains according to the constraints expressed in the HL7 methodology.
4. HL7 RMIM Designer (in Visio) a combination of Visio stencils and detailed VBA code that supports "drag-and-drop" static model design while simultaneously invoking the constraints and content rules expressed in both the Hl7 Methodology, and the RIM and Vocabulary specifications.
5. RoseTree - which supports the RMIM Designer (in Visio), HL7 PubDb, and vocabulary MIF assembly by providing automated access to the HL7 design repository (holds RIM and Vocabulary content) and command line processes that allow ANT scripts to invoke processes in the RMIM Designer and PubDB.
6. Additional ANT scripts and transforms to support the integration of these tools, and the definition and execution of manifest generation, submission packaging, and quality assurance testing.

Rudimentary Instructions for Complete “Desktop” Publishing

System Dependencies & Installation

1. Dependency Note: These functions work equally well with Windows XP or Vista and Visio 2002 or Visio 2003-2007. There are no longer OS-specific BAT files. ANT automatically detects the OS and sets the directories accordingly.
2. Limit: either Visio 2002 or Visio 2003-7 with either operating system, but extensive testing has only occurred for Visio 2002 on XP and Visio 2003-7 on Windows XP. Further, I do not know if Visio 2002 will even run on Vista. (woody@beelers.com)
3. Configuration-specific BAT files have been created to deal with the Visio release differences, where necessary. In these cases, the BAT file names include either “Visio2002” or “Visio2003-7” in their names.

Installation

1. unzip hl7_v3pubgencombinedtools-*.zip archive into any available directory (ultimately requires about 800Mb MB)
2. convert hidden batch files to functional batch files by changing the file "1st_MAKE_THIS_FILE_dot_bat_and_RUN_it" to a batch file, and running it (this changes all of the "*.rename_as_dot_bat" files to BAT files)

Adding domain content to directories and BAT files

1. Populate tool with your domain data
   1. convert the "generic" domain (under input/domains) to the appropriate domain for your application (for example" uvrr")
   2. modify the file "generic-PublishLogged.bat" by replacing the word "generic" with the abbreviation for your domain (such as uvrr) in the body of the file, and make the same substitution in the name of the file if desired.
   3. copy and repeat the above two steps if you wish to process additional domains.
   4. add your "PubDB" and "design repository" (if static model designs are being reported in a design repository) in the "databases" subdirectory of your domain
   5. add your Visio design files (*.vsd) into the "sourcegraphics" subdirectory for all of your static model designs
   6. add your Visio "XML" files for your static model designs to the "sourcegraphics" subdirectory for those static model designs are not recorded in a design repository, Delete the Visio “XML” files for designs that are recoded in a design repository.
   7. add your RoseTree "hmd" files for your static model designs to the "sourcegraphics" subdirectory if your static model designs are\ recorded in a design repository,
   8. add your graphic files for other content (storyboard interaction diagrams, local graphics, etc.) (in GIF, JPG, or PNG formats) in the "outputgraphics" subdirectory
   9. add other material to be referenced in the domain (such as Adobe PDF files, or spreadsheets) to the "otherdistribution" subdirectory
2. Reduce CMET source content to desired – If you wish to reduce the CMET coverage to a known, required sub-set of the total CMETs, follow this step
   1. edit input/support/ant/cmetSourceRetentions.txt to create patterns that match the CMETs you wish to retain. All others will be deleted.
   2. run DeleteAllButSelectedCmetSource and “press any key to continue” when prompted
3. Publish the RIM, Datatypes and Vocabulary content to act as reference targets for your designs (this step only needs to be performed once)
   1. run RimDatatypesVocabulary-PublishLogged.bat

General Processing Steps

1. Create "clickable" graphics for the domain static model designs (perform this step again any time graphic representation or content of static model is changed in the Visio in the "vsd")
   1. run CreateClickableGraphicsFromVsd-Visio2002.bat or CreateClickableGraphicsFromVsd-Visio2003-7.bat (depending upon your Visio release)
2. Extract the domain XML (dynamic model) file from the pub DB (this step will also be performed at the end to finalize the publication) (Todo: Change this to a be a file "synchronization" step and do not require it to completely publish the domain.)
   1. run <yourDomain>-PublishLogged.bat. This will place Visio XML or design repository HMD files in the generator (Todo: Change ANT script to make this only move files for the selected domain, and provide another script that does the support files.)
   2. (not yet supported) extract design repository HMD files and move them to the generator

Domain Content Processing and Management

Domain content: Generate Schemas, Table Views, Excel Views

1. Run the generator to create table views, Excel views, and schemas for your designs (perform this step any time the static models are changed)
   1. run runlogged.bat (generator takes 5-20 min or so)
   2. use Excel spreadsheet widget to convert CSV files to XLS files this manual process requires file input/support/xsl/ HL7_RMIM_HMD_master-v2.26.xls

Domain content: Publish/assemble domain HTML

1. Publish your domain content repeat this step whenever any of your content (particularly the PubDb) has been changed
   1. run <yourDomain>-PublishLoggedXP.bat or <yourDomain>-PublishLoggedVista.bat (depending upon your OS)

Domain content: Manifest, Packaging and Quality Assurance

1. Dependency - As currently defined, this functionality is dependent upon the Generator source files having been populated. This is done by doing the initial set-up and "General Processing Steps" (above), although it does not require that clicakable graphics be created.
2. Set "MessageReferences" source - This is the source file for the packaging and QA tests. This process will analyze both your domain "dynamic model"(the output from your PubDb) and your static models as defined in "Visio xml" and "RoseTree hmd" files. The manifest and packaging draw all of their information from the "dynamic model" (PubDb xml output), whereas the QA analysis uses both.
3. Run "PreviewReferenceErrors.bat" file. This is a Generator process that runs at the beginning of every Generator run. Thus it deos not need to be re-executed, but, on the other hand, it is a quick (less than one minute process.
4. Generate Manifest, ZIP and QA document - At this writing, this is a single process, because the process is quick and it did not seem valuable to segregate the steps. To execute this process, you will need to create a batch file with a single line:

   BuildDomainManifestZip.bat uvxx where "xx" is replaced with the lower-case, two-character identifier for your domain. This file might be saved as "BuildManifestZip-uvrr.bat", for example.

   "run the BAT file created above". When you do this, the following will be created:

   • manifests.xml is created in "OutputFiles/Reports". This is the source file for all the domains represented in the Generator. It is of little direct use to the domain Facilitator.
   • manifestSummary-uvxx.htm is created in "input/domains/uvxx". This file has a root element of "manifest" (no surprise there) with a name attribute that is the domain name (like "uvxx"). The manifest contains a set of "file" elements that represent the individual lines of the manifest definition file (below). It also holds a set of "reference" elements that are of one of two types: "spec" and "url". The former are references using the "specRef" element to link to another specification in the HL7 Ballot, or a hyperlink to an HL7 or external web site. These should be reviewed to be certain they are current and that the links continue to work.
   • manifest-uvxx.txt is created in "input/domains/uvxx". This file is used by ANT to describe a "file set" of the files for including in the ZIP file. It will also be packaged as part of the ZIP file, and thus can be used by processes at HQ to manage the content or seek to recover it from SVN. (Todo: Make this happen.)
   • publishingPackage-uvxx.zip is created in the "root" directory of the tools (as a sibling to "input", "ToolFiles", etc.) It is the complete package of files from this domain to be sent to HQ. The ZIP file preserves the directory structure of the "input/domains" branches from which the content is drawn. This is the package that should be submitted to HQ for inclusion in the ballot.

     It should include all necessary files as:

     • "PubDb xml extract from which the manifest was defined,
     • "Visio vsd", and "Visio xml" or "RoseTree hmd" files for each static model defined in thePubDb. Note: It does not include the DMIMs.
     • All "graphic" files referenced by the PubDb content, as picked up from "outputgraphics"
     • All "other" files, like Word documents or Excel files or PDF documents that are picked up from "otherdistribution".
   • uvxx-qareview.htm is created in "input/domains/uvxx". This file documents the QA issues detected for the domain, and mirrors the report generated for each Normative Edition and Ballot, but with the content filtered to that relevant to the specific domain being packaged. [Todo: Perform further testing on the filtering.]

Other support: VisioXML editing, and ??

Updating class and attribute descriptions in Visio XML

This release includes the transform to update Visio XML Descriptions in a “target” file based upon descriptions previously captured in a “source” file.

The matching is done on the Class name ( and attribute name within that class) for the non-Arrow classes. (All but Participation, ActRelationship and RoleLink.) For the Arrow classes, the algorithm finds the class away from which the arrow class is traversing (always a non-Arrow class) by its name,. and then matches the arrow class by the traversal name rather than by class name. (Thus “author” rather than “Author1”.) If the target also contains descriptions, there is a default option to Replace these, but this can be over-ridden so that the process will only bring in descriptions from the Source in those places that have no descriptions in the target.

In order to use this transform, you will have to re-define (and experiment) with the bat file named: XampleUpdateVisioXmlDescriptions-PublishLogged.bat. The BAT file has a set of parameters that must be set by preceding them with –DparameterName. The parameters are:

• utilBaseDir the directory that holds the target file(s)
• utilDestDir the directory to receive the results which will have the same name as the targets
• utilSourceFileParameter The full path and file name of the source file
• utilTransformName set this as -DutilTransformName=UpdateAnnotationsInVisioXml.xsl
• utilTransformDir you can ignore this, the default is correct
• utilFileExt the extension for the target files, set as -DutilFileExt=xml

Good Luck.