Revision: Effective Date:
Model-Driven
16 3/30/11
Health Tools
Allyson Weaver Bunker
Author:
MDHT
User Guide
MDHT Document1
Document History
Revision History
Revision Revision Date Summary of Changes Author
Number
17 3/30/2011 Implemented changes from Allyson Weaver Bunker
Les Westberg, John Timm
and Kanwarpreet Sethi
MDHT USER GUIDE
03/29/2011
Page 2 of 36
MDHT Document1
Table of Contents
1. Introduction ............................................................................................................... 4
1.1. Purpose ........................................................................................................................................... 4
1.2. System Organization ....................................................................................................................... 4
2. Overview of the System ............................................................................................ 5
2.1. Key Features ................................................................................................................................... 5
2.2. Environment .................................................................................................................................... 5
2.3. System Operations .......................................................................................................................... 5
3. Definitions ................................................................................................................. 6
3.1. Key Vocabulary and Terminology ................................................................................................... 6
4. CDA 101 ................................................................................................................... 8
5. UML 101 ................................................................................................................. 10
5.1. Example UML Diagram ................................................................................................................. 11
6. MDHT Program Installation ..................................................................................... 12
7. Understanding a Template Model ........................................................................... 15
7.1. Organization of the Template Model ............................................................................................. 15
8. Editing the Example Model ..................................................................................... 19
8.1. Creating a New Template .............................................................................................................. 19
8.2. Creating an Association between Templates ................................................................................ 22
8.3. Creating a Constraint on an Attribute ............................................................................................ 22
8.4. Setting the Severity of the Constraint ............................................................................................ 23
8.5. Modeling Vocabulary ..................................................................................................................... 24
9. Transforming the Model to Source Code and Regenerating ................................ 25
10. Regenerating the Code ......................................................................................... 31
11. Transforming to DITA and Reloading the Model .............................................. 32
12. Activities in the Publication Process ...................................................................... 34
12.1. Adding Snippets .......................................................................................................................... 34
MDHT USER GUIDE
03/29/2011
Page 3 of 36
MDHT Document1
1. Introduction
1.1. Purpose
MDHT (Model-Driven Health Tools) is an Eclipse plug-in that provides a health care information
modeling environment. It provides the ability to create Unified Modeling Language (UML)
information models using a columnar spreadsheet like methodology. As part of the information
modeling toolkit, new models can be created from scratch or by extension or restriction of existing
class models. One of the primary goals of this tool is to enable models to be created and managed
in a single place and to generate the various artifacts from those models. Generated artifacts
include a java class library that represents the information model, validation tools, UML class
diagrams and implementation guide/documentation in a wide variety of formats including Eclipse
Help and PDF.
1.2. System Organization
This guide describes how Unified Modeling Language (UML) is used to model Clinical
Documentation Architecture (CDA) templates and implementation guides. This style is used within
the OHT Model Driven Health Tools (MDHT), but is applicable to any Unified Modeling Language
(UML) tool that is compliant with the Object Management Group (OMG) standard Unified Modeling
Language (UML) 2.2 or later.
MDHT USER GUIDE
03/29/2011
Page 4 of 36
MDHT Document1
2. Overview of the System
Describe the key features that relate to the system or software.
2.1. Key Features
MDHT software is described in this guide from the perspective of the end-user. MDHT contains
both design-time tooling and runtime artifacts both of which are discussed in this guide. However
the emphasis of this guide is on the design-time tooling and how it can be used to create models
and transform those models into documentation and code.
2.2. Environment
MDHT is run through Eclipse. Eclipse is an integrated development environment (IDE) for Java
created by an open source community of developers. Eclipse contains perspectives, views and
editors. Views and editors are grouped into perspectives and all projects are located in a
workspace.
2.3. System Operations
Prior to installing MDHT, the user will need to have the Eclipse Java Development Kit installed.
Use JDK 1.6 Update 23
http://www.oracle.com/technetwork/java/javase/downloads/index.html
The latest version of the all in one MDHT zip file
https://www.projects.openhealthtools.org/sf/projects/mdht/downloads/index.html
7Zip extraction tool
http://www.7-zip.org/download.html
MDHT USER GUIDE
03/29/2011
Page 5 of 36
MDHT Document1
3. Definitions
3.1. Key Vocabulary and Terminology
Association- a relationship with two or more ends, where each end is on a class (or other
classifier). Each end is called a Role, and may have a role name, Multiplicity, and may be
Navigable.
Attribute - a significant piece of data owned by a Class, often containing values describing each
instance of the class. Besides the attribute name and a slot for the attribute value, an attribute may
have specified Visibility, Type, Multiplicity, Default value, and Property-string.
Class- the primary declarative construct of Object-Oriented Programming; a cohesive unit of
Attributes and Operations; a compile-time template for an Object.
Constraint - natural language, programming language or Object Constraint Language Boolean
condition which may not be false if a Class is to be considered valid.
Comment- a comment is a mechanism that can be used to document various aspects of the
modeling process including design decisions, rationale, assumptions and limitations.
Generalization - a relationship between a specific classifier (typically a class) to a more general
classifier asserting that the general classifier contains common features among both the specific
classifier and the general classifier. Features include, for example, properties, and constraints. The
use of generalization is often logically restricted to cases where the specific classifier is a "kind-of"
or "sort-of" the general classifier: for example, a Boxer is a "kind-of" Dog. When the classifiers
involved are software engineering classes, generalization usually involves reusing code; it is often
implemented using inheritance, where the more specific code reuses the more general code.
Element Import- element import is a mechanism that allows one UML model to import an element
from another model essentially making it local (i.e. it no longer needs to be qualified when
referencing it in a constraint).
Enumeration- a set of constant values for a new data type
Enumeration Literal - one constant value contained within Enumeration
Package- a package in the Unified Modeling Language is used to group elements, and to provide a
namespace for the grouped elements. A package may contain other packages, thus providing for a
hierarchical organization of packages. All UML elements can be grouped into packages. Thus,
classes, objects, use cases, components, nodes, node instances etc. can all be organized as
packages, thus enabling a manageable organization of the myriad elements that a real-world UML
model entails.
MDHT USER GUIDE
03/29/2011
Page 6 of 36
MDHT Document1
Package Diagram- a package diagram in the Unified Modeling Language depicts the
dependencies between the packages that make up a model. In addition to the standard UML
Dependency relationship, there are two special types of dependencies defined between packages:
Package Import, Package Merge.
Package Import- a package import is a relationship between an importing namespace and a
package, indicating that the importing namespace adds the names of the members of the package
to its own namespace. By default, an unlabeled dependency between two packages is interpreted
as a package import relationship.
Package Merge- a package merge is a directed relationship between two packages that indicates
that the contents of the two packages are to be combined. It is very similar to Generalization in the
sense that the source element conceptually adds the characteristics of the target element to its own
characteristics resulting in an element that combines the characteristics of both.
Property- an attribute or an association.
Stereotype- a stereotype is one of three types of extensibility mechanisms in the Unified Modeling
Language (UML). They allow designers to extend the vocabulary of UML in order to create new
model elements, derived from existing ones, but that have specific properties that are suitable for a
particular problem domain or otherwise specialized usage. The nomenclature is derived from the
original meaning of stereotype, used in printing. For example, when modeling a network you might
need to have symbols for representing routers and hubs. By using stereotyped nodes you can
make these things appear as primitive building blocks.
MDHT USER GUIDE
03/29/2011
Page 7 of 36
MDHT Document1
4. CDA 101
Clinical Documentation Architecture (CDA) supplies a framework for specifying the full semantics of
a clinical document. CDA defines a clinical document as having the following six characteristics:
Persistence
Stewardship
Potential for authentication
Context
Wholeness
Human readability.
Any type of clinical content can be included in the CDA. Some types of typical CDA documents
include Discharge Summary, Imaging Report, Admission and Physical, Pathology Report, etc.
CDA is being used world-wide. The most popular use is for inter-enterprise information exchange
such as what is envisioned for the United States Regional Health Information Organizations
(RHIO). Most users are currently in countries such as Finland, Greece and Germany where RHIO
type exchange is well established. Future plans in the US include using CDA in the US RHIO(s)
and in the US military Health System.
In addition to use by the Regional Health Information Organizations, CDA is the basis of a variety of
experimental work within academic medical centers and research institutions. Examples of this are
the project on CDA note generation with knowledge management and controlled vocabulary at
Columbia-Presbyterian in New York, the work on CDA for decision support at Queen Elizabeth II
Hospital/Dalhousie University and the Single Source Proof of Concept at Duke Clinical Research
Institute.
CDA-compliant applications have been created by many vendors for document management,
viewing and creation. Since CDA uses Extensible Markup Language (XML), it allows for a non-XML
body (word, jpg) for simpler implementation. Therefore any web browser such as Microsoft Internet
Explorer and Firefox can parse a CDA document and using XSL style sheet covert in to HTML for
display. CDA can also be managed by an XML repository.
Implementers have a variety of choices when it comes to document generation. Many
dictation/transcription vendors have CDA as an output option. Many EHR vendors can produce
CDA documents. E-Form applications have also been produced for use with CDA.
One of the biggest existing barriers to CDA generation is when insufficient information is available
at the source for conversion. This however has not been a problem thus far from voice-interface or
keyboard entry applications.
CDA introduces the concept of “incremental” semantic interoperability. This means that there is a
range of complexity allowed within the specification and that users must set their own compliance.
The minimum clinical data architecture required are small XML metadata fields including provider
name, document type, document id, etc).
MDHT USER GUIDE
03/29/2011
Page 8 of 36
MDHT Document1
The body must also be any commonly used Multipurpose Internet Mail Exchange (MIME) type such
as a .doc, a .pdf or even a scanned image. The minimal standard metadata set and display
characteristics mean that documents could be filed and categorized. They would also be
searchable and could be retrieved along with more richly encoded documents. This would make
them all easily readable at the point of care.
MDHT USER GUIDE
03/29/2011
Page 9 of 36
MDHT Document1
5. UML 101
Unified Modeling Language (UML) is a standardized general-purpose language. Object
Management Group created and manages the standard.
UML is used in generating artifacts of an object-oriented software-intensive system along with
offering a way to view a system’s architectural blueprint.
UML is not a development method by itself. It was designed to be compatible with the leading
object-oriented software development methods of its time. Since UML has evolved, some of these
methods have been recast to take advantage of the new notations (for example OMT), and new
methods have been created based on UML, such as IBM Rational Unified Process (RUP). Others
include Abstraction Method and Dynamic Systems Development Method.
Modeling
It is important to distinguish between the UML model and the set of diagrams of a system. A
diagram is a partial graphic representation of a system's model. The model also contains
documentation that drives the model elements and diagrams
UML Diagrams represent two different views of a system model.
Static (structural) view: emphasizes the static structure of the system using objects,
attributes, operations and relationships. The structural view includes class diagrams and
composite structure diagrams.
Dynamic (behavioral) view: emphasizes the dynamic behavior of the system by showing
collaborations among objects and changes to the internal states of objects. This view
includes sequence diagrams, activity diagrams and state machine diagrams.
Models can be exchanged among UML tools by using the Extensive Markup Language interchange
(XMI) format. There are different versions of the XMI standard and that there are different levels of
compatibility between the various UML tools.
MDHT USER GUIDE
03/29/2011
Page 10 of 36
MDHT Document1
5.1. Example UML Diagram
MDHT USER GUIDE
03/29/2011
Page 11 of 36
MDHT Document1
6. MDHT Program Installation
Install instructions are applicable to Windows XP, Vista and Windows 7.
Before installing you will need to install the Java Development Kit. Use JDK 1.6 Update 23. Make
sure that the JDK can be found on the path. A common way to do that is to create a system
environment variable called JAVA_HOME and give it the path to the directory where you installed
the JDK. Then alter the Path environment variable to include %JAVA_HOME%\bin on the path.
NOTE: A problem was found trying to use this with the 64 bit JDK Therefore the 32 bit JDK should
be installed even if you have 64 bit Windows.
Download the latest MDHT All-In-One Zip File:
https://www.projects.openhealthtools.org/sf/projects/mdht/downloads/index.html
Click on Designers: All-in-one ZIP, quick and easy! (~200MB) If it states that the file is too
large, perform the following to download.
Click on the documents folder.
Click on downloads
Click on doc1660: allinone
Click save to save the file to your computer
Navigate to directory where file should be saved. It is recommended that the file be saved
to My Computer-Local Disk (C) and named MDHT CDA Tools. This will allow for easier
trouble shooting in the future.
MDHT USER GUIDE
03/29/2011
Page 12 of 36
MDHT Document1
Unzip the downloaded file in the current location. (Use something like 7Zip. Do NOT use the
Windows Compressed Folders Extraction Wizard - it has problems with some of the long file
names.)
Run Eclipse.exe and verify the environment
You will find this in the following location:
\MDHT_CDATools_M7\eclipse\eclipse.exe
Note that when Eclipse starts up, it should build the entire project. The following problem may occur
when it builds:
MDHT USER GUIDE
03/29/2011
Page 13 of 36
MDHT Document1
"Manifest has no main section".
If this occurs, the problem needs to be resolved before proceeding. Do the following steps to
resolve this:
1) Highlight all of the projects in the Project Explorer window
2) Right-click on the highlighted projects and select "Refresh" from the context menu.
3) This will cause all projects to be refreshed and rebuilt. Once they are all rebuilt, this should
resolve the build problems.
a) Make sure that java compatibility is set to 1.5
b) Select "Preferences" from the "Window" menu
c) Expand the "Java" item
d) Select the "Compiler" item.
e) Change "Compiler compliance level" to 1.5
f) Select "OK" and let it rebuild everything again.
g) Verify that the build was successful
h) Expand the project: "org.openhealthtools.mdht.uml.cda"
i) Expand the "src" folder
j) Expand the "org.openhealthtools.mdht.uml.cda.tests" package
k) Right click on the "Main.java" file and select "Run As" and "Java Application" from the
context menu.
l) This will use the class library to generate and validate an instance of a CDA document in
the console window. The output in the console window will show the example XML that was
generated following by the validation results. The results should state "Document is Valid".
MDHT USER GUIDE
03/29/2011
Page 14 of 36
MDHT Document1
7. Understanding a Template Model
7.1. Organization of the Template Model
Accessing the Example Model
Before learning to edit the template, it is important to understand how it is set up. The following
includes steps and screenshots for understanding the template. The example.uml model is
focused on learning, clone, re-factor and make it your own. The Example model illustrates the
basic structures that every CDA implementation guide/model has with the purpose being to exhibit
the model techniques.
1) In Windows, click on the following to run eclipse and access the Example UML model
a) My Computer
b) Local Drive C
c) MDHT CDA Tools
d) MDHT_CDA Tools_M7
e) Eclipse
f) Run Eclipe.exe
2) Once eclipse has been executed, expand the example model
a) Click the + sign next to openhealthtools.mdht.uml.cda.example.model
MDHT USER GUIDE
03/29/2011
Page 15 of 36
MDHT Document1
b) Double click the model
c) Double click example.uml
MDHT USER GUIDE
03/29/2011
Page 16 of 36
MDHT Document1
d) The table editor will appear on the right showing template classes
Understanding the Example Model
1) Every CDA template is represented as a UML class.
a) In a CDA implementation guide, every class must be derived from a subclass of the CDA
base model
b) The UML model containing all the different classes is the CDA base model
c) There is a class for every complex type in the CDA schema.
d) Every implementation guide needs to be specialized with a specific clinical document.
e) The purpose of the example UML is to illustrate the basic structures that most every CDA
implementation guide has.
2) Notice that there are subclasses of classes
a) Every implementation guide takes the CDA model and specializes it for a particular type of
clinical document.
b) Template classes are often times reused
c) A document also contains sections such as history of present illness, past medical history,
review of systems, etc. Each of these sections might be where the physician would include
the corresponding information.
d) These domains are named ending with Section. For example: A History & Physical
contains at least one section which could be Past Medical History section.
e) This will be revisited again when we discuss re-using existing templates.
MDHT USER GUIDE
03/29/2011
Page 17 of 36
MDHT Document1
f) Keep in mind that CDA is the least restrictive model.
g) Notice the “Open” headed arrow – denotes a “subclass of” and it denotes which existing
template it derives from.
i) Every implementation guide has at least one template class derive from a Clinical
Document.
h) Notice the “Solid” headed arrow denotes the UML association from one class to another –
i.e. the relationship between templates – contains – representing a constraints.
3) The multiplicity domain in the editor can describe the requirements for each document and the
conformance rules
a) This domain provides information about how many sections the document must contain
b) The severity of the constraint is described with conformance rules in one of the following
ways: SHALL (required) contain, SHOULD (suggested) contain or MAY (allowed) contain a
specific section
c) A problem is constrained for a particular purpose to make it easier to solve
d) The number in the multiplicity domain denotes the minimum and maximum number of
observations.
e) In the case of 1.*, this denotes that there must be at least one but that it can be multiple.
MDHT USER GUIDE
03/29/2011
Page 18 of 36
MDHT Document1
8. Editing the Example Model
8.1. Creating a New Template
1) When editing a model
a) Have multiple model templates open when working with the relationship across models.
b) Cda.uml is the CDA base model which is the meat and bones (standard) of an
implementation guide.
c) Restrictions or constraints are being added to the base CDA standard, thus making the
standard more implementable.
d) Information is being restricted as to what can be contained in a particular type of document.
2) Editing a model can consist of:
a) Adding a template;
b) Placing constraints on attributes;
c) Setting the severity of attributes; and/or
d) Making associations between models.
3) Models are located in the models folder.
a) Model names appear under the mdht.uml.cda.model.example
4) Adding a template to a Model
a) Right click on desired package
b) Click on add CDA template.
MDHT USER GUIDE
03/29/2011
Page 19 of 36
MDHT Document1
5) Enter Name of template when prompted
6) You will then be prompted for the class or CDA that is it derived from
7) You will then be prompted for the constraint
MDHT USER GUIDE
03/29/2011
Page 20 of 36
MDHT Document1
a) Everything needs to be a subclass of something from CDA.
b) If you are adding a section, you would add section from CDA.
c) Enter attributes to constrain
d) Your new section will then be added.
e) Right click on your new section and select the UML association.
8) Templates
a) Are independent and reusable
b) By creating templates that are independent of one another, they are able to be used in
different types of documentation.
9) Models
a) Will most likely contain all templates relating to specific sections (example-History of
Present Illness Model, Vital Signs template).
Understanding the Difference between Templates and Models
Templates are not clinical documents.
Templates represent patterns of usage. In XML terms,
they are essentially restrictions on the base CDA schema. In UML, terms, they are considered
specializations of the UML classes in the base CDA model.
Models are not clinical documents.
Much like there is a set of "base" CDA XML schemas, in MDHT we have created a set of base
UML models for CDA. Additionally, there are models of the restrictions (or constraints) on top of
the base CDA model. These are called "template models".
Template models are groups of CDA
templates that are "modeled" using the UML and Object Constraint Language (OCL) formalisms.
MDHT USER GUIDE
03/29/2011
Page 21 of 36
MDHT Document1
8.2. Creating an Association between Templates
1) Associations are made to templates by adding sections that the template must contain.
a) For example, a clinical document must contain at least one vital signs section.
b) A closed arrow denotes the association to what it is pointing to. Example: A consultation
note contains a vital sign section thus showing the constraint of the consultation note.
i) In this example, My Document shall (required) contain at least 1 MySection as indicated
by the constraint in the multiplicity field.
8.3. Creating a Constraint on an Attribute
Constraints are made on attributes to constrain information that can be placed in certain documents
thus making the CDA standard more implementable.
1) To constrain an attribute
a) Click on the template to view the code to be constrained. In this example, you are viewing
the MyDocument template.
MDHT USER GUIDE
03/29/2011
Page 22 of 36
MDHT Document1
b) Right click on the attribute to be constrained. In this example you will be constraining
MySection.
c) Click add UML, Select Constraint
8.4. Setting the Severity of the Constraint
Setting the severity of the code will always be based on Shall (required), Should (suggested) or
May (allowed).
1) Right click on the template to set the severity of a constraint.
a) What you can constrain about an attribute depends on its attribute.
b) If you are constraining a code field, you are specifying exactly what terminology is being
placed in that field in the medical documentation and possibly constraining the actual code
that it must be set to.
c) The severity of the constraint is described with conformance rules in one of the following
ways: SHALL (required) contain, SHOULD (suggested) contain or MAY (allowed) contain a
MDHT USER GUIDE
03/29/2011
Page 23 of 36
MDHT Document1
specific section. The behavior of the severity will appear as follows in eclipse: Shall will
show up in eclipse as an error if it is validated, Should will show up as a warning.
d) A problem is constrained for a particular purpose to make it easier to solve.
e) The number in the multiplicity domain denotes the minimum and maximum number of
repetitions of this element.
8.5. Modeling Vocabulary
When writing implementation guides with the MDHT system you want to restrict the codes that can
be taken on for a particular implementation guide. By applying constraints you can have only
certain coded values you are targeting in the your restricted value set. For example, the
implementation guide can be coded to particular medical terminology. One well-defined value set
that can be used is the toy value set in the example model. The key with modeling vocabulary is
restricting and remaining optionality to make it the guide easier to implement.
MDHT USER GUIDE
03/29/2011
Page 24 of 36
MDHT Document1
9. Transforming the Model to Source Code
and Regenerating
Once a change has been made to a model, a transformation must be made to generate the new
Java Code.
1) This is done by right clicking on the transform.xml.
a) Click Run As.
MDHT USER GUIDE
03/29/2011
Page 25 of 36
MDHT Document1
2) Click Ant Build.
a) Select radial button “Run in the same JRE as the workspace.”
b) Click Apply.
c) Click Run.
MDHT USER GUIDE
03/29/2011
Page 26 of 36
MDHT Document1
d) You will see the build status in the console window. If you do not receive an error code, it
should state “Build Successful.”
3) That process updates the example_encore.uml.
a) The process performed transformed the .uml to the examplegen model.
b) The next step is to generate the Java code.
4) Right click the example generation model.
a) Click Reload to reload the UML model.
MDHT USER GUIDE
03/29/2011
Page 27 of 36
MDHT Document1
5) Select UML model, click Next.
6) You will see a UML import screen, click Next.
MDHT USER GUIDE
03/29/2011
Page 28 of 36
MDHT Document1
7) The progress of the Java code generation will show, click Next.
MDHT USER GUIDE
03/29/2011
Page 29 of 36
MDHT Document1
8) Click Finish on the package selection screen.
MDHT USER GUIDE
03/29/2011
Page 30 of 36
MDHT Document1
10. Regenerating the Code
1) The example.genmodel tab will appear in the right window.
a) Right click on Example and select Generate Model Code.
2) A progress bar will appear.
3) The Java code has now been generated.
MDHT USER GUIDE
03/29/2011
Page 31 of 36
MDHT Document1
11. Transforming to DITA and Reloading the
Model
Once the Java Code is generated the model must be transformed to DITA (Darwin Information
Typing Architecture)
The first time you transform the DITA and reload the model you will need to perform the following
steps. All subsequent times, all you will need to do is Run as Ant.
1) Right click ditatransform.xml.
a) Right click Run As.
b) Click Ant Build.
2) Click JRE tab.
a) Select radial button “Run in the same JRE as the workspace.”
b) Click Apply then Run.
MDHT USER GUIDE
03/29/2011
Page 32 of 36
MDHT Document1
The output will appear in the console window. If the build was successful, it will state “Build
Successful.”
The DITA content is then updated.
3) To republish the data, right click, select Publish.
MDHT USER GUIDE
03/29/2011
Page 33 of 36
MDHT Document1
12. Activities in the Publication Process
There are two activities within the publication process. There is an interactive approach and the
publishing approach.
12.1. Adding Snippets
To launch an interactive snippet generation, perform the following:
1) Right click on template.
a) Click CDA tools.
b) Click Generate Sample Instance.
This shows an example of the generated XML.
MDHT USER GUIDE
03/29/2011
Page 34 of 36
MDHT Document1
To launch the DITA pub transformation which generates snippets for every class defined.
2) Right click on ditaform.xml.
a) Click Run As.
b) Click Ant Build.
3) Click JRE tab.
a) Select radial button “Run in the same JRE as the workspace.”
b) Click Apply then Run.
MDHT USER GUIDE
03/29/2011
Page 35 of 36
MDHT Document1
This shows an example of DITA generated file including a XML snippet.
The MDHT XML Snippet Generation attempts to generate reasonable approximation of the
corresponding XML. The process uses the UML model and source code to determine what
aspects of the class are Shall, Should, and May and populates them accordingly. Effective Dates
and ID are generated automatically.
The XML snippet is correct in syntax, but the content should not be viewed as a genuine record
content.
MDHT USER GUIDE
03/29/2011
Page 36 of 36