5/28/20021Copyright 2002, HL7 Ballot 3 Style Guide Developed by: Helen Stevens ([email protected])[email protected] Woody Beeler([email protected])[email protected].

5/28/2002 1Copyright 2002, HL7

Ballot 3 Style Guide

Developed by:

Helen Stevens ([email protected])

Woody Beeler([email protected])

This presentation is a cheat sheet for those preparing HL7 3.x content for publication. Refer to available documentation and

tutorials for detailed information.

Please email questions/corrections to Helen

Table of contents Schedule

Naming Identifier structure Structured names for publication sorting Artifact development axes

Best practices Narrative content & HTML markup Storyboard purpose and narrative Application roles – Groups, “hidden” roles, naming Trigger events Interactions – naming and preferred patterns

State Transition Notification Pattern State Transition Request Pattern Query Pattern

RMIM & DMIM Models Naming and Clone names Loosely/tightly coupled CMETS Compound domain constraints

Schedule (Summer 2002)

WGM

WGM

HL7 Board

3x Preview/Harm

3x Ballot Close

3x Preview Close

3x Ballot Open

5 week ballot period

HL7 3.0

Intl Meeting3x Content Deadline

Content Generation Tools Available

Foundation DocumentsContent Deadline

Draft PubDb Submissions to verify progress

ToC

Schedule (Fall 2002)Assuming earliest possible ballot cycle avoiding Christmas.

2x Ballot Close

2x Ballot Open

5 week ballot period

WGM

WGM

Content Deadline

HL7 2.5

ToC

Tool Development Schedule (Summer 2002)

Tool changes required by Domains for creation of the 3.x Ballot 3

Tool changes required by Publications to create the HTML ballot preview

Tool changes required by Publicationsto create the final Ballot 3

Tool changes required by Domains for Ballot 2 reconciliation and creation of Ballot 4

4/28 5/24 Tooling phase 0 (3 wks)5/25 6/20 Tooling phase 1 (5 wks)6/20 6/28 Content verification 6/28 7/14 Preview production HTML7/15 7/29 QA7/15 7/29 Tooling phase 2 (2 wks)7/30 8/11 Ballot production8/12 9/22 Tooling phase 3 (5 wks)

Tooling Phase 1

Tooling Phase 2

Tooling Phase 3

Tooling Phase 0

ToC

Section, Sub-Section & Domain Codes

Applicable to all sub-sections

XX Non Domain Specific

AM Section: Administrative Management

PR Sub-Section: Practice

PA Patient Administration PA

SC Scheduling SC

PM Personnel Management PM

FI Sub-Section: Financial

CR Claims & Reimbursement FM

AB Accounting & Billing FM

HM Section: Health & Clinical Management

PO Sub-Section: Operations

LB Laboratory OO

RX Pharmacy OO

RE Sub-Section: Reasoning

PC Patient Care PC

RC Sub-Section: Records

MR Medical Records MR

IM Section: Infrastructure Management

MC Sub-Section: Message Control

CI Message Control Infrastructure CQ

MF Sub-Section: Master File Management

MI Master File Infrastructure CQ

AC Act Classes CQ

EN Entity Classes CQ

RO Role Classes CQ

QU Sub-Section: Query

QI Query Infrastructure CQ

PA Patient Administration PA

CO Sub-Section: Common Message Elements

CT Common Message Elements CQ

XX Non Domain Specific CQ

Responsible Committee

Sub-Section Identifier

Domain Identifier

Section Identifier

ToC

Artifact & Document CodesCode ArtifactAR Application RoleDM D-MIM (Domain Information Model)DO DomainEX Example HD HMD (Hierarchial Message Descriptor)IN Interaction MT Message TypeNC Narrative ContentRM R-MIM (Refined Information Model)ST StoryboardSN Storyboard NarrativeTE Trigger Event

Code ArtifactAR Application RoleDM D-MIM (Domain Information Model)DO DomainEX Example HD HMD (Hierarchial Message Descriptor)IN Interaction MT Message TypeNC Narrative ContentRM R-MIM (Refined Information Model)ST StoryboardSN Storyboard NarrativeTE Trigger Event

