HL7 Publishing Facilitator's Guide

HL7 Version 3 Publishing Facilitator's Guide

HL7 Version 3 Publishing Facilitator's Guide

DRAFT: February 28June 1, 2005

Preface:

The Publishing Facilitator's Guide is intended to assist the Publishing Facilitator in creating and maintaining correct and consistent HL7 Version 3 Standards.

Editing Notes (to be deleted when non-Draft):

Pink indicates where hyperlinks will be inserted

Yellow indicates outstanding questions or content to be written still.

Revision History:

Date / Editor / Comment
2/28/05 / Pete Gilbert / First Draft
2/28/05 / Lloyd McKenzie / Comments and additions
3/23/05 / Dick Harding / Comments and additions
4/20/05 / Helen Stevens / Comments and additions
4/22/05 / Pete Gilbert / Additions

Table of Contents

1.Introduction and Scope

1.1Roles and Responsibilities

1.1.1Publishing Committee Leadership

1.1.2Publishing Facilitators

1.1.3Technical Publications Manager

1.2Publishing Schedule

2.Publishing Tools

2.1Installation

2.2Narrative Guidelines

2.3HTML Markup

2.4Artifact Identification

2.4.1Structured Sort Name

2.4.2Artifact Codes

2.5Graphics

3.Content Domains

3.1Introduction

3.1.1General Principles

3.1.2Publication Section Indexes

3.2Preface & Table of Contents Section

3.3Overview Section

3.4Domain Message Information Models

3.5Storyboards

3.6Application Roles

3.7Trigger Events

3.8Refined Message Information Models

3.9Hierarchical Message Descriptions and Message Types

3.10Interactions

4.Common Domains

4.1Common Message Element Types

4.2Shared Messages

4.3Clinical Statement Pattern

4.4Messaging Infrastructure

4.4.1Wrappers

5.Supporting Documents

5.1Foundation Documents

5.1.1Reference Information Model

5.1.2Data Types: Abstract

5.1.3Vocabulary

5.1.4Refinement and Localization

5.1.5GELLO: Common Expression Language

5.2Background Documents

5.2.1Version 3 Guide

5.2.2Glossary

5.2.3Methodology (HDF)

6.Appendix X: Templates and Building Blocks

6.1.1Graphical Templates

6.1.2Content Templates

7.Appendix X: Storyboard Names

7.1.1Patients

7.1.2Healthcare Staff

7.1.3Locations

8.Appendix X: Section, Subsection and Domain Codes

8.1.1Artifact Codes

8.1.2Document Codes

8.1.3Realm Codes

9.Appendix X: Publication Process and Checklist

1.Introduction and Scope...... 4

1.1Roles and Responsibilities...... 4

1.1.1Publishing Committee Leadership...... 4

1.1.2Publishing Facilitators...... 4

1.1.3Technical Publications Manager...... 5

1.2Publishing Schedule...... 6

2.Publishing Tools...... 9

2.1Installation...... 9

2.2Narrative Guidelines...... 10

2.3HTML Markup...... 11

2.4Artifact Identification...... 11

2.4.1Structured Sort Name...... 11

2.4.2Artifact Codes...... 12

2.5Graphics...... 12

3.Content Domains...... 14

3.1Introduction...... 14

3.1.1General Principles...... 15

3.1.2Publication Section Indexes...... 15

3.2Preview & Table of Contents Section...... 16

3.3Overview Section...... 17

3.4Domain Message Information Models...... 17

3.5Storyboards...... 19

3.6Application Roles...... 21

3.7Trigger Events...... 21

3.8Refined Message Information Models...... 22

3.9Hierarchical Message Descriptions and Message Types...... 23

3.10Interactions...... 23

4.Common Domains...... 28

4.1Common Message Element Types...... 28

4.2Shared Messages...... 28

4.3Clinical Statement Pattern...... 29

4.4Messaging Infrastructure...... 29

4.4.1Wrappers...... 30

5.Supporting Documents...... 31

5.1Foundation Documents...... 31

5.1.1Reference Information Model...... 31

5.1.2Data Types: Abstract...... 31

5.1.3Vocabulary...... 32

5.1.4Refinement and Localization...... 32

5.1.5GELLO: Common Expression Language...... 32

5.2Background Documents...... 32

5.2.1Version 3 Guide...... 32

5.2.2Glossary...... 33

5.2.3Methodology (HDF)...... 33

6.Appendix X: Templates and Building Blocks...... 35

6.1.1Graphical Templates...... 35

6.1.2Content Templates...... 35

7.Appendix X: Storyboard Names...... 36

7.1.1Patients...... 36

7.1.2Healthcare Staff...... 36

7.1.3Locations...... 37

8.Appendix X: Section, Subsection and Domain Codes...... 38

8.1.1Artifact Codes...... 39

8.1.2Document Codes...... 39

8.1.3Realm Codes...... 39

3.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 developed the HL7 Development Framework to guide the technical development the standards and 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 consistent, easy to use format appropriate for a variety of audiences. Publishing HL7 Version 3 Standards is a demanding task. Not only do you have to get the technical content right, but you have to understand how to use a plethora of tools to create the content. You will also be confronted by a dizzying array of concepts, terms and abbreviations. And, as a volunteer, you will do all of this in addition to your real job.

