hide revision marks€¦ · web view01/06/2006 · use a lower case "v" rather than...
TRANSCRIPT
Hide Revision Marks
Version 3 Publishing Facilitator's GuideChair of Publishing Committee Helen Stevens
[email protected] Gordon Point Informatics
Publishing Facilitator Joann [email protected] Permanente
Editor Donald [email protected] Level Seven, Inc.
Last Published: 03/26/2006 8:48 PM
HL7® Version 3 Standard, © 2005 Health Level Seven®, Inc. All Rights Reserved.
HL7 and Health Level Seven are registered trademarks of Health Level Seven, Inc. Reg. U.S. Pat & TM Off
Table of ContentsPrefacei Notes to Readersii Acknowledgementsiii Changes from Previous Releaseiv Known Issues & Planned Changes1 Overview1.1 Introduction and Scope2 Roles and Responsibilities2.1 Publishing Committee Leadership2.2 Publishing Facilitators2.3 Technical Publications Manager3 Publishing Schedule4 Reference Documents5 Style Guide for Narrative Content5.1 Language5.1.1 Use of SHALL, SHOULD and Other Modal Verbs5.2 Capitalization5.2.1 Section Headings5.2.2 Key Terms5.2.3 Titles5.3 Commonly Used Grammar Conventions5.3.1 A and An Convention5.3.2 Version Expression5.3.3 The Use of Commas in a Series5.3.4 Quotation Marks and Punctuation5.4 Lists5.5 Spelling Conventions
5.6 Tables5.7 Figures, Images and Other Graphics5.8 Use of External Hyperlinks5.8 9 Redundancy5.9 10 Subsection Guidelines5.10 11 Annexes6 HTML Markup7 Artifact Identification7.1 Structured Sort Names7.2 Artifact Codes8 Graphics9 Document Structure9.1 Introduction9.1.1 General Principles9.2 Title, Authors and Copyright Notice9.2.1 Required9.2.2 Recommended9.2.3 Best Practices9.3 Preface and Table of Contents Section9.3.1 Required9.3.2 Recommended9.3.3 Best Practices9.4 Overview Section9.4.1 Required9.4.2 Recommended9.4.3 Best Practices10 Content Domains10.1 Introduction10.1.1 General Principles10.1.2 Publication Section Indexes10.2 Domain Message Information Models (DMIM)10.2.1 Required10.2.2 Recommended10.2.3 Best Practice10.3 Storyboards10.3.1 Required10.3.2 Recommended10.3.3 Best Practice10.4 Application Roles10.4.1 Required10.4.2 Recommended10.4.3 Best Practices10.5 Trigger Events10.5.1 Required10.5.2 Recommended10.5.3 Best Practice10.6 Refined Message Information Models (RMIM)10.6.1 Required10.6.2 Recommended10.6.3 Best Practices10.7 Hierarchical Message Descriptions10.7.1 Required10.7.2 Recommended10.7.3 Best Practices10.8 Interactions
10.8.1 Required10.8.2 Recommended10.8.3 Best Practice11 Common Domains11.1 Common Message Element Types (CMETs)11.2 Shared Messages11.3 ClinicalStatementPattern11.4 Messaging Infrastructure11.4.1 Wrappers12 Supporting Documents12.1 Foundation Documents12.1.1 Reference Information Model12.1.2 Data Types Abstract12.1.3 Vocabulary12.1.4 Refinement, Constraint and Localization12.1.5 GELLO12.2 Background Documents12.2.1 Version 3 Guide12.2.2 Glossary12.2.3 Methodology
Appendices
A Publishing ToolsA.1 InstallationB Templates and Building BlocksB.1 Graphic TemplatesB.2 Content TemplatesC HL7 Mailing ListsC.1 Editors ListC.2 Tooling Committee's Mailing ListD Storyboard NamesD.1 New Storyboard NamesD.2 PatientsD.3 Healthcare StaffD.4 OrganizationsD.5 FacilitiesE Section, Subsection and Domain CodesF Artifact CodesG Document CodesH Realm CodesI Publication Process and ChecklistJ Adding Annexes to Topics in a DomainJ.1 IdentificationJ.2 Using <div/> tags to structure an AnnexK Managing ComponentsK.1 Managing a large number of GIF filesK.2 Managing a large amount of storyboard content over many topics
Preface i Notes to Readers
The Publishing Facilitator's Guide is intended to assist the Publishing Facilitator in creating and maintaining correct and consistent HL7 Version 3 Standards. It is also intended to assist balloters by providing rules for required and recommended elements within an HL7 Version 3 Standard.
This document is part of our ongoing effort to create more "background documentation" and was first published in September 2005 in conjunction with the HL7 Development Framework (HDF) and the Version 3 Substantivity Guide.
It also contains some elements of a "V3 Style Guide." Content creators are encouraged to follow the rules and guidelines that are contained in this document. Balloters may refer to this document when requesting that documents be changed to "follow the rules."
ii Acknowledgements
Many members of the HL7 community proofed early drafts of this document and provided valuable feedback.
This document was created in response to Dick Harding's request to "bring back the style guide."
The Publishing Committee would like to thank Dick Harding, Lloyd McKenzie, Joann Larson, June Rosploch, Ken McCaslin and Alexis Grassie for comments and suggestions on early drafts.
iii Changes from Previous Release
This is document has been updated from the original that was published in September 2005 based on ballot comments. We have added a section on References. The Style Guide for Narrative Content has been expanded significantly. The appendixStoryboard Names has also been updated with new cast members and an outline of the process for adding to the list.
Typos and other minor corrections were also made. The text was updated to conform to the Style Guide for Narrative Content.
iv Known Issues & Planned Changes
This is a draft. We are looking for comments, feedback and additional examples.
1 Overview 1.1 Introduction and Scope
The HL7 Version 3 Standards are a collection of related standards built upon a common Reference Information Model. Due to the extensive range of standards the development of consistent content and presentation can become a complex task. The HL7 Modeling & Methodology Committee has produced the HL7 Development Framework to guide the technical development of the standards. The HL7 Tooling Committee is mandated with developing appropriate tooling to support this
methodology. The HL7 Publishing Committee is responsible for developing a presentation of the Version 3 standards that is a consistent, easy to use format that is appropriate for a variety of audiences.
This document presents an overview of the Publishing Process, the tools that are used to create the content, and some guidance on creating consistent and correct content. The goal of this document is to provide the information needed to create a consistent Version 3 Standard that conforms to the M&M methodology and uses the appropriate tooling.
2 Roles and Responsibilities 2.1 Publishing Committee Leadership
The Publishing Committee is an HL7 Board appointed committee and as such the leadership of the committee is appointed by the chair of the HL7 Board of Directors. The committee co-chairs are changed or reconfirmed whenever the HL7 Chair is changed.
The role of the Publishing Committee Co-chair(s) are as follows:
Chair conference calls and meetings. Liaison with HL7 Board, TSC, International Affiliate Realms and other
committees as necessary to represent the HL7 Publishing Committee and provide updates as appropriate.
Ensure that appropriate HL7 policies and procedures are followed by the committee.
Guide the activities of the Publications Technical Manager in accordance with his role and responsibilities.
2.2 Publishing Facilitators
The Publishing Facilitator is a person responsible for the submission of content to the HL7 Publishing committee to be published on behalf of a committee or realm.
All HL7 groups (Technical Committee (TC), Special Interest Group (SIG), Realms, Focus Group or Project) that are in the process of developing content that will be submitted for consideration as an HL7 standard must select a Publishing Facilitator. The selection process is governed by the group's processes (for example elected or appointed).
For the purposes of simplicity in this document we will refer to the group for which the facilitator acts the "TC" recognizing that it may in fact be any of the above mentioned types of groups.
Although the focus of this document is for Version 3 standards it should be noted that a Publishing Facilitator should also be assigned for management of the Version 2 standards and this may be the same person at the discretion of the TC. The traditional term "Editor" was determined to be inadequate, as it did not represent the full range of activities and responsibilities expected of this role; consequently the Publishing Committee felt that creating another term would encompass these expanded responsibilities.
The role of a Publishing Facilitator includes the following:
Participating as a member of the TC for which he is acting. Informing the TC of any issues, questions or decisions from the Publishing Committee that may affect the group.
Participating in the Publishing Committee conference calls and meetings whenever possible. Informing the Publishing Committee of any issues, questions or decisions from the represented TC relevant to publishing.
Ensuring that the TC is aware of any schedules or deadlines from Publishing. Ensuring that a Ballot Request for Information Form is submitted to HL7 HQ by
the deadline as is required for content to be included in a Ballot Cycle. Ensuring that the TC's content is submitted to Publishing in the correct format,
using the correct tooling by the required schedule to meet the publishing deadlines.
Ensuring that the TC's content is represented correctly and completely during testing (Preview) and that any revisions are submitted appropriately.
Note that although it is the responsibility of the Publishing Facilitator to ensure the above items, it is not necessarily his responsibility to perform all these tasks himself. The division of tasks within a TC is the responsibility of the TC's leadership.
2.3 Technical Publications Manager
HL7 HQ employs a Technical Publications Manager (TPM) who is responsible for supporting the HL7 Publishing Committee's activities. This role provides a consistent point of contact for all publishing related queries and support for the Publishing Facilitators and other HL7 members working on the development of HL7 standards.
The role of the Technical Publications Manager includes the following:
Attending HL7 Publishing Committee meetings and conference calls Receiving content from the TC's for consideration to be published by the
Publishing Committee. Responding to HL7 Member queries regarding Publishing Committee activities
or directing these queries to the Publishing committee co-chairs as appropriate. Supporting Publishing Facilitators in the conversion of content to Publishing
approved formats or in performing Quality Assurance as requested by the Publishing Committee co-chairs.
Other activities in support of the publishing Committee as requested by the co-chairs or HL7 Leadership.
3 Publishing Schedule
The HL7 content developed must undergo balloting prior to approval as HL7 standards. The process of publishing the documents and voting on them is known as a Ballot Cycle. Currently the Publishing Committee schedules ballot cycles prior to each Working Group Meeting (WGM). The results of a Ballot Cycle are discussed at the next WGM; consequently the ballot cycle is named for the year and month when
the next WGM occurs. For example, the 2005Sep Ballot Cycle opened on August 1 and closed on September 3, and the WGM ran from September 11-16.
The Publishing Schedule is defined by the Publishing Committee each year and then presented to the Technical Steering Committee (TSC) at the Plenary Working Group Meeting for approval. The Publishing Schedule becomes official after the TSC accepts it. The current Publishing Schedule can be found on the HL7 Website on the Publishing Committee's webpage. Any TC may opt in or out of any ballot cycle. There is NO requirement to ballot a document in every cycle if resources are not available or if the content is not ready to be submitted for another round of balloting. If a TC decides to opt-out of a ballot cycle they may request one of the following:
1. Content from the previous cycle be re-presented with no changes. A note will be added to indicate that the content is not open for balloting and is only being displayed to show the last balloted material. Any comments received on this material may be processed by the committee according to their internal processes and are not subject to the normal ballot reconciliation rules.
2. The current work in progress may be presented with a note indicating that that the material is for comment only to show the current working direction of the TC. Any comments received on this material may be processed by the committee according to their internal processes and are not subject to the normal ballot reconciliation rules.
3. The content may be removed completely from the ballot cycle. This is not available for any documents upon which other documents are reliant or may reference (e.g. Shared Messages). This strategy is not always recommended as it triggers questions about where the material may have gone.
The Publishing Schedule outlines deadline dates of the Publishing Process which must be met in order to publish and ballot the content. The deadlines are designed to ensure a high quality of balloted material and unnecessary negative votes are avoided. The schedule includes a two-week testing/preview period and a five-day window for ballot package preparation. Some of the critical deadlines on the Publishing Schedule include:
Ballot AnnouncementA Ballot Announcement must be sent to the membership 30 days before a ballot cycle opens. Any documents that are to be included in the ballot cycle must be a part of this announcement; since this is an ANSI and HL7 requirement no exceptions will be made. It is the responsibility of the Publishing Facilitator to ensure that the TC co-chairs return a completed Ballot Request for Information Form to the Project Management website in order to be included in a Ballot Cycle. Please note that the HL7 Policy on Ballot Reconcilations requires that all TCs and SIGs properly complete the reconciliation and negative voter notification requirements before they can re-ballot their domain content.
Ballot Preview and Testing PeriodThe Ballot Preview and Testing period is a two week window prior to the ballot cycle opening that provides an opportunity to look at the content on the Ballot Preview Site before the Ballot Cycle officially opens. During the Ballot Preview Period, the Publishing Facilitator, and other TC members, should review the content to ensure that it is complete and ready to be voted upon. Any errors or omissions should be identified and either corrected by the Publishing Facilitator
or brought to the attention of the Publishing Committee prior to ballot cycle opening. During the preview period the Publishing Committee will commit to updating the preview site with corrections within 48 hours of receiving the corrected content (usually sooner).
Content DeadlineThe Final Content Deadline is usually set to seven days before the Ballot Cycle is scheduled to open. This is the deadline for any content to be submitted to the Technical Publishing Manager if it is to be included in the ballot cycle. The Publishing Committee has allocated a full week between the content deadline before the ballot cycle open date because it is necessary to use this time to build the ballot website. In addition, the Publishing Committee reserves the right to establish interim content deadlines to aid the construction of the preview web site and coordinate cross-domain publishing. Any content not received by the published final content deadline will not be included in the ballot cycle with the following exception: If a preview of the content has been received and processed AND permission is requested and granted based on extreme special circumstances an extension may be considered. Examples of extreme circumstances include unexpected tooling problems or the publishing facilitator being hit by a bus.
Ballot Cycle OpenThe Ballot Cycle Open and Close dates are the bookends to the Ballot Cycle. During the time between the Open and Close dates, the Ballot Cycle is referred to as being Open. This means that HL7 members (and paying non-members) will be reviewing and voting upon the content.There is generally at least a one week period between the closing of a Ballot Cycle and the following Working Group Meeting. This week is reserved to allow for the tabulation of the votes and organization of the reconciliation meetings during the WGM. The intent is that the TC discuss the votes and comments received during the ballot cycle on its content at the Working Group Meeting.
Refer to the HL7 Ballot Desktop documentation for more information on Balloting.
4 Reference Documents
The authority for style and grammar rules in HL7 publications is the Chicago Manual of Style (CMS). Any exceptions to the CMS will be noted.
The authority for spelling and meaning is the Webster's Third New International Dictionary, Unabridged.
The authority for spelling and meaning of new, technical terms, not present in Webster's, is a documented use of the term in any of the following documents, in order:
1. an Institute of Electrical and Electronics Engineers (IEEE) standard 2. an Internet Engineering Task Force (IETF) standard 3. the Word Wide Web Consortium (W3C) Glossary 4. an ISO Standard, or 5. an ANSI standard
The authority for spelling and meaning of medical or other healthcare terms is National Library of Medicine Medline Plus Dictionary. An example of such a word is pharmacogenomics, which would not be in a "normal" dictionary, but is a valid medical term.
HL7 is not in the business of coining new words. If a need is found, the new word is to be submitted to the Publishing Committee for approval. Newly coined words must appear in the glossary.
5 Style Guide for Narrative Content
Narrative content within the HL7 standard SHALL be consistent from one document to another and professionally presented. To attain this objective, the Publishing Committee, based on comments received during the balloting process and committee review, has established the rules and conventions set forth in this section. Relevant material from the v2 Style Guide has also been brought forward.
This section is to be used in conjunction with the HL7 Development Framework.
5.1 Language
HL7 publications are written in formal American English.
Note the following characteristics of formal American English:
Complete sentences with proper and complete punctuation SHALL be used rather than sentence fragments. An exception to this is a list where fragments may be used.
Contractions SHALL NOT be used Colloquial expressions SHOULD NOT be used Acronyms MAY be used provided the initial entry within any published domain
or topic specifies the full name of the entity followed by the acronym in parenthesis (see 1st preference in CMS, Section 15). If the acronym is defined in the HL7 Glossary, a hyperlink MAY be provided.
5.1.1 Use of SHALL, SHOULD and Other Modal Verbs
This section describes the terminology for expressing the stringency of a conformance statement.
HL7 adheres to ISO/IEC directive, Appendix G, as delineated in the following table:
Table 1: Stringent Use of SHALL, SHOULD and Other Modal Verbs
To Convey the Sense of: Use the Following:
Required/Mandatory SHALL SHALL NOT
Best Practice/Recommendation SHOULD SHOULD NOT
Acceptable/Permitted MAY NEED NOT
Examples:
You SHALL clean your room before going out.
The action is REQUIRED. If the specified action is not performed, the following action is NOT allowed.
You SHOULD clean your room before going out.
The action is RECOMMENDED or a BEST PRACTICE. This a practice that is believed to be beneficial.
You MAY clean your room before going out.
This action is ALLOWED.
5.2 Capitalization
This section addresses capitalization issues frequently encountered in HL7 publications.
5.2.1 Section Headings
Section headings are expressed in Title capitalization. For example:
Introduction Basic Types Constraints Catalog
5.2.2 Key Terms
Key Terms are in Title Case and are not bold faced, in italics or underlined.
The exceptions to this are the Conformance Verbs which are in All Caps. Note that this does not apply when these verbs are used as an incidental part of the sentence and not meant as conformance statement.
The first occurrence of a key term in a section SHALL be hyperlinked to the glossary.
For example:
SHALL NOT Application
5.2.3 Titles
Titles are in title case.
For example:
GELLO: A Common Expression Language
HL7 Reference Information Model Domain: Patient Administration
5.3 Commonly Used Grammar Conventions
This section delineates certain grammar conventions that are commonly used.
5.3.1 A and An Convention
Use the article "an" before acronyms, abbreviations or initialisms that begin with a consonant but sound like a vowel. For example:
an HL7 table an ST data type an XML fragment a DTD an ANSI Standard a LOINC Code
5.3.2 Version Expression
Use a lower case "v" rather than spelling out the word "version" only if the version number appears, e.g., "v3.0". Otherwise, spell out the word version, e.g., "in earlier versions of the standard".
5.3.3 The Use of Commas in a Series
Use commas to separate elements in a series, but do not put a comma before the conjunction in a simple series.
This matter is addressed fully in CMS 6.18. The general rule is that the comma, aside from its technical uses in mathematical, bibliographical, and other contexts, indicates the smallest break in sentence structure. It denotes a slight pause. Effective use of the comma involves good judgment, with ease of reading the end in view
For example:
DMIMs, RMIMs and Storyboards are all artifacts. With gratitude to my parents, Mother Teresa, and the Pope.
In the first example, we have a list of artifacts. A comma is not needed after "RMIMs." In the second example, we place a comma before the last "and" to make it clear that Mother Theresa and the Pope are not our parents.
5.3.4 Quotation Marks and Punctuation
Double quote marks (") are used at the outermost level. Single quote marks(') are used for a quote embedded within another quote. See CMS, Section 11.33.
Periods and commas precede closing quotation marks; colons, semicolons, question marks and exclamation points follow. The exception is a question mark or exclamation point belongs within the quoted matter. Also note that it acceptable to put the period outside the quote when the quote is part of a string of computer code. See CMS, section 6.8 and 6.9
For Example:
"The 'Wild Horses' bass line is very good," Include the type identifier: type="text/JavaScript".
Note that "smart quotes" are not supported by the publishing tools. The most common method for inserting "smart quotes" into a PubDB is to copy text from a Word document. Use simple quotes instead.
5.4 Lists
From a practical standpoint a bulleted list should be used only when there are a small number of points, such as 5 or 6, that can be easily scanned. If greater than that, an alpha or numbered list should be used. A numbered list suggests steps or sequence more strongly than an alpha list. An alpha list may be used for either sequential points or non-sequential points (when the list is lengthy and bullets would lack precision). A list that contains a single element SHALL NOT be used.
Care should be used when a bulleted list requires sub-bullets or has lengthy narrative.
Consider recasting a lengthy list as sub-sections with narrative.
Care should be taken when a section includes more than one list. This makes it difficult for the reader to reference the location of a list item. Such an occurrence usually signals that a new topic was being discussed and SHOULD be moved to its own section or sub-section.
Unless the list items themselves form complete sentences, lowercase the first letter of each item in a multiple-choice list and omit periods:
This is an example of an unordered list:
unordered list item 1 unordered list item 2
This is an example of an ordered list of steps:
1. first step 2. second step 3. third step 4. fourth step
5.5 Spelling Conventions
The following are commonly used words that appear inconsistently throughout the HL7 documentation. The correct spelling is:
data type rather than datatype walk-through rather than walkthrough or walk through. artifact rather than artefact acknowledgement rather than acknowledgment specialization rather than specialisation authorization rather than authorisation
5.6 Tables
Tables are used to present organized information in a row and column format. See The Storyboard Names Appendix for an example of table usage.
Single row tables SHOULD NOT be used.
5.7 Figures, Images and Other Graphics
For complete information on the use of figures, images and other graphics, please see the section later in this guide titled Graphics (§ 8 ).
5.8 Use of External Hyperlinks
While Publishing does support the use of External Hyperlinks to relevant and important information external to the V3 Standard, committees should be attentive to the lack of control over the stability of external links. Consequently, any committees that incorporate hyperlinks to external sources in their documents should take steps to ensure that the destination of that hyperlink is permanently stable, recognizing that these hyperlinks may well eventually be incorporated into the Normative Standards. Normative Standards are released once a year, so a general suggestion is that the hyperlink be stable for a minimum of 2 years after the date that the content passes final balloting. If a hyperlink can not be assured as stable for 2 years, the content should be included directly in the Normative material or moved to an HL7 controlled website where it can be maintained as stable. Publishing encourages committees to err on the side of caution and not reference external sources unless it is absolutely necessary. Publishing will be happy to help you incorporate material or relocate it to a stable website.
5.8 9 Redundancy
The document SHOULD NOT have redundant text. Hyperlinks to a single source of the information are preferred for a variety of reasons, not the least of which is ease of maintenance. If you only have to correct information in one place, this should reduce the frequency of errors.
5.9 10 Subsection Guidelines
A Section SHALL NOT have a Subsection with the same name.
The Section Name SHOULD clearly identify the Section content to the reader; The reader should not have to guess which "Examples" Section to look at.
The document SHOULD be subdivided into sections when multiple lists are needed.
The document SHOULD be subdivided into sections when the length of a single section would make it difficult for the reader to grasp.
Each section will appear as a hyperlink in the Table of Contents, which is an advantage to dividing the document into shorter sections.
5.10 11 Annexes
Annexes appear following the main body of the document and contain supplemental information. By default annexes are not Normative. However, under ISO rules an annex can be normative in certain situations. Annexes that are normative should be clearly identified as such.
Annexes will be "auto named" during the rendering process in the sequence Annex A, Annex B, Annex C, etc.
6 HTML Markup
All Description (memo type) fields in the PubDb support a subset of HTML-like tags to assist with formatting and display. Note that none of these tags should have an XML namespace specified.
The following XHTML-like tags are allowed in the PubDb description fields:
This list is not complete
Formatting:
Ordered list <ol> <li> (close each with </li> </ol>) Unordered list <ul> <li> (close each with </li> </ul>) Bold Emphasis <b> (close with </b>) Italics <i> (close with </i>) Note: You may not nest <b> and <i>
Diagram References:
← <diagref ref="{filename}"/>
Artifact References:
← <artref ref="{artifact code}" alt="{Caption text}"></artref>
Term References:
← <xtermref href="{term}" >Term</xtermref>
Graphics:
← <graphic source="./Graphics/{fileName}.gif" alt="{Caption text}"/>
Line Break – will occur:
At a pair of CR/LFs (carriage return-linefeed combination) after </li>, where a CR/LF immediately follows </b> or </i> [A single CR/LF is replaced with a space.] after a paragraph (<p> … </p>
It is recommended that you reference standard XHTML documentation for more information on how to use XHTML tags. In the future, publishing will be moving to use a more complete set of XHTML tags, including use of the appropriate namespace.
7 Artifact Identification 7.1 Structured Sort Names
All Artifacts will sort in the Publication using the Structured Sort Name (SSN). Artifacts will also have a 'Title Name' which will appear as the Artifact title and should be "human reader friendly", but will not be used for sorting. The reason for using the SSN for sorting is to ensure that the content is organized in a logical and consistent manner between different domains. The PubDb has a Widget to assist in the assigning of correct SSN codes to the different Artifacts. Additionally, if an Artifact has an invalid SSN assigned a warning will appear in the PubDb. A full description of the SSN is included in Version 3 Guide.
7.2 Artifact Codes
All Artifacts within HL7 Version 3 SHALL be identified with a unique Artifact Code. An Artifact Code is reserved for an individual artifact and SHALL NOT be reused, replace or removed once the Artifact has been approved as standard. The following convention is used to create the Artifact Codes:
UUDD_AAnnnnnRRvv
Table 2: Artifact Coding System
Code Description
UU Sub-Section code
DD Domain code
AA Artifact or Document code
nnnnnn Six digit zero-filled number
RR Realm code
VV Version code
Example:PORX_AR000001UV01Practices & Operations Sub-Section, Pharmacy Domain, Application Role Artifact number 00001, Universal Realm, Version 01.
See the Artifact Code Table for more details.
8 Graphics
Graphics are used as illustrations of models and processes. If a graphic is "too large" it will be taken out of the document and a hyperlink will be generated. This is done to keep the document text from being rendered off the right side of the screen, which would require horizontal scrolling to read the document. To keep your graphics inline, keep them less than 600 pixels wide.
The general rule for keeping graphics inline is "Go Long, not Wide"
Figures are automatically rendered and numbered.
Here is an example of an inline figure (generated from an image that is less than 600 pixels in width).
Here is an example of a linked graphic (generated from an image greater than 600 pixels in width).
Link to wide graphic (opens in a new window)
See the Appendix Graphic Templates for templates that you can use to create many of the common graphics.
9 Document Structure 9.1 Introduction
The purpose of this section is to provide guidelines to assist in the development of consistent document structures for all documents published by HL7. The requirements within this section apply to any document published by HL7 including standards, specifications, implementation guides and supporting documents.
9.1.1 General Principles
Sections in this chapter will be identified with one of the following categories
Requirement – These items SHALL be followed to produce content that is compliant with the Version 3 Methodology. Any omissions of required items will automatically prevent a document from being published and consequently being included in a ballot cycle. Helpful checklists have been provided to assist in ensuring all required elements are included.
Recommendation – These items SHOULD be followed. However, the TC may decide to vary from this item if it is not applicable or appropriate to the content being developed
Best Practice – These items are examples that have been highlighted from previous content submissions that are particularly good or helpful. A TC MAY choose to follow these items as appropriate.
9.2 Title, Authors and Copyright Notice 9.2.1 Required
The Document Title SHALL appear at the top of the document and SHOULD be a short, clear, unique document name by which the document will be referred.
The Title SHALL be followed by the list of Authors with the Name, email, employer/sponsor as well as the role that the Author played in the development of the document. This list of authors is used to identify those individuals who are primary contacts for the document and should be maintained as current (i.e. when co-chairs change, the Authors must be updated).
Chair of Publishing Committee Helen [email protected] Gordon Point Informatics
Publishing Facilitator Joann [email protected] Permanente
Editor Donald [email protected] Level Seven, Inc.
The Authors SHALL be followed by the following copyright information and statements:
Last Published: 03/15/2006 11:48 AM [Date and time to reflect the appropriate publishing information.] HL7® Version 3 Standard, ©2005 Health Level Seven®, Inc. All Rights Reserved. HL7 and Health Level Seven are registered trademarks of Health Level Seven, Inc. Reg. U.S. Pat & TM Off
Please note that vor Version 3 documents these statements are inserted automatically during the build process.
9.2.2 Recommended
The Authors list SHOULD contain a listing of the following individuals:
1. Committee Co-Chair(s) 2. Modeling and Methodology Facilitator 3. Vocabulary Facilitator 4. Publishing Facilitator
Other individuals SHALL be acknowledged in the Acknowledgements section of the Preface.
9.2.3 Best Practices
Past chairs and primary contributes may be acknowledged in the Preface using the following format:
The committee is indebted to the following past co-chairs, facilitators and primary contributors for their contributions towards the Public Health domain and the material presented here.
Name Role Organization
Linda Quade Past RCRIM Co-Chair/Facilitator Eli Lilly and Company
Austin Kreisler Primary Contributor SAIC Consultant to the
CDC
9.3 Preface and Table of Contents Section
The Preface SHALL use the following ordering:
1. Notes to Readers 2. Acknowledgements 3. Changes from Previous Release 4. Prerequisites, Assumptions and Conventions 5. Known Issues and Planned Changes 6. Other Notes 7. Message Design Element Navigation
9.3.1 Required
Notes to Readers Changes from Previous Release Message Design Element Navigation (created automatically during the
publishing process)
The Changes from Previous Release sections SHALL list all Substantive Changes that have been made since the last time that the document was balloted.
9.3.2 Recommended
The Acknowledgements section SHOULD be used to formally acknowledge individuals and organizations that contributed to the creation of the document that are not listed in the Authors Section.
The Prerequisites, Assumptions and Conventions section SHOULD be used to provide the reader with an overview of background material.
The Known Issues and Planned Changes section SHOULD be used to provide the reader with a brief overview of areas that the TC has identified as requiring additional work and some indication as to what will be done to address them.
The Changes from Previous Release section SHOULD be used to describe the changes in general terms. You should tell the reader where significant changes were made and the type of change that was made. The information in this section should allow the reader to easily locate and identify artifacts that have been changed.
9.3.3 Best Practices
The Changes from Previous Release Sections MAY include hyperlinks to each Section that has been changed.
9.4 Overview Section 9.4.1 Required
The Overview’s first sub-section SHALL be entitled “Introduction and Scope” a this section SHALL contain a description of the Document at a minimum sufficient for a person unfamiliar with the work to understand the document’s business, scope and relationship with HL7.
The Introduction and Scope section SHALL also explain the need for a Specification.
Content Domains SHALL include a section entitled “Domain Message Information Model (DMIM). (See Domain Message Information Models (DMIM) (§ 10.2 )below)
9.4.2 Recommended
The Overview SHOULD include a sub-Section, immediately following the Introduction and Scope entitled “Domain Analysis Model” if such a model has been developed for the document.
9.4.3 Best Practices
None.
10 Content Domains 10.1 Introduction
The purpose of this section is to provide guidelines to assist in the development of consistent, methodology conformant Version 3 content domains. Content Domains include messaging domains that conform to the Version 3 methodology for message development. Refer to the Appendixes for a list of current content domains.
The content domains are listed in the publication ballot as either Administrative Management Domains or Health and Clinical Domains. The Common Domains follow some of the guidelines, however there may be noted exceptions where the structure
does not apply. Refer to the Common Domains section for information specific to these domains.
Sections in this chapter will be identified with one of the following categories:
Requirement – These items SHALL be followed to produce content that is compliant with the Version 3 Methodology. Any omissions of required items will automatically prevent a document from being published and consequently being included in a ballot cycle. Helpful checklists have been provided to assist in ensuring all required elements are included.
Recommendation – These items SHOULD be followed. However, the TC may decide to vary from this item if it is not applicable or appropriate to the content being developed
Best Practice – These items are examples that have been highlighted from previous content submissions that are particularly good or helpful. A TC MAY choose to follow these items as appropriate.
10.1.1 General Principles
A Domain is a way to organize standards that are related to a common area of healthcare. The Domain Name should clearly convey some meaning to the Standard Developer, but most importantly, to the reader. For example, Patient Administration and Pharmacy are concepts that the reader can grasp. It is not necessary, or expected, for all the content developed by a particular TC to fit within a single Domain. There will be cases where a TC has content in more than one Domain and there will be cases where a Domain contains content from more than one TC.
A Topic is subdivision of a Domain that allows the Domain to be organized so that the reader can quickly identify and focus in on the content they are looking for.
The following example is drawn from the Personnel Management domain and shows how four Topics have been created.
The reader should have a clear idea of the document's contents by looking at the Topic Titles and Domain Names. Topic Titles like "Topic 1" or "Combined" or "Not Specified" SHALL NOT be used. The Topic Title is rendered in both the Table of Contents and the Document as "Topic_Title Topic". When you create a Topic Title, you should consider how it will appear to the reader in the Document and the Table of Contents.
TIn addition to a Topic Title, a Topic Structured Name must be defined. The Topic Structured Name is the base of the Structured Sort Name (SSN). The Topic Structured Name must be short (one word is recommended).
When creating topic Structured Name, keep in mind that no topic name can be the opening string of another topic structured name. (e.g. "Care" and "Care Record" are not OK. "Care Record" and "Care Transfer" are OK.).
The order that the Topic appears within the Domain is specified by setting the Sort Order field for the Topic in the PubDB.
10.1.2 Publication Section Indexes
The beginning of each section in the publication includes three indexes to provide links to the artifacts. These indexes are designed to support a variety of readers and
their requirements. It is not necessary for the Publishing Facilitator to do anything to create or manage these indexes as they are automatically generated by the publishing process.
Sorted by Title - alphabetical list by title name Sorted by Structured Sort Name - alphabetical list by the SSN Sorted by Display Order - This is a list showing the Title name, but sorted by the
order that the artifacts will appear in the publication which is based on an algorithmic calculation of the SSN.
Note that the SSN is used to algorithmically organize the artifacts into a logical order based on the components of the SSN (for example mood Proposal, then order, then intent, then event). For details on how this works please look at the Version 3 Guide.
10.2 Domain Message Information Models (DMIM)
The Domain Message Information Model (D-MIM) is a subset of the Reference Information Model (RIM) that includes a fully expanded set of class clones, attributes
and relationships that are used to create messages, documents and other static models for a particular domain.
The basic principle is One DMIM Per Domain.
The DMIM is a unified model that represents how all classes and attributes fit together. The DMIM SHOULD be refined so that it is less abstract. Simply copying the RIM into your DMIM is not sufficient. The DMIM SHALL be understandable.
Don't re-invent the wheel. If you are modeling a concept that exists in another Domain, work with them. If you can find a CMET, use it.
For more information on DMIMS, see the Version 3 Guide
Each Domain SHALL contain one DMIM.
10.2.1 Required
Title Code Structured Sort Name Walk-through
10.2.2 Recommended
TBD
10.2.3 Best Practice
TBD
10.3 Storyboards
A Storyboard consists of a short description, typically less than 100 words, and an Storyboard Interaction Diagram that shows the progression of Interactions between Application Roles. A Storyboard narrative is a description of a real-life event that provides the necessary context for the development of a specific set of Interactions described in the Storyboard.
Storyboards SHOULD explain the use of appropriate artifacts that are in the Domain or Topic.
The process of creating Storyboards lays the foundation for describing HL7 Messages and their content.
The names of persons, places and organizations that are used in Storyboards and examples are fictional. Any resemblance of actual persons, living or dead, or places and/or organizations is unintentional and coincidental.
Storyboard Names are intended to be reflective of the role they play within HL7. Any name that is trademarked will be addressed as it is brought to our attention.
For more information on Storyboards, see the Version 3 Guide
10.3.1 Required
Title Code Structured Sort Name Purpose Diagram Interaction List Narrative Title Narrative Code Narrative Structured Sort Name Narrative Text
General Rules:
1. There SHALL be at least one Storyboard within a topic. 2. Storyboards SHALL use the names and contact information as outlined in the
(§ ) for all entities (People, organizations etc).
3. Where a storyboard references an artifact, that artifact SHOULD be explicitly identified.
4. The appropriate level of artifact (e.g., message type, application role, trigger event, or document) SHOULD be used in one or storyboards.
5. Each Storyboard narrative SHOULD be an "alternative" narrative that fulfills the purpose. Storyboards should not build or depend upon each other (cumulative).
o NOT: create/update/replace o OK: Admit Emergency; Admit Inpatient
10.3.2 Recommended
Use sub-headings (HTML markup) within the Storyboards to organize the information.
Insert hyperlinks to glossary definitions of Application Roles, Trigger Events or Interactions in the narratives.
Support hierarchical Storyboards where one Storyboard can list Storyboards that are dependent upon it. This is done by identifying and linking to a parent Storyboard in the dependent Storyboard's purpose statement using the HTML markup
10.3.3 Best Practice1. Storyboard Narrative Headings. The following is an example of a structure
within the Storyboard narrative. o Introduction introduces the environment where the Storyboard is
occurring and any existing systems or assumptions in that environment and
o Story Event describes the actual event that is the subject of the Storyboard and the cause of the messaging. Within the Story Event is a listing of the Message Flow where each Interaction is listed and explained.
2. Avoid including excess information that is not relevant to the data exchange (e.g., messaging or documents) scenario. If it is not relevant to the HL7 data exchange artifacts being described in the ballot, leave it out. If it is relevant, put it in.
Example Storyboard
Storyboard Interaction Diagram. The following is an example of a good Storyboard Interaction Diagram. Specifically:
Application Roles are identified by Title Name and code Interactions are identified by Title Name and code All interactions are listed (see note under the heading)
Sample Storyboard Interaction Diagram 10.4 Application Roles
Application Roles represent a set of communication responsibilities that might be implemented by an application. They describe system components or sub-components that send or receive Interactions or produce or consume Documents. Application Roles are not presently Normative.
Published Application roles SHALL be aggregated at a general level reflecting commonly expected combinations of functionality.
For more information on Application Roles, see the Version 3 Guide
10.4.1 Required
Title Code Structured Sort Name Description
10.4.2 Recommended
The Title Name for any Application Role SHOULD be meaningful and unique.
10.4.3 Best Practices
TBD
10.5 Trigger Events
A Trigger Event is an explicit set of conditions that initiate the transfer of information between system components (Application Roles).
Each Trigger Event SHALL have a Trigger Event Type defined from one of the following three values:
State-transition based: Based on the state transition of a particular focal class. Some trigger events MAY be based on more than one state transition. If a trigger is associated with more than one state transition, it is assumed that both transitions occur at the same time
Interaction based: Occurs when a specific interaction is received Environment based: (Also known as User Request based) Occurs at the request
of a human user or other environmental factor (e.g. fixed point in time, particular record count, etc.)
For more information on Trigger Events, see the Version 3 Guide
10.5.1 Required
Title Code Structured Sort Name Description Trigger Event Type
Provide a clear description referencing the State Transition diagram if applicable.
10.5.2 Recommended
Document the State Transition diagram and any variations from the RIM diagram, if needed to understand the Domain.
10.5.3 Best Practice
TBD
10.6 Refined Message Information Models (RMIM)
Each Refined Message Information Model (R-MIM) is a proper subset of the D-MIM for that domain and contains only those classes, attributes and associations required to compose the set of messages derived from the Hierarchical Message Descriptions (HMD) that originate from the R-MIM root class.
For more information on RMIMs, see the Version 3 Guide
10.6.1 Required
Title Code Structured Sort Name Description
10.6.2 Recommended
TBD
10.6.3 Best Practices
TBD
10.7 Hierarchical Message Descriptions
Hierarchical Message Descriptions (HMD) and their resulting Message Types define the message payload. An HMD is a tabular representation of the sequence of elements (i.e., classes, attributes and associations) represented in an R-MIM that define the Message without reference to the Implementation Technology. The HMD defines a single base message structure - the "common" message type. A Message Type represents a unique set of Constraints applied against the common message.
For more information on HMDs, see the Version 3 Guide
10.7.1 Required
Title Code Structured Sort Name Description
10.7.2 Recommended
TBD
10.7.3 Best Practices
TBD
10.8 Interactions
An Interaction is a unique one-way transfer of information consisting of:
Trigger Event Transmission Wrapper Control Act Wrapper Message Type
Interactions are Normative.
For more information on Interactions, see the Version 3 Guide
10.8.1 Required
Title Code Structured Sort Name Description Initiating Trigger Event Message Type Query Type in a Response Control Act Wrapper Transport Wrapper
10.8.2 Recommended
Sending Application Role(s) Receiving Application Role(s)
10.8.3 Best Practice
Initial experience with the first two ballot cycles has revealed four basic interaction patterns. These patterns should be the primary focus of committee-level development.
State Transition Notification – Sending application is notifying receivers of the occurrence of a state transition
State Transition Request – Sending application is requesting an action that will cause a state transition
Fulfillment Request Query
State Transition Notification Pattern:
Starts with interaction type Event Notification Trigger event must always be state transition based. May involve multiple state-transitions (possibly on different focal classes)
E.g. Replace trigger is tied to an "Obsolete" and a Null-to-normal transition Sending Application Role is Informer Receiving Application Role is Tracker No Receiver Responsibility
State Transition Request Pattern:
Starts with interaction type Request for Action Trigger event must always be environment-based.
May involve multiple state-transitions (possibly on different focal classes)E.g. Replace trigger is tied to an "Obsolete" and a Null-to-normal transition
Always has an associated interaction of type Request Response-Refuse Interaction has a trigger that is 'Interaction Based' on the previous Request for
Action Has at least one additional interaction of type Request Response-Accept Interaction has a trigger that is 'Interaction Based' on the previous Request for
Action AND is associated with a state transition for the focal class for the Confirmation
Sending Application Roles
Placer One or more types of Confirmation Receiver for a focal class that has a "fulfills"
relationship of the class on which a transition is being requested. Translation:
o Proposals are confirmed by Orders, Intents or Events o Orders are confirmed by Intents or Events
Receiving Application Roles
Fulfiller (not "filler") One or more types of Confirmer for a focal class that has a "fulfills" relationship
of the class on which a transition is being requested. Translation:
o Proposals are confirmed by Orders, Intents or Events o Orders are confirmed by Intents or Events
Fulfillment Request Pattern
To Be Written
Query Pattern
Starts with interaction type Query Trigger event is of type User-Request Always has an associated interaction of type Query Response Interaction has a trigger that is "Interaction Based" on the previous Query
Sending Application Roles
Informer Placer Translation: Proposals are confirmed by Orders, Intents or Events Orders are confirmed by Intents or Events
Receiving Application Roles
Tracker Fulfiller (not "filler") One or more types of Confirmer for a focal class that has a 'fulfills' relationship
of the class on which a transition is being requested. Translation:
o Proposals are confirmed by Orders, Intents or Events o Orders are confirmed by Intents or Events
11 Common Domains
The Common Domains are domains that generally follow the structure of the Content Domains; however they are designed to be used by the Content Domains and as such may not include all the same Artifacts. For example Common Message Element Types do not include Interactions.
11.1 Common Message Element Types (CMETs)
Common Message Element Types (CMETs) are a work product produced by a Technical Committee for expressing a common, useful and reusable concept. They are generally "consumed", or used by both the producing committee and other committees.
Because they are intended for common use across messages produced by all committees, they are proposed to, reviewed by, and maintained by the CMET task force of the Modeling and Methodology committee. The CMET task force harmonizes and becomes steward for all CMETs.
A CMET can be envisioned as a message type fragment that is reusable by other message types. Any message type can reference a CMET, including other CMETs. As an example, several committees may require the use of a common concept, that of a person in the role of a patient. A CMET can be defined to express this concept as a message type that clones a role played by a person, with all appropriate attributes. The CMET is then used to uniformly represent the concept for all interested committees.
Your domain SHOULD use CMETs wherever possible so that you do not have to "reinvent the wheel."
The process for creating and using "local" CMETs is documented on the HL7 website.
For more information on CMETs, see the Version 3 Guide
11.2 Shared Messages
Shared Messages are a work product produced for expressing common, useful and reusable message types. A Shared Message can be envisioned as a message type that is reusable in interactions in any of the domains within the HL7 standard.
The scope of the Shared Messages Domain includes message types shared by all the clinical domains. The domain model consists of a minimalistic Act payload used to convey generic information related to an Act and its associated classes. Although CMET terminology does not apply to Message Types, the Common Messages domain model can be thought of as an Act CMET [minimal].
The Act in the Shared Message DMIM can be thought of as a reference to, or as a summary version of, an act. This includes use-cases such as the notification of a status change of an act, the sending of application level accept/reject messages, the registration of acts in repositories, and responding to Act-related queries.
Note: The Shared Messages domain will include storyboards, application roles, trigger events, interactions, and message types shared by any of the healthcare domains. Some of these will be for example purposes only. The examples will not be used in their own right but as a reusable payload in various domains. When used in this fashion, the message is transmitted as a result of a domain interaction and between two domain application roles. Artifacts will be documented as to whether they are examples or can be used in their own right.
11.3 ClinicalStatementPattern
The model described in this document is a pattern designed to be used within multiple HL7 Version 3 domain models. This "pattern" is intended to facilitate the consistent design of communications that convey clinical information to meet specific use cases. It is not intended that the "pattern" itself is ever used in a communication, and consequently the information in this document is necessarily at a high level with a minimum of constraints applied. The "pattern" does NOT represent a Record Architecture or a physical structure for storing data on an EHR database, although it does cover many of the types of clinical information that should be part of an Electronic Health Record.
The formal definition of clinical statement for the care of patients is:
"An expression of a discrete item of clinical (or clinically related) information that is recorded because of its relevance to the care of a patient. Clinical information is fractal in nature and therefore the extent and detail conveyed in a single statement may vary. To be regarded as a clinical statement, a concept must be associated with a patient in a manner which makes clear:
Its temporal context Its relationship to the patient In the case of an observation, its mood and presence, absence or value In the case of a procedure, its mood and status
This clarity may be achieved by
Explicit representation; or Implicit application of defaults ONLY where explicitly modeled rules state the
appropriate defaults." 11.4 Messaging Infrastructure
The HL7 Infrastructure addresses the following aspects of the communications environment that is considered common to all
HL7 Version 3 messaging implementations: A specification for the composite HL7 Version 3 message. A protocol for reliable message delivery. Generic "Communication Roles" that support the modes of HL7 messaging. Message control events that describe a framework for generic HL7 messaging.
11.4.1 Wrappers
HL7 Version 3 provides a substantial level of functionality in the provision of envelopes to support the transport of HL7 messages from sender to receiver. HL7 calls these Wrappers. Wrappers are defined in the same way as message content; by defining object classes and relationships. These specifications can then be used to generate an XML schema, or other ITS-defined syntax to go on the wire.
12 Supporting Documents 12.1 Foundation Documents
The HL7 Version 3 Methodology is built upon a foundation that includes the RIM, Vocabulary, Abstract Data Type definition, conformance rules and a Common Expression Language (GELLO).
These documents are published with the Version 3 material so that they can be referenced by the reader when reviewing the standard's documents. It is important that Publishing Facilitators link appropriately to this reference material and not duplicate it within individual documents. A hyperlink may be made to the foundation documents from any description (or text) field within the Domains. If the foundation content were duplicated within the domain it is possible that it will become outdated as the foundation content is updated; by using the appropriate hyperlinks the facilitator will ensure that the link is maintained to the current version of the foundation material.
12.1.1 Reference Information Model
The Health Level Seven (HL7) Reference Information Model (RIM) is a static model of health and health care information as viewed within the scope of HL7 standards development activities. It is the combined consensus view of information from the perspective of the HL7 working group and the HL7 international affiliates. The RIM is the ultimate source from which all HL7 version 3.0 protocol specification standards draw their information-related content.
Each Domain's DMIM SHALL be a subset of the RIM.
For more information, see the Reference Information Model
12.1.2 Data Types Abstract
This document specifies the HL7 Version 3 Data Types on an abstract layer, independent of representation. By "independent of representation" we mean
independent of both abstract syntax as well as implementation in any particular implementation technology.
This document is accompanied by Implementation Technology Specifications (ITS). The ITS documents can serve as a quick compendium to the data types that is more practically oriented toward the representation in that particular implementation technology.
Vocabulary tables within this specification list the current contents of vocabulary domains for ease of reference by the reader. However, at any given time the normative source for these domains is the vocabulary tables in the RIM database. For some large domains, only a sample of possible values is shown. The complete domains can be referenced in the vocabulary tables by looking up the domain name associated with the table in the RIM vocabulary tables.
12.1.3 Vocabulary
The HL7-defined Vocabulary domain tables that have been developed for coded class attributes are stored in the HL7 repository, from which a number of views have been extracted to produce the HL7 Vocabulary Domain Listings for the HL7 Reference Information Model (RIM). The views are presented in table format and include the HL7 Vocabulary Domain Values, the HL7 Domain Tables and Coded Attributes Cross-reference. HL7-recognized external vocabulary domains are described in the External Domains list.
For more information, see the HL7 Vocabulary
12.1.4 Refinement, Constraint and Localization
The Version 3 Messaging standard provides a rich set of messages to support communications in a variety of clinical and other health related endeavors. Moreover, HL7 Version 3 messages will be specific enough to permit strong conformance claims to be asserted and verified. Refer to Conformance Statements for more details. Nevertheless, any standard faces two challenges. First, it can always be made more specific in order to provide a more precise solution to a particular requirement. Second, it will not contain all of the data needed in every environment, particularly when international requirements are considered. These challenges lead to a pair of complementary requirements: the ability to constrain the standard in more detail, and the ability to extend the standard in a controlled fashion.
12.1.5 GELLO
GELLO is a class-based, object-oriented (OO) language that is built on existing standards. GELLO expression language is based on the Object Constraint Language (OCL), developed by the Object Management Group. Relevant components of OCL have been selected and integrated into the GELLO to provide a suitable framework for manipulation of clinical data for decision support in health care.
12.2 Background Documents 12.2.1 Version 3 Guide
The Version 3 Guide is a useful introduction to the concepts that underlie Version 3, provides an introduction to terminology that is used, and gives an overview of the basic layout of a Version 3 Standard.
12.2.2 Glossary
There are actually several Glossaries that are published as part of Version 3. Each Domain contains a Glossary of terms that are defined and used within it. The main Version 3 Glossary is a combination of the terms from each Domain and Core Terms that are common to all Version 3 Standards.
As a Publishing Facilitator, you will define the terms that are used in your Domain. These Domain Terms and their definitions are referred to as the Domain Glossary. The publishing process will automatically generate the Glossary for your Domain, and will also place your Domain's terms into the Combined Glossary.
The Core Glossary is maintained by the Publishing Committee. It contains terms that are commonly used in all Version 3 Standards. For example, artifact and mandatory are defined in the Core Glossary.
Before you define a term in your Domain Glossary, you should look to see if it exists in the Core Glossary. You should not define a term in your Domain Glossary if it would duplicate the definition that is in the Core Glossary. However, if your Domain uses a term in a manner that is different from the Core Definition, you should add it to your Domain Glossary. For example, Application is defined in the Core Glossary and refers to a software program; Application is defined by Personnel Management in the context of applying for a job.
For more information, see the HL7 Glossary
12.2.3 Methodology
The Health Level 7 (HL7) Development Framework Methodology Specification is a product of the HL7 Development Framework (HDF) project. The purpose of the Health Level Seven (HL7) Development Framework Project is to research, analyze, design, and document the processes, policies, and artifacts associated with development of HL7 standards specifications.
If you are new to developing HL7 Standards, this is a very good reference.
For more information, see the HL7 Development Framework.
A Publishing Tools
The complexity of the Version 3 methodology and interdependence between the components of the standard requires that tools be used to develop the standard and to publish it in a consistent manner. Although some TC's may chose to use common applications such as MS Word while they are developing the content it is necessary to convert any content into the standard Publishing tools and technologies before it can be published and balloted.
A.1 Installation
All HL7 Version 3 Publishing Tools may be downloaded from the Tools Website. The following table is a summary of the tools.
Table 3: Version 3 Domain Documentation Tools
Tool Description
Pub DBInstaller of PubDB as MSI
Installs a Publication DB and necessary support files. VB code in the Pub DB will invoke WYSIWYG editing of the XML markup using XML Spy Suite 4.4 or 5.0 Supports local publication of domain content. Requires CURRENT RoseTree. User Guide included. Be sure to "remove" or uninstall the previous version before installing this one.
PubDB Merge WidgetInstaller --DBManage -msi
The Pub DB Manager is a widget created to facilitate the merger of PubDbs, both across domains and within a domain. Its primary focus is for internal use in publishing HL7 ballots, and is offered with no additional documentation.
Stand-alone DescriptionEditorDescEditor as MSI
The Description Editor is a component of the Pub Db that can be installed separately to support editing of descriptive text for HL7 ballots. Do not install this if RoseTree and/or the PubDb are already on your system. It is installed as part of those packages and a separate installation will cause conflicts. User Guide included.
Table 4: Version 3 Static Model Design & Documentation Tools
Tool Description
RMIM Designer HL7_RmimDesign Installer.msiCMETinfo.txt in ZIPFormal Naming FormalNamingSource
Link is Windows Installer (Win2k, XP, ME).
Contents: This is an intelligent installer for the HL7 R-MIM design templates for interactive design with Visio 2000 or 2002. These tools do not work with Visio 2003 (See advisory).
This tool requires a Design/RIM Repository (below) and the installation of RoseTree (below) to function. The installer includes instructions for installation and use of these tools. This is the latest "official" release.
CMETinfo.txt file is used by the RMIM design tools (in Visio) to specify the CMETs that may be included in a design. This file should be downloaded and placed in your Visio "Solutions\HL7" directory if it is more recently
released than the Visio RMIM Designer tools
Formal naming in the RMIM designer can be updated independently from the Formal Naming Source file. Installation instructions are on a ReadMe in the archive.
RIM, Voc Naming Design/RIM Repository in ZIP
The most recent HL7 Model Repository for capturing message designs. Includes the most recent RIM and Vocabulary. This is updated as additional columns and tables are added to the repository.
Note: Use of this design repository with the RMIM Designer (in Visio) or with other RoseTree-supported applications requires RoseTree Version 3.0.0 or later.
The archive also holds the latest formal naming source file for the RMIM Designer in Visio. This source file can also be downloaded separately.
RoseTree RoseTree II.msi (downloads "msi" file needs Win Installer)
Contents: This is the most current release of RoseTree, which builds R-MIMs and HMDs for the Version 3 demonstration. This will INSTALL RoseTree.exe on your system, works with the published, R-MIM-enabled repository. It will also install Microsoft's MSXML4 (if this is not already on your machine) to perform XML extracts from Repository. Be sure to "remove" or uninstall the previous version before installing this one.
HL7 Design Documentation Editor CICmDocEdit.msi
The HL7 Design Documentation Editor (CICmDocEdit) is an application for attaching detailed annotations to individual rows of HL7 Version 3 message designs. The power of the editor stems from the ability to re-use a particular definition based upon the semantic scope of the element being annotated. User Guide included. (Provided by Clinical Information Consultancy and Beeler Consulting)
Some of these tools are updated frequently; consequently it is recommended that facilitators check this page before beginning any work to ensure that they are using the latest versions of the tools. When a new version of a tool is available, an announcement is usually sent to the editor's mailing list.
The general order for installing the tools is:
1. RoseTree must be installed before the RMIM Designer (in Visio). RoseTree also installs MSXML4, which is used by the RMIM Designer and Visio.
2. XMLSpy should be installed before the PubDB.
3. Visio is used to create the graphical representations of the models (DMIM, RMIM, CMETs, etc), as well as the other diagrams that appear in the document.
Note that before you install an updated version of any of the HL7 Tools, you must uninstall the previous version.
B Templates and Building Blocks
You don't have to create all of this from scratch. Here is a list of templates and fragments that can be used as a starting point for creating diagrams and other content.
B.1 Graphic Templates
Storyboard Template State Diagram Template
B.2 Content Templates
Need some ideas here.
C HL7 Mailing Lists
HL7 has many electronic mailing lists. Several of them will be of interest to Publishing Facilitators. Publishing Facilitators must subscribe to the Editors list and the domain list(s) where they are serving. They may also want to subscribe to the general HL7 list for general announcements to the community at large.
This is a complete listing of HL7 mailing lists.
C.1 Editors List
This is the primary mailing list for Publishing Facilitators.
Subscribe to the Editor's Mailing list
C.2 Tooling Committee's Mailing List
This is the primary mailing list for Tooling Developers and for the announcement of new releases of tools.
Subscribe to the Toolng Committee's Mailing list
D Storyboard Names
The names of persons, places and organizations that are used in storyboards and examples are fictional. Any resemblance of actual persons, living or dead, or places and/or organizations is unintentional and coincidental.
Storyboard Names are intended to be reflective of the role they play within HL7. Any name that is trademarked will be addressed as it is brought to our attention.
The "cast of Patients, Healthcare Staff, Organizations and Facilities" in the following tables SHALL be used.
D.1 New Storyboard Names
Requests for additional cast names required to create new Storyboards need to be sent to the Publishing Committee. The Publishing Committee will review the request. The Publishing Committee SHALL reject any proposed names that:
← refer to real persons or places ← are racially or ethnically insensitive ← infringe on a trademark
D.2 PatientsTable 5: Patient Information for Storyboards
Cast Family Given MI Gender SSN Phone Street
patient, female Everywoman Eve E F
444-22-2222
555-555-2003
2222 Home Street
patient, male Everyman Adam A M
444-33-3333
555-555-2004
2222 Home Street
patient, child Kidd Kari K F
444-55-5555
555-555-2005
2222 Home Street
family, daughter Nuclear Nancy D F
444-11-4567
555-555-5001
6666 Home Street
family, husband Nuclear Neville H M
444-11-1234
555-555-5001
6666 Home Street
family, son Nuclear Ned S M
444-11-3456
555-555-5001
6666 Home Street
family, wife Nuclear Nelda W F
444-11-2345
555-555-5001
6666 Home Street
next of kin Mum Martha M F 444- 555- 4444
(parent) 66-6666
555-2006
Home Street
next of kin (child) Sons Stuart S M
444-77-7777
555-555-2007
4444 Home Street
next of kin (spouse) Betterhalf Boris B M
444-88-8888
555-555-2008
2222 Home Street
next of kin (other) Relative Ralph R M
444-99-9999
555-555-2009
4444 Home Street
contact person Contact Carrie C F
555-22-2222
555-555-2010
5555 Home Street
D.3 Healthcare StaffTable 6: Healthcare Staff for Storyboards
Cast Family Given MI
Gender SN Pho
neCel
l Street
healthcare provider Seven Henry L M
333-33-3333
555-555-1002
955-555-1002
1002 Healthcare Drive
assigned practitioner Assigned Aman
da A F333-44-444
555-555-1021
955-555-1021
1020 Healthcare Drive
physician Hippocrates Harold H M
444-44-4444
555-555-1003
955-555-1003
1003 Healthcare Drive
primary care physician
Primary Patricia
P F 555-55-5555
555-555-1004
955-555-
1004 Healthcare Drive
1004
admitting physician Admit Alan A M
666-66-6666
555-555-1005
955-555-1005
1005 Healthcare Drive
attending physician Attend Aaron A M
777-77-7777
555-555-1006
955-555-1006
1006 Healthcare Drive
referring physician Sender Sam S M
888-88-8888
555-555-1007
955-555-1007
1007 Healthcare Drive
intern Intern Irving I M888-22-2222
555-555-1022
955-555-1022
1021 Healthcare Drive
resident Resident Rachel R F888-33-3333
555-555-1023
955-555-1023
1022 Healthcare Drive
chief of staff Leader Linda L F888-44-4444
555-555-1024
955-555-1024
1023 Healthcare Drive
authenticator Verify Virgil V M999-99-9999
555-555-1008
955-555-1008
1008 Healthcare Drive
specialist Specialize Sara S F
222-33-3333
555-555-1009
955-555-1009
1009 Healthcare Drive
allergist/immunologist Reaction Ramse
y R M222-22-3333
555-555-1025
955-555-1025
1024 Healthcare Drive
anesthesiologist Sleeper Sally S F222-66-6666
555-555-1012
955-555-1012
1012 Healthcare Drive
cardiologist Pump Patrick P M222-33-4444
555-555-1027
955-555-1027
1025 Healthcare Drive
cardiovascular surgeon Valve Vera V F
222-33-5555
555-555-1028
955-555-1028
1026 Healthcare Drive
dermatologist Scratch Sophie S F 222-33-6666
555-555-1029
955-555-
1027 Healthcare Drive
1029
emergency medicine specialist
Emergency Eric E M
222-33-7777
555-555-1030
955-555-1030
1028 Healthcare Drive
endocrinologist Hormone Horace H M
222-33-8888
555-555-1031
955-555-1031
1029 Healthcare Drive
family practitioner Family Fay F F
222-33-9999
555-555-1032
955-555-1032
1030 Healthcare Drive
gastroenterologist Tum Tony T M
222-44-2222
555-555-1033
955-555-1033
1031 Healthcare Drive
geriatrician Sage Stanley S M
222-44-3333
555-555-1034
955-555-1034
1032 Healthcare Drive
hematologist Bleeder Boris B M222-44-3344
555-555-1035
955-555-1035
1033 Healthcare Drive
infectious disease specialist
Pasteur Paula P F222-44-5555
555-555-1036
955-555-1036
1034 Healthcare Drive
internist Osler Otto O M222-44-6666
555-555-1037
955-555-1037
1035 Healthcare Drive
nephrologist Renal Rory R M222-44-7777
555-555-1038
955-555-1038
1036 Healthcare Drive
neurologist Brain Barry B M222-44-8888
555-555-1039
955-555-1039
1037 Healthcare Drive
neurosurgeon Cranium Carol C F222-44-9999
555-555-1040
955-555-1040
1038 Healthcare Drive
OB/GYN Fem Flora F F222-55-2222
555-555-1041
955-555-1041
1039 Healthcare Drive
oncologist Tumor Trudy T F 222-55-3333
555-555-1042
955-555-
1040 Healthcare Drive
1042
ophthalmologist Vision Victor V M222-55-4444
555-555-1043
955-555-1043
1041 Healthcare Drive
orthopedic surgeon
Carpenter Calvin C M
222-55-5545
555-555-1044
955-555-1044
1042 Healthcare Drive
otolaryngologist (ENT) Rhino Rick R M
222-55-6666
555-555-1045
955-555-1045
1043 Healthcare Drive
pathologist Slide Stan S M222-44-4444
555-555-1010
955-555-1010
1010 Healthcare Drive
pediatrician Kidder Karen K F222-55-7777
555-555-1046
955-555-1046
1044 Healthcare Drive
plastic surgeon Hollywood
Heddie H F
222-55-8888
555-555-1047
955-555-1047
1045 Healthcare Drive
psychiatrist Shrink Serena S F
222-55-9999
555-555-1048
955-555-1048
1046 Healthcare Drive
pulmonologist Puffer Penny P F222-66-2222
555-555-1049
955-555-1049
1047 Healthcare Drive
radiologist Curie Christine C F
222-55-5555
555-555-1011
955-555-1011
1011 Healthcare Drive
rheumatologist Joint Jeffrey J M222-66-3333
555-555-1050
955-555-1050
1048 Healthcare Drive
surgeon Cutter Carl C M222-77-7777
555-555-1013
955-555-1013
1013 Healthcare Drive
urologist Plumber Peter P M222-66-4444
555-555-1051
955-555-1051
1049 Healthcare Drive
physician assistant
Helper Horace
H M 222-66-5555
555-555-1052
955-555-
1050 Healthcare Drive
1052
registered nurse Nightingale Nancy N F
222-88-8888
555-555-1014
955-555-1014
1014 Healthcare Drive
nursing assistant Barton Clarence C M
222-99-9999
555-555-1015
955-555-1015
1015 Healthcare Drive
chiropractor Bender Bob B M222-66-6666
555-555-1053
955-555-1053
1051 Healthcare Drive
dentist Chopper Charlie C M
222-66-7777
555-555-1054
955-555-1054
1052 Healthcare Drive
orthodontist Brace Ben B M222-66-8888
555-555-1055
955-555-1055
1053 Healthcare Drive
optometrist Specs Sylvia S F222-66-9999
555-555-1056
955-555-1056
1054 Healthcare Drive
pharmacist Script Susan S F333-22-2222
555-555-1016
955-555-1016
1016 Healthcare Drive
podiatrist Bunion Paul B M222-77-2222
555-555-1057
955-555-1057
1055 Healthcare Drive
psychologist Listener Larry L M222-77-3333
555-555-1058
955-555-1058
1056 Healthcare Drive
lab technician Beaker Bill B M333-44-4444
555-555-1017
955-555-1017
1017 Healthcare Drive
dietician Chow Connie C F333-55-5555
555-555-1018
955-555-1018
1018 Healthcare Drive
social worker Helper Helen H F333-66-6666
555-555-1019
955-555-1019
1019 Healthcare Drive
occupational therapist
Player Pamela
P F 222-77-6666
555-555-1059
955-555-
1057 Healthcare Drive
1059
physical therapist
Stretcher Seth S M
222-77-8888
555-555-1060
955-555-1060
1058 Healthcare Drive
transcriptionist Enter Ellen E F333-77-7777
555-555-1020
955-555-5555
1058 Healthcare Drive
Pastoral Care Director
Sacerdotal Senior S M
333-77-7777
555-555-1020
955-555-5555
1058 Healthcare Drive
Chaplain Padre Peter P M333-77-7777
555-555-1020
955-555-5555
1058 Healthcare Drive
Informal Career Comrade Connor C M
333-77-7777
555-555-1020
955-555-5555
1058 Healthcare Drive
Electrophysiologist
Electrode Ed E M
333-77-7777
555-555-1020
955-555-5555
1058 Healthcare Drive
Laboratory Specimen Processor
Spinner Sam S M333-45-4545
555-555-1020
955-555-5555
1058 Healthcare Drive
D.4 Organizations
Table 7: Organizations for Storyboards
Role Name Phone Address City State ZIP
healthcare provider organization
Level Seven Healthcare, Inc.
555-555-3001
4444 Healthcare Drive
Ann Arbor MI 99999
healthcare insurer #1
HC Payor, Inc.
555-555-3002
5555 Insurers Circle
Ann Arbor MI 99999
healthcare insurer #2
Uare Insured, Inc.
555-555-3015
8888 Insurers Circle
Ann Arbor MI 99999
employer Work Is Fun, Inc.
555-555-3003
6666 Worker Loop
Ann Arbor MI 99999
Health Authority
Health Authority West
D.5 FacilitiesTable 8: Facilities for Storyboards
Role Name Phone Address City State ZIP
healthcare provider
Community Health and Hospitals
555-555-5000
1000 Enterprise Blvd
Ann Arbor MI 99999
hospital Good Health Hospital
555-555-3004
1000 Hospital Lane
Ann Arbor MI 99999
hospital unit (e.g., BMT)
GHH Inpatient Unit
555-555-3005 (ext 123)
hospital ward
GHH Patient Ward
555-555-3006 (ext 456)
hospital room
GHH Room 234
555-555-3007 (ext
789)
emergency room GHH ER
555-555-3008 (ext 246)
operating room GHH OR
555-555-3009 (ext 321)
radiology dept.
GHH Radiology
555-555-3010 (ext 654)
laboratory, in-house GHH Lab
555-555-3011 (ext 987)
pharmacy dept.
GHH Pharmacy
555-555-3012 (ext 642)
outpatient clinic
GHH Outpatient Clinic
555-555-3013 (ext 999)
urgent care center
Community Urgent Care
555-555-4001
1001 Village Avenue
Ann Arbor MI 99999
physical therapy clinic
Early Recovery Clinic
555-555-4006
1010 Village Avenue
Ann Arbor MI 99999
home health care clinic
Home Health Care Clinic
555-555-4008
1030 Village Avenue
Ann Arbor MI 99999
chiropractic clinic
Bender Clinic
555-555-4009
1040 Village Avenue
Ann Arbor MI 99999
optician See Straight 555- 1050 Village Ann MI 99999
clinic Opticians 555-4010 Avenue Arbor
pharmacy, retail
Good Neighbor Pharmacy
555-555-4002
2222 Village Avenue
Ann Arbor MI 99999
laboratory, commercial
Reliable Labs, Inc.
555-555-4003
3434 Industrial Loop
Ann Arbor MI 99999
nursing or custodial care facility
Green Acres Retirement Home
555-555-4004
4444 Nursinghome Drive
Ann Arbor MI 99999
residential treatment facility
Home Away From Home
555-555-4005
5555 Residential Lane
Ann Arbor MI 99999
satelite clinic
Lone Tree Island Satellite Clinic
555-555-5001
1001 Lone Tree Rd
Ann Arbor MI 99999
satelite clinic
Stone Mountain Satellite Clinic
555-555-5002
1000 Mountain Way
Ann Arbor MI 99999
satelite clinic
Three Rivers Satellite Clinic
555-555-5003
1000 River Drive
Ann Arbor MI 99999
satelite clinic
Bayview Satellite Clinic
555-555-5004
1000 Lakeside Drive
Ann Arbor MI 99999
E Section, Subsection and Domain Codes← AM – Administrative Management (Section)
PR – Subsection: Practice ← PA: Domain: Patient Administration ← SC: Domain: Scheduling ← PM: Domain: Personnel Management FI -- Subsection: Financial ← CR: Domain: Claims and Reimbursement ← AB: Domain: Accounting and Billing
← HM – Health and Clinical Management (Section) PO – Subsection: Operations ← BB: Domain: Bloodbank ← CG: Domain: Clinical Genomics ← LB: Domain: Laboratory ← ME: Domain: Medication ← RI: Domain: Informative Public Health ← RR: Domain: Public Health Reporting ← RT: Domain: Regulated Studies
← RX: Domain: Pharmacy ← TD: Domain: Therapeutic Devices RE – Subsection: Reasoning ← PC: Domain: Care Provision (Formerly Patient Care) RC – Subsection: Records ← MR: Domain: Medical Records
← IM – Infrastructure Management (Section) CO – Subsection: Common Message Elements (CMETs) ← CT: Domain: Common Message Elements ← MT: Domain: Shared Messages MC – Subsection: Message Control ← CI: Domain Message Control Infrastructure MF – Subsection: Master File Management ← AC: Domain: Act Classes ← EN: Domain: Entity Classes ← MI: Domain: Master File Infrastructure ← RO: Domain: Role Classes QU – Subsection: Query ← PA: Domain: Patient Administration ← QI: Domain: Query Infrastructure
F Artifact CodesTable 9: HL7 Artifact Codes
Code Artifact
AR Application Role
DM D-MIM (Domain Message Information Model)
DO Domain
EX Example
HD HMD (Hierarchical Message Descriptor)
IN Interaction
MT Message Type
NC Narrative Content
RM R-MIM (Refined Message Information Model)
ST Storyboard
SN Storyboard Narrative
TE Trigger Event
G Document CodesTable 10: Table of Document Codes
Code Document Type
BB Backbone
CF Conformance
DT Data Types
GL Glossary
IT ITS (Implementation Technology Specification)
NC Narrative Content
PB Publication/Domain Database
RI RIM (Reference Information Model)
RP Repository Database
VG Version 3 Guide
VO Vocabulary
H Realm CodesTable 11: Realm Code Table
Code Realm
CA Canadian
CT Common
UV Universal
I Publication Process and Checklist
Before you begin work, download and install the most recent version of the Publishing Tools. Note that for most publishing tools, you must remove the old version before you install the new version.
1. Convert your PubDB to the latest version. 2. Convert your Repository to the latest version.
Before sending content to HQ check the following:
1. Have you made all changes that the TC agreed to during ballot reconciliation? Review the Ballot Reconciliation spreadsheet from the previous ballot cycle if you are not sure.
2. Have you previewed the material locally? 3. Have you created all the necessary Graphics and Figures? 4. Have you set the Ballot Status in the PubDB correctly?
1. Does it match what was in the Ballot Announcement? 2. Do the Ballot status icons in the document reflect the current status of
the document?
3. Does the textual description of the document status that appears on the Preface or Overview section reflect the current status of the document?
To submit your content, zip up the following:
← Your PubDB ← Your Repository ← Visio files for all of your DMIMs and RMIMs ← Visios or GIFs of all other graphics ← Any other supporting documents
Send the zip to HQ (either [email protected] or [email protected]).
Note that some corporate email systems will restrict the size of attachments. You may try to submit your content in smaller pieces (i.e., part 1 of 5, etc). If your email system will not allow you to send your content to HL7 HQ, contact us for alternative means.
J Adding Annexes to Topics in a Domain
An annex may defined for any topic (except another annex). When defined, an annex consists solely of contents of its textual "introduction." This may be either simple marked up text, or it may contain div tags. (See later discussion of content.)
J.1 Identification
An annex is simple another entry in the list of entries on the "Sort" tab. However, its base class name designates it as an annex to another topic. This is done by simply adding "Annex " to the front of the base class name for the topic to which you wish to add an annex. The following graphic shows the definition of two annexes.
The second row defines an annex named "Implementation Guide" for the "Care Transfer" topic, using a base class name of "Annex Care Transfer." Similarly, the fourth row defines an annex named "Patient Care Relationships" for the "Care Structures" topic.
J.2 Using <div/> tags to structure an Annex
As mentioned above, the content of an Annex may contain <div/> tags to provide additional structured with numbered sub-division. Use of <div/> tags is discussed in detail in the section on creating prefaces, above. For a simple example, div tags were added to the content of an annex using Spy. The Spy authentic window looked like:
The XML mark-up for the same definition looks like:
Finally, when this is published, it looks like the following:
K Managing Components K.1 Managing a large number of GIF files
A method employed by the Care Provision TC, who has have a large number of graphics in their narrative text, is the a spreadsheet with the formal, publication database name of the .GIF file, the last editor and a description of the graphic. A repository of .GIFs with the contents of the …Pubdb/Localpub/outputgraphics file is then maintained from ballot-to-ballot for future use and reference. An illustration of the .GIF reference spreadsheet follows:
K.2 Managing a large amount of storyboard content over many topics
A method employed by the Care Provision TC to manage a large number of storyboards, and their associated interaction and activity diagrams over several topics is the use of a "Storyboard Map." This allows coordination of the content between many committee members, in addition to promoting communication.
The base class sort numbering from the Publication database is used to namespace the topic artifacts. The topics are arranged into groups of two columns each, the first is for the storyboard narrative title and the associated interaction diagram. The second column is for the activity diagrams, which must be added manually in the XML code. Members of a TC that are working on content can color code cells in the spreadsheet when making updates, or comments. The following is an example of a Storyboard Map used by the Care provision TC.
Link to wide graphic (opens in a new window)Hide Revision Marks Return to top of page