Code DocumentBB BackboneCF ConformanceDT Data TypesGL GlossaryIT ITSNC Narrative ContentPB Publication/Domain DatabaseRI RIMRP Repository DatabaseVG V3 GuideVO Vocabulary

Code DocumentBB BackboneCF ConformanceDT Data TypesGL GlossaryIT ITSNC Narrative ContentPB Publication/Domain DatabaseRI RIMRP Repository DatabaseVG V3 GuideVO Vocabulary

Code RealmCT CommonUV Universal

Code RealmCT CommonUV Universal

ToC

Artifact Naming

All artifacts delivered for V3 must be named using the following convention:

UUDD_AAnnnnnRRvvUU = 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_AR000001UV01

Practices & Operations Sub-Section, Pharmacy Domain, Application Role Artifact number 00001, Universal Realm, Version 01.

ToC

TC Submissions Summary

Repository Database UUDD_RPnnnnnnRRvv.mdb DMIM Diagram(s) UUDD_DMnnnnnnRRvv.vsd (one diagram per file)

RMIM Diagram(s) UUDD_RMnnnnnnRRvv.vsd (one diagram per file)

Storyboard Diagram(s) UUDD_STnnnnnnRRvv.vsd (one diagram per file)

Publication Database UUDD_PBnnnnnnRRvv.mdb

Narrative Documents UUDD_NAnnnnnnRRvv.xml

Example Files UUDD_HDnnnnnnRRvv_nn.xml

UUDD_MTnnnnnnRRvv_nn.xml Example identifiers should match the HMD (HD) or Message Type (MT) to which they apply. If multiple examples have been created for a single MT or HMD add _nn to the end of the name where nn is a number. (one example per file)

Submit Files to http: //www.hl7.org/v3 If an update to a file must be submitted, then it should be named exactly the

same as the original file. HQ will automatically add a timestamp to received files and keep all historical files.

ToC

All artifacts will sort in the Publication using the ‘Structured Sort Name’

Some artifacts also support a ‘Title Name’ this will appear as the artifact title, but will not be used for sorting.

Publication Sorting – structured names

Artifact Title Name Structured Name Algorithm Specified by M&M

Storyboard (ST) Yes Yes No

ST Narrative (SN) Yes Yes No

Application Role (AR) Yes Yes Yes

Trigger Event (TE) Yes Yes Yes

R-MIM (RM) No Yes Yes

D-MIM (DM) No Yes Yes

HMD (HD) No Yes Yes

Message Type (MT) No Yes Yes

Interaction (IN) No Yes Yes

ToC

Publication Sorting M&M Algorithm

The Algorithm for each artifact type differs

Algorithm is based on variables:Base ClassMoodActionStereotypeState TransitionCapability

Each is explained on the following slides:

Exception to the formulas: Cannot ‘request’ completionCannot request fulfillment of events

ToC

Artifact Development Axes

[Base Class] Defined by the Domain to describe the focal class of the artifact. Documented in PubDb in the ‘Base Class’ screen

Recommend not including Domain name in the Base Class E.g. Combined, Supply, Patient Encounter, etc.

[Mood] Defined by M&M Valid values include: Proposal, Order, Intent (Promise), Event

[Action] Defined by M&M Valid values include: Notification, Fulfillment Request, Confirmation,

Rejection

[Stereotype] Defined by M&M Valid values include: Placer, Fulfiller, Confirmer, Confirmation Receiver,

Informer, Tracker

ToC

Artifact Development Axes (cont’d)

[State Transition]Defined from the State Transition DiagramValid values include: New, Hold, Release, Cancel, Activate,

Suspend, Resume, Abort, Complete, Reactivate, Nullify, Revise, Replace

normal

held

cancelled

suspended

completed

aborted

activenew

null

held

cancelled

suspended

nullified obsolete

revise

revise

completed

revise

aborted

active

reactivate

revise

new

create completeactivate

release

hold

cancel

activate

suspend

complete

abort

nullify obsolete

resume

end

abort

ToC

Artifact Development Axes (cont’d)

[Capability] Describes the functions that the application is capable of performing. Valid values include the following values: Existence, Revision,

Replacement, Nullification, Completion, Abortion, Creator, Holder, Cancellation, Suspension, Reactivation, Comprehensive and Global

Revision R evise

Replacement O bsolete +

N orm al

Suspension Suspend R esum e

Nullification N ullify

Reactivation R eactivate

Comprehensive

Completion C om plete

Existence Activate

Creator C reate

Global

Holder H old R elease

Abortion Abort

Cancelation C ancel

ToC

Artifact Development Axes (cont’d)

[Capability] (Event) Describes the functions that the application is capable of performing in

Event Mood. Valid values include the following values: Completion, Revision,

Replacement, Nullification, Existence, Abortion, Creator, Holder, Cancellation, Suspension, Reactivation, Comprehensive and Global

Revision R evise

Replacement O bsolete +

N orm al

Suspension Suspend R esum e

Nullification N ullify

Reactivation R eactivate

Comprehensive

Existence Activate

Completion C om plete

Creator C reate

Global

Holder H old R elease

Abortion Abort

Cancelation C ancel

ToC

Best Practices – Narratives

Never reference a section number in the narrative, these change. Reference artifacts by Code only, publishing may be able to then insert hyperlinks.

Titles and Structured Sort Names should be in title case.

Descriptions should always be full sentences terminated with appropriate punctuation.

Use HTML (see next slide) to format narrative presentation.

Each domain introduction should be included in the PubDb using HTML markup. If tables are required within the introduction, please contact

publishing committee for instructions.

Informative

ToC

HTML Allowed in PubDb

All Description (memo type) fields in the PubDb support HTML to assist with formatting and display.;

The following HTML tags are allowed in the PubDb description fields: Ordered list <ol> <li> (close each with </ol> </li>) Unordered list <ul> <li> (close each with </ul> </li>) Bold Emphasis <b> (close with </b>) Italics <i> (close with </b>)

Note: You may not nest <b> and <i> Line Break <br/> or paragarphs as <p> … </p> 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.]

Diagram References <diagref ref=“{filename}”/>

Graphics <graphic source="./Graphics/{fileName}.gif" alt="{Caption text}"/>

Use appropriate title-case for titles/headings Reference standard HTML documentation for more information on how to

use HTML tags.

ToC

Best Practices – Storyboards & Narratives

Storyboards Purpose - less than 250 characters, brief description of why the storyboard

was developed and what it covers for quick reference. There may be more than one narrative, but one is sufficient. Each narrative should be an ‘alternative’ narrative that fulfills the

purpose. Narratives should not build or depend upon each other (cumulative).

E.g NOT create/update/replace OK: Admit Emergency; Admit Inpatient

Use sub-headings (html markup) within the narratives to organize the information.

Use standard names for storyboard Entities from ExampleData.xsl (patient/doctor/hospital etc).

Use references to AR, TE or IN in the narratives. Support hierarchical Storyboards where one storyboard can list

storyboards that are dependent upon it. Currently identify parent storyboard in the dependent storyboard purpose.

PubDb will be adjusted to support this.

Example Authentication request & Final results (FICR_ST200200)

Informative

ToC

Structured Name – Storyboards & Narratives

No formal Structured Sort Name algorithm defined by M&M This name can be in any format Don’t start with the domain name – everything is sorted by domain

anyway. Don’t insert spaces or dummy characters at the beginning of a line to

force the sort order – they will be hard to maintain in future. Don’t use numbers to force the sort order – it is impossible to guarantee

that you will leave enough spaces between numbers to support future expansion.

Determine and document a structured sort name algorithm that works for the committee. Document it in the domain introduction if necessary.

Consider breaking down by focal class

Title name should be meaningful.

Purpose < 250 characters

Narratives – Alternatives, not Cumulative E.g NOT create/update/replace OK: Admit Emergency; Admit Inpatient

Informative

ToC

Best Practices – Application Roles

The TSC and Board agreed that conformance specifications in the current ballot packages will be non-normative. Thus the specification of Application Roles is now “Informative”

Extensive discussion in Atlanta led to the conclusion that the published Application roles must be aggregated at a more general level (similar to what was done in PA). This level was also called “business groups.”

The data bases and publications will allow detailed (low-level) application roles to be defined and “hidden,” if this facilitates assembling the higher level Application roles.

