Chapter 1: HL7 V2.5 Style Guide
1.HL7 V2.5 Style Guide
Co-Chair: / Helen StevensMcKesson HBOC
Co-Chair: / Klaus D. Veil
HL7S&S
Editor: / Frank Oemig
KIS Laufenberg GmbH & Co. KG
1.1Style Guide Contents
1.1 Style Guide Contents......
1.2 Purpose......
1.3 General Rules......
1.3.1 Exceptions......
1.3.2 General Specifications and Settings......
1.3.3 Heading Capitalization......
1.3.4 Enabling Macros......
1.4 Document Structure......
1.4.1 Introductory Page
1.4.2 Table of Contents......
1.4.3 Statement of Purpose......
1.4.4 Notes to Balloters......
1.4.5 Preparing documents for publishing......
1.4.6 Event/Message and Segment Definition......
1.4.7 Field Definitions......
1.5 Document properties......
1.6 Formatting......
1.6.1 Text Indentation......
1.6.2 Message Definitions......
1.6.3 Segment Definitions......
1.6.4 Field Definitions......
1.6.5 Components......
1.6.6 Components (Data type)......
1.6.7 Component Definitions......
1.6.8 Table Definitions......
1.6.9 Table Value Definitions......
1.6.10 References to Data Elements......
1.6.11 References to HL7 Tables......
1.6.12 References to User Tables......
1.6.13 Notes......
1.6.14 Examples......
1.6.15 Page Headers......
1.6.16 Page Footers......
1.6.17 Setting Bookmarks......
1.7 Lists......
1.8 Indexing......
1.8.1 Data Types......
1.8.2 Data Elements......
1.8.3 Segments......
1.8.4 Attribute Tables......
1.8.5 Events......
1.8.6 Tables......
1.8.7 Message Types......
1.9 Conformance Statements......
1.9.1 Distinct Parts of a Conformance Statement......
1.9.2 Formatting the different parts of a conformance statement with styles......
1.10 Other EDITING TASKS and Issues......
2.1 Authorized Paragraph Styles for the HL7-2 Template......
2.1.1 Style Name Notes......
2.1.2 Font......
2.1.3 Kern......
2.1.4 Line Spacing......
2.1.5 Space Before......
2.1.6 Space After......
2.1.7 Justification......
2.1.8 Other......
2.1.9 Indent......
2.1.10 Tabs......
2.1.11 Base Style......
2.1.12 Style for Following Paragraph......
2.2 Authorized Character Styles for the HL7-2 Template......
2.3 Withdrawn Styles for the HL7-2 Template......
2.4 List of new styles for the Conformance Statement......
2.5 List of column widths for all tables......
2.6 REMARKS......
2.7 A NOTE ON HTML STYLE SHEETS......
2.8 Formatting Macros (Style Fixer)......
2.8.1 Enabling Macros......
2.8.2 General Remarks......
2.8.3 Adjust the properties of the styles......
2.8.4 Format all Tables within the document......
2.8.5 References......
2.8.6 Adjust the numbering of the headings......
2.8.7 Adjust the Number Gallery......
2.8.8 Delete unused styles......
2.8.9 Convert message tables into 5 column format......
2.8.10 Add 3rd column to tables......
2.8.11 Reformat Message table......
go to Table What table is this......
2.8.13 Goto a specific table......
2.8.14 Get All Formats......
2.8.15 Requirements to run the macros......
2.8.16 Manually Correcting Styles......
2.8.17 Questions/Errors......
2.8.18 History (last changes at the end)......
2.9 Procedures......
2.9.1 Procedure for Troubleshooting Normal List Alpha......
2.9.2 Troubleshooting styles that change erratically......
2.9.3 Procedure for inserting a picture......
2.9.4 Troubleshooting the macro Format All Tables......
1.2Purpose
This document describes how HL7 Version 2.5 Chapters should be formatted in order to get a uniform layout, which in turn allows automatic generation of the HL7 V2.5 Database. For the automatic scanning and data extraction processing it is important to maintain consistency across all HL7 chapters.
To demonstrate the styles this document uses the same formatting rules.
All formatting is set by MS Word “styles”. (The use of a MS Word .DOT template file was found to be too unreliable). A set of macros is available (see the end of this document) to apply the styles to the document.
1.3General Rules
To reduce the amount of formatting effort and to allow easy processing of HL7 Chapters no direct formatting should be applied. All necessary formatting shall be done by the help of MS Word “styles”.
1.3.1Exceptions
Only a few exceptions are accepted. One is the numbering of the chapter. Others are identified later.
1.3.2General Specifications and Settings
This HL7 Style Guide is for HL7 V2.5 documents.
This Style Guide assumes the use of MS Word 97 SR-2 or a later version of MS word (Office 2000, etc.).
Some settings are standard:
- The language is American English
- Hyphenation is enabled.
- Paper orientation is portrait
- “Fast saves” are disabled (keeps the documents to a minimum size)
- “Templates and Add-Ins automatic updates” is disabled.
1.3.2.0
1.3.2.1Page Setup
Top margin: 0.4" (1,016 cm)
Bottom margin: 0.5" (1.27 cm)
Left margin: 0.75" (1.905 cm)
Right margin: 0.75" (1.905 cm)
Gutter (for binding): 0.5" (1.27 cm)
Header: 0.6” (1.524 cm)
Footer: 0.6” (1.524 cm)
1.3.2.2Filename Conventions
The naming convention for the files is:
Ch<99>.doc / for the chapters including a two digit chapter numberAppendix<X>.doc / for the appendices including a one character appendix number
This convention is necessary to achieve hyperlinking across the different chapters.
1.3.3Heading Capitalization
Capitalize the first and last words and all others except articles, prepositions, the to in infinitives and coordinate conjunctions (such as “and”, “but”, “or” and “yet2).
The same should be applied to data elements and segment names.
1.3.4Enabling Macros
Regarding disabled macros. Word 97 (I don't know about later versions) will (is suppose to ask) if you want to enable/disable macros when you open a document that contains macros. The prompt can be turned on/off by checking/unchecking Macro Virus Protection in the General tab of Tools:Options. But, it you are not getting the prompt, the macros are suppose to be enabled.
You can get to the macros directly (not using the buttons) by going to Tools:Macro:Macros or pressing Alt+F8. The window will list the available macros. If the window is empty, then the macros have been disabled via Word's virus protection: Enable Macro Virus Protection (check it) in Tools:Options:General, then close and re-openthe document and click Enable on the dialog. If the dialog still doesn't show up then get a "fresh" copy of the style guide either re-extract it from the zip or download the zip again. (On the copy that I use I don't get the macro disable dialog, but I do get the dialog when I open a new copy out of the zip file.)
1.4Document Structure
1.4.1Introductory Page
Every chapter begins with an introductory page which names the number of the chapter, the name of the chapter and the responsible chairs and editors.
1.4.2Table of Contents
A Table of Contents appears after the introductory information.
The TOC lists the chapter contents at the Heading 2 and Heading 3 levels.
The TOC is constructed as follows:
1)Select and delete the current TOC.
2)From the Insert menu, select Index and Tables
3)Select the Table of Contents menu.
4)Select “From Template” as the format
5)Show Page Number should be checked
6)Right Align Page Number should be checked
7)Show levels should be set to (WHAT)
8)Tab Leader should be set to “dots”
9)Select the Options menu
10)Etc
Heading 2
3.2 CHAPTER xx CONTENTS
{ VERZEICHNIS \T "Heading 2,1,Heading 3,2,Heading 4,3" }
Another important issue is to move the level down, i.e. make “Heading 2” “TOC 1”.
1.4.3Statement of Purpose
Except for chapter 2, the first paragraph specifies the purpose of the chapter. The formatting is as follows:
Heading 1 (consists of a soft end of line [SHIIFT+RETURN] and the heading, but is auto-numbered and sets the number "base" for the whole chapter)
3.
Patient Administration
Ernest & Young
Chapter Chair: / Michael Hawver
Eclipsys Corporation
Editor: / Klaus D. Veil
HL7S&S
3.2 PURPOSEHeading 2
The black horizontal line is built up by a graphical box across the page with 5 mm in height. The list of chairs and the editors is a table with no borderlines. This allows for easy alignment.
To set the "base" numbering for a chapter, set the number a *one* place in each chapter, namely in the actual chapter number ("3.") with the style of "Heading 1". Go to Format->Bullets and Numbering->Customize->Start at.
Heading 3
1.4.4Notes to Balloters
Preparing a document for balloting often requires some additional information which should be taken care of when reading the document. This initial section appears directly below the list of co-chairs and editors, but before the table of contents. This ensures that everybody is aware of this additional information.
Notes to Balloters
- This is the Member Ballot for V2.x.
- Please ballot on chapter content only. The formatting of the chapters is mainly driven by the requirement to automatically extract data for automatic consistency checking and to build the HL7 V2.4 Database. The format has been reviewed by the HL7 Architectural Review Board. As HL7 also intends to publish the Standard in PDF and HTML/XML format, variations in presentation may not be avoidable. For this reason, not all style enhancements have change marks.
- HL7 HQ, the TC Chairs and the International Affiliates thank you for your consideration!
This section is makes use of the available styles.
Afterwards the whole section (without a section heading) is shaded in grey 15% and border lines are 1½ points.
1.4.5Preparing documents for publishing
a)Run Macros
b)Clear number gallery (seep rocedure in section 1.7.1)
c)Correct typos
d)Make technical corrections approved by ARB that do not need to be balloted
e)Make any sections moves that do not involve content change
f)Make any other styleguide changes that do not involve content change
g)Set place holders for new sections
h)Check and correct bookmarks
i)Check that Header is correct
j)Check that the Footer indicates the proper ballot name or final name and the date
k)Turn Tracking (Checkmarking) on
l)Make content changes as needed
1.4.6Event/Message and Segment Definition
The structure of the HL7 chapters consists of two parts. The first lists events, triggers and messages with the relevant message structures; the second part defines the segments, elements, components and subcomponents in detail.
1.4.7Field Definitions
The field definitions for a segment have to be appended to the segment definition. It starts with the level 4 heading naming the segment after which the fields/elements are defined. No text is necessary.
Heading 4
1.4.7.0PID-1 Set ID PID (SI) 00104
All field definitions start with a level 4 heading consisting of four parts:
1)The data element identifier
2)the name of the data element
3)the type of the data element (in brackets)
4)the data element ID number
The four heading parts are separated by three spaces each.
The field definition header also contains an invisible entry for index generation. Look at the “Set ID – PID” heading above with Tools -> Options -> View -> All checked on.
1.5Document properties
Title:The contents of this document, i.e. the name of the chapter
Topic:“HL7” and the corresponding version number
Author:The name of the editors.
1.6Formatting
1.6.1Text Indentation
Text following headings level 1 and 2 are flush left with no indentation; the MS Word style is “Normal”.
Text following level 3 headings and lower is formatted using "Normal Indented", indented 1/4" (0.63cm).
1.6.2Message Definitions
Message definitions are in form of a table to simplify the document data extraction This table consists of three columns and as many rows as necessary.
The first row (“Msg Table Header”) describes:
- in the first column the message type, the event/trigger code and the message structure ID separated by "^",
- in the second column a short description
- in the third column the group name to identify logical groups of segments
- in the fourth column a status concerning backward compatibility
- in the fifth column the corresponding HL7 chapter.
All subsequent rows are used for the message description (“Msg Table Body”). The segments used and structure symbols are listed in the left column. The middle column holds the segment name.
If this message applies to more than one event, all event codes are listed within the second field of the first column in the first row. Ranges are separated by dashes (“-“) and single values by commas.
The message definition tables are indented by 1/4" (0.63cm).
Msg Table HeaderHyperlink to “EVN”Msg Table Body
ADT^A01^ADT_A01 / ADT Message / Group Name / Status / ChapterMSH / Message Header / 2
EVN / Event Type / 3
PID / Patient Identification / 3
[PD1] / Additional Demographics / 3
[ { NK1 } ] / Next of Kin /Associated Parties / 3
PV1 / Patient Visit / 3
[ PV2 ] / Patient Visit - Additional Info. / 3
[ { DB1 } ] / Disability Information / 3
[ { OBX } ] / Observation/Result / 7
[ { AL1 } ] / Allergy Information / 3
[ { DG1 } ] / Diagnosis Information / 6
[ DRG ] / Diagnosis Related Group / 6
[ / PROCEDURE
{
PR1 / Procedures / 6
[{ROL}] / Role / 12
}
]
[ { GT1 } ] / Guarantor / 6
[ / INSURANCE
{
IN1 / Insurance / 6
[ IN2 ] / Insurance Additional Info. / 6
[ {IN3} ] / Insurance Additional Info. - Cert. / 6
}
]
Columns 1 and 2 are left justified – and columns 3 to 5 are centered.
It is required that all segments in the message structure that are defined in the same chapter have a hyperlink to the segment attribute table.
Whenever brackets are used for one segment only they should appear within the same cell. Otherwise separate rows should be used.
Indentation can use tabs or spaces. The latter are preferred. If possible the closing brackets should appear below the corresponding opening bracket.
1.6.3Segment Definitions
Attribute headers start on a new page. The attribute tables, i.e. the list of data elements used, are indented 1/4" (0.63cm) and should be formatted as follows:
Attribute Table Caption
Attribute Table Header
Attribute Table BodyBookmark (“EVN”)Index information
Hyperlink to “ID”
HL7 Attribute Table – EVN – Events {XE “HL7 Attribute Table: EVN” }{XE “EVN attributes”}
SEQ / LEN / DT / OPT / RP/# / TBL# / ITEM# / ELEMENT NAME1 / 3 / ID / B / 0003 / 00099 / Event Type Code
2 / 26 / TS / R / 00100 / Recorded Date/Time
3 / 26 / TS / O / 00101 / Date/Time Planned Event
4 / 3 / IS / O / 0062 / 00102 / Event Reason Code
5 / 60 / XCN / O / Y / 0188 / 00103 / Operator ID
6 / 26 / TS / O / 01278 / Event Occurred
The attribute table caption line information is used to generate the index of HL7 attribute tables. Therefore the complete caption is repeated in the index field. To facilitate the generation of the database the index field must be positioned at the end of the line!
The attribute table caption line must be bookmarked with the 3-letter segment ID (i.e. "EVN") for referencing by the message structure tables.
The header is shaded 10%.
The attribute table grid lines are ¾ points, and the border is a dual ¾ point line.
Additional index information is added at the end of the paragraph. This kind of information is hidden and therefore only visible when switching on “all” in Extras->Options->non-printable characters. (The information above is formatted as normal text so it appears in the printed version of this document.)
1.6.4Field Definitions
Style “Heading 4” 1.5.10.0 starts with zero to ensure that “field definitions” after a HL7 Attribute Table are automatically renumbered. Where a zero-numbered heading is not desired, hide it with Format -> Font -> Hidden.
The Field Definition heading now consists of 5 components:
- Section heading number: 3.3.2.3 (automatically generated by Word)
- Element name: PID-3
- Element description: Patient Identifier List (Use Title Case)
- Element data type: (CX)
- Unique data element identifier: 00106
The 5 heading components are separated by 3 spaces each. The complete heading looks as follows:
3.3.2.3 PID-3 Patient Identifier List (CX) 00106
1.6.5Components
Whenever a data element consists of components, they are defined first within the description. This definition is done in a paragraph like form. This definition also applies for subcomponents.
Components: <identifier (ST)> ^ <text (ST)> ^ <name of coding system (ST)> ^ <alternate identifier (ST)> ^ <alternate text (ST)> ^ <name of alternate coding system (ST)>
Components
The component definition, i.e. the list of components, is not repeated within each field definition since this functionality can be reached by hyperlinking! This change reduces drastically the amount of pages necessary for printing.
1.6.6Components (Data type)
The components which make up a data type are specified in form of a table like segments or real tables.
Component Table Caption
Component Table Header
Component Table BodyBookmark (“CE”)Index information
Hyperlink to “ST”
HL7 Component Table - CE – coded element{XE “HL7 Component Table - CE ” }
SEQ / LEN / DT / OPT / TBL# / COMPONENT NAME / COMMENTS / SEC.REF.1 / ST / R / Identifier
2 / ST / O / Text
3 / IS / R / 0396 / Name Of Coding System
4 / ST / O / Alternate Identifier
5 / ST / O / Alternate Text
6 / IS / O / 0396 / Name Of Alternate Coding System
Length: 250
Example:
|F-11380^CREATININE^I9^2148-5^CREATININE^LN|
The header is shaded 10%.
Columns 6 and 7 are left justified.
The attribute table grid lines are ¾ points, and the border is a dual ¾ point line.
Within the comments column there is no hint whether this component is itself a complex data type. The user can find out by checking the underlying data type. Within the narrative a hint (note) can be found to give an indication the data type which embeds the current one. But this should only apply to sparsely use data types.
See Bookmark procedure for setting a Bookmark in the caption.
1.6.7Component Definitions
Style “Heading 4” 1.5.10.0 starts with zero to ensure that “component definitions” after a HL7 Component Table are automatically renumbered. Where a zero-numbered heading is not desired, hide it with Format -> Font -> Hidden.
The Component Definition heading now consists of 4 components:
- Section heading number: 3.3.2.3 (automatically generated by Word)
- Component name: CE.1
- Component description: Identifier (Use Title Case)
- Component data type: (ST)
The 4 heading components are separated by 3 spaces each. The complete heading looks as follows:
3.3.2.3 CE.1 Identifier (ST)
1.6.8Table Definitions
Whenever a table is referenced within a field description the first time (according to the sequence of chapters) the corresponding values have to be defined in form of a table. If no values can be identified this table should contain one entry saying “no suggested values”.
1.6.8.0
1.6.8.1General rules
- Tables with double borders are normative, tables with single borders are user-defined.
- Each table consists of a caption, a header and a body.
- The header part is shaded.
- Table structures are to be inserted in the standard, even if values have not been determined.
1.6.8.2HL7 Tables
HL7 Table Caption
HL7 Table Header
HL7 Table BodyBookmark (“HL70103”) Index information
HL7 Table 0103 – Processing ID{XE “HL7 Table: 0103 - Processing ID ” }
Value / Description01 / Patient request
02 / Physician order
03 / Census management
Note the index field in the HL7 table caption above.