This document will give youpresents 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 give you provide the information that you needed to create a consistent and valid Version 3 Standard that conforms to the M&M methodology and uses the appropriate tooling.

3.11.1Roles and Responsibilities

1.1.1Publishing Committee Leadership

The Publishing Committee is an HL7 board committee and as such the leadership of the committee is appointed by the chair of the HL7 Board. 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 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.

3.21.1.2What is a 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.

All HL7 groups (Technical Committee (TC), Special Interest Group (SIG), 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 is "Editor" was determined to be inadequate as it did not represent the full range of activities and responsibilities expected of this role. However, the HL7 Version 3 Editors do much more than traditional document editors and we; consequently the Publishing Committee felt that creating another term would encompass these expanded responsibilities.

The role of athe 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.

A Publishing Facilitator usually works with a Technical Committee (TC), Special Interest Group (SIG) or Project to create and edit the content of the V3 standard which is relevant to that group.

The Publishing Facilitator is responsible for coordinating the creation and editing of the content of a Version 3 Standard with the appropriate Technical Committees (TCs) and Special Interest Groups (SIGs)

AThe Publishing Facilitator works with the appropriate Committee Chairs to ensure that a properly completed Ballot Request for Information Form is submitted to HL7 HQ by the deadline specified. This is required to have your document included in a Ballot Cycle.

AThe Publishing Facilitator submits the Version 3 document components (PubDB, Visio Diagrams, etc) to HL7 HQ so that it can be included in a Ballot Cycle.

1.1.3[RH1]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 and taking minutes
• 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.

Ballot Preparation

4.11.2Publishing Schedule

The HL7 content developed must undergo balloting prior to approval as HL7 standards. Three times each year, HL7 Standards are voted on (balloted). The process of publishing the documents and voting on them is known as a Ballot Cycle and the Publishing Committee has scheduled a ballot cycle prior to each Working Group Meeting (WGM). The results of a Ballot Cycle are discussed at the next Working Group Meeting (WGM) which follows the Ballot Cycle; consequently . Tthe ballot cycle is named for the year and month of that thewhen the nextWorking Group MeetingWGM occurs is held. For example, the 2005September Ballot Cycle opens on August 1 and closes on September 3, and the WGM runs from September 11-16. [RH2]

The Publishing Schedule is defined by the Publishing Committee each year and then presented to the Technical Steering Committee (TSC) at the January 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 . Look under Events, or at the Publishing Committee's webpage.

The Publishing Schedule outlines target dates of the Publishing Process which you must meet in order to Publish and Ballot your document. Take a look at the Publishing Schedule now. Let's review the process, some of the dates and how they affect youAlthough there is a ballot cycle prior to every WGM 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 Announcement

A Ballot Announcementmust go outbe published 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. If you want to Publish and Ballot a document, you must be part of that announcement.

HL7 HQ will send several reminder emails out before the Ballot Announcement.

If you are not in the Ballot Announcement, your document cannot go to ballot.

This is an ANSI and HL7 requirement.

It is the responsibility of the Publishing Facilitator to ensure that the TC The co-chairs of the responsible TC or SIG must return a completed Ballot Request for Information Form xxx to the HL7 HQTechnical Publishing Manager in order to be included in a Ballot Cycle. The Publishing Facilitator must coordinate this with the appropriate co-chairs.

• Ballot Preview & Testing Period

The Ballot Preview and Testing periodis a two week period window prior to the ballot cycle opening that providesis your an opportunity to look at your documentsthe content on the Ballot Preview Site before the Ballot Cycle officially opens.

In order for this to work, you need to have your content complete and delivered to HL7 HQ for processing.

During the Ballot Preview Period, the Publishing Facilitator, and other TC members, shouldyou will want to review the content your document 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).

It is much easier to fix problems before the Ballot Cycle oOpens, so encourage the members of your SIG, TC or Project to review the document at this point in the Ballot Cycle.

• Content Deadline

The Content Deadline is set the Sunday 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.

Any content not received by Wednesday before ballot opens will automatically 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 Open

The Ballot Cycle Open and Close dates are the bookends to the Ballot Cycle. During the time between the Open and Close dates, we refer to the Ballot Cycle is referred to as being Open. This means that people HL7 members (and paying non-members) will be reviewing and voting upon your document.the content.

There is always 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 TCyou discuss the votes and comments received during the ballot cycle on its content your document at the Working Group Meeting.

See Refer to the HL7 Ballot System documentation for more information on Balloting.[RH3]

2.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 Publshing tools and technologies before it can be published and balloted.

2.1Installation

All HL7 Version 3 Publishing Tools may be downloaded from:

Version 3 Domain Documentation Tools
Pub DB V 204
Installer of 204 --
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 Widget
Installer --
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 DescriptionEditor
DescEditor 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.
Version 3 Static Model Design & Documentation Tools
RMIM Designer Version 3.01
HL7_RmimDesign Installer.msi
July 15, 2004 release
CMETinfo.txt
in ZIP
Formal Naming
22s
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 2.08,
Voc 273
Naming 22
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 3.0.3
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 – r1.0
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.