The Business Groups (published application roles) aggregate hidden roles into ‘useful’ hierarchies

Title Name for any Application role should be meaningful and unique Recommend use [Base Class] [Mood] where that makes sense

Informative

ToC

Best Practices – “Hidden” Application Roles

In the new data base, an Application Role may be marked as “hidden.” A “hidden” role will not appear in the ballot. However, interactions that

are defined using a hidden role as a sender or receiver, will appear in the ballot and will be assigned to the higher level (unhidden) roles that aggregate the responsibilities of (or “include”) the lower level rows.

Interactions should be defined against the lowest level (most-granular) Application roles to which they apply. These interactions will be automatically promoted to be applicable to any

higher level ARs that include the lower level role.

Warning: By default, when the Ballot-2 data-bases were migrated to the new format, all application roles were marked as “hidden.” Therefore, each committee must unhide the roles it wishes to expose in Ballot-3

Informative

ToC

Structured Name – Application Roles

Hidden RolesNon-query

[Base Class][Mood][Capability][Stereotype][Environment]

Queries [Base Class] [Mood] [Qualifier] Query Placer

Or

[Base Class] [Mood] [Qualifier] Query Fulfiller [Qualifier] uniquely identify the query, and will be based on the

parameters and response payload Inheritance structure as defined earlier

Includes Choice

Informative

ToC

Best Practices – Trigger Events

Document the state transition diagram and any variations from the RIM diagram, if needed to understand the domain.

Include a Trigger Event Type for all trigger events Interaction based

Occurs when a specific interaction is received 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

User request Occurs at the request of a human user

Provide a clear description referencing the state transition diagram if applicable.

Normative

ToC

Structured Name – Trigger Events

State-Transition Based [Base Class] [Mood] [State Transition][Qualifier][Action]

[Qualifier] is optional. For Revision, you may have multiple types (e.g. Change Dose, Change Address, Change Name) so add a qualifier after the [State Transition] before [Action]

Queries [Base Class] [Mood] [Qualifier] Query

Or

[Base Class] [Mood] [Qualifier] Query Response [Qualifier] uniquely identify the query, and will be based on the parameters

and response payload

Others There is the potential for other User Initiated or Interaction Initiated

triggers that are not covered above, but we haven’t hit them yet.

Normative

ToC

Best Practices – Interactions

Basic interaction patterns Initial experience with the first two ballots reveal three basic

interaction patterns. These patterns should be the primary focus of committee-

level development.

The basic patterns includeState Transition Notification – Sending application is

notifying receivers of the occurrence of a state transitionState Transition Request – Sending application is requesting

an action that will cause a state transition Query

Pattern detailThe following slides provide more detail about these patterns,

including their naming, interaction sets and receiver responsibilities

Normative

ToC

Structured Name – Interactions

State-Transition Based [Base Class] [Mood] [State Transition][Action]

[Environment] Special Cases

– Same issues as with revision.

– Environment can be pretty much anything

Queries [Base Class] [Mood] [qualifiers] Query / Query Response

Note: Environment is not specified

OthersNo others encountered as yet.

Normative

ToC

Pattern: State Transition Notification

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 Informer

Receiving Application RoleTracker

Normative

ToC

Pattern: State Transition Notification (cont’d)

No receiver responsibility

Informer Tracker

1.2

SendN otification

1.2

R eceiveN otification[Base C lass][Mood][Trigger]Notification[environm ent]

Normative

ToC

Pattern: State Transition Request

Starts with interaction type Request for Action

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

Always has an associated interaction of type Request Response-Refuse Interaction has a trigger that is ‘Interaction Based’ on the previous

Request for Action

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

Normative

ToC

Pattern: State Transition Request (cont’d)

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:

Proposals are confirmed by Orders, Intents or Events 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:

Proposals are confirmed by Orders, Intents or Events Orders are confirmed by Intents or Events

Normative

ToC

Pattern: State Transition Request (cont’d)Placer

(Confirmation Receiver A)(Confirmation Receiver B)

Fulfiller(Confirmer A)(Confirmer B)

1.2

Send R equest

1.2

R eceiveR equest[Base C lass][Mood][Trigger]Fulfillm ent Request[environm ent]

1.2

D eterm ineR esponse

1.2

SendR ejection

1.2

SendC onfirm ation

A

1.2

R eceiveR ejection

1.2

SendC onfirm ation

B

1.2

R eceiveC onfirm ation

A

1.2

R eceiveC onfirm ation

B

[Base C lass][Mood][Trigger]Rejection[environm ent]

[Base C lass][Mood A][Trigger]Confirm ation[environm ent]

[Base C lass][Mood B][Trigger]Confirm ation[environm ent]

Normative

ToC

Pattern: Query

Starts with interaction type QueryTrigger 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

Normative

ToC

Pattern: Query (cont’d)

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:

Proposals are confirmed by Orders, Intents or Events 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:

Proposals are confirmed by Orders, Intents or Events Orders are confirmed by Intents or Events

Normative

ToC

Pattern: Query (cont’d)

Query Placer Query Fulfiller

1.2

Send R equest

1.2

R eceiveR equest[Base C lass][Mood][qualifiers]Q uery

1.2

SendR ejection

1.2

R eceiveR ejection [Base C lass][Mood][qualifiers]Q uery Response

Normative

ToC

Best Practices – Models

Includes: DMIM/RMIM/HMD/MT

Model Names should be clear and understandable. For example don’t use A_Account as an RMIM name.

Must have better descriptions/walkthroughs of the DMIMs and RMIMs

Best Practices Example from Ballot #2: Lab D-MIM (POLB_DM000000) Claims and Reimbursements (FICR_DM000000)

Normative

ToC

Structured Name – Models

D-MIMs [Domain name] Domain Model

R-MIMs [Base Class] [Mood]

HMDs [Base Class] [Mood] [State Transition]

Not all transitions need HMDs – Common HMDs for suspend/resume, abort, nullify.

Message Type [Base Class] [Mood] [State Transition] [Environment]

Normative

ToC

Formal clone names in Models

In Ballot 3, the names of the class clones (and their resulting HMD associations) should be based on an HL7-adopted algorithm that names each clone and association using the class (or type) code and mood (or determiner) code as the basis for generating the formal name. Thus:Prefixes like A_ and AR_ are going awayAlgorithmically defined names will look like

ObservationEvent (for an Act), Reason (for an act relationship) and Patient for a role.

Association names will reflect the semantic differences of the direction of travel

Normative

ToC

Formal clone names in Models (cont’d)

Visio will propose names automatically for use when designing the R-MIM or D-MIM

RoseTree has the ability to assert these names for models that have already been placed in a repository.Note: RoseTree and Visio will use a single DLL for these

functions, and thus will not propose “conflicting” names

Committees may revise these names in either Visio or but are strongly encouraged not to do so. If a committee chooses to revise these names, care must be taken to assure that the name does not suggest a semantic interpretation that goes beyond the specified type/class and mood/determiner codes.

Normative

ToC

CMET changes - Tightly/Loosely coupled

The notion of tightly coupled vs. loosely coupled CMETs is being altered in the CMET design. Going forward, the CMET task group will define "Identified" CMETs as

a constraint on the quivalent “Detailed” CMET. This means that a message instance containing an "identified patient" will

be a valid instance of a “detailed patient” and thus any given message can support both tightly coupled and loosely coupled environments.

Result is that HL7 can drop all "tightly coupled" messages (and interactions, and application roles)

Instead, users can use implementation profiles to define a tightly coupled environment as a constraint on the HL7-defined messages

What is more, users can “mix and match” (for example they could choose to be tightly coupled for procedures and loosely coupled for patients within a single set of interactions.

Therefore, committees should define all messages using "Detailed" CMETs, unless the identified CMET is always required for a given message or interaction.

Normative

ToC

Domain constraints in Models & HMDs

Going forward, the use of compound domain specifications in the RMIM and HMD specifications is deprecated. A compound domain specification is one that is expressed like “ORD + INT” or “ActFinancialClass + INC”

Thus, the “domain” field in RMIMs and HMDs: Should never include a "+“ Should contain ONLY a defined domain name or a single code value

As a result, the committees must propose domain name additions for any compound domains that they need in the ballot

A list of compound domains that existed in Ballot-2 has been circulated and discussed on the M&M list.

Normative

ToC