HL7 v2 messages are not used in a vacuum, rather they are part of a larger system designed to satisfy one or more use cases. An HL7 v2 implementation guide is a specification that describes this larger context. An implementation guide is created to organize a collection of message profiles for specifying a set of related interactions described in a use case or use cases. Implementation guides may describe broader conformance requirements such as application functionality. Such requirements may include how a set of messages are to be used to enact certain application functionality among applications (actors).
Broadly speaking, implementation guides are containers for message profiles. In short, implementation guides describe the use case(s), the applications (actors) involved, the message profile(s), the interaction among the actors; and they also can specify functional requirements. A message profile in the context of a messaging standard describes the requirements for a single interaction (e.g., Send an Unsolicited Immunization VXU V04 message).
Figure 3.1 illustrates a generic logical organization of an Implementation Guide. There are no definitive rules for what constitutes an implementation guide. For example, some implementation guides will focus on interoperability definitions and include limited application functional requirements (mostly implied); whereas others will include functional requirements to a greater degree.
|
Profile Identifier |
Message Definition |
Profile |
Related Profiles |
|---|---|---|---|
|
Z22 |
VXU V04 |
Send Immunization History |
Z23 |
|
Z23 |
ACK V04 |
Acknowledgement |
Z22 |
|
Z34 |
QBP Q11 |
Request Immunization History |
Z31 Z32 Z33 |
|
Z44 |
QBP Q11 |
Request Evaluated History and Forecast |
Z42 Z33 |
|
Z31 |
RSP K11 |
Return a list of Candidates Profile |
Z34 |
|
Z32 |
RSP K11 |
Return an Immunization History Profile |
Z34 |
|
Z42 |
RSP K11 |
Return Evaluated History and Forecast |
Z44 |
|
Z33 |
RSP K11 |
Acknowledgement with No Person Records |
Z34 Z44 |
The CDC HL7 v2.5.1 Release 1.5 Implementation Guide for Immunization Messaging is an example of a guide that describes a set of relevant message profiles for a specific domain. Table 3.1 lists the base message definitions and derived profiles included in that guide. The left column of this table indicates the identifier of the profile and the column on the right side lists the valid profile transaction pair(s) for each profile. For example, the profile Z22 – Send Immunization History defines (refines) the requirements for a VXU V04 message interaction. When it is paired with the Acknowledgment profile (Z23), a transaction is defined. The implementation guide provides use cases, actor definitions, transactions, and limited functional requirements. Each refinement of a message definition (e.g., VXU V04) specifies a message profile (e.g., Z22) and corresponds to an interaction. The collection of message profiles and associated use case information define the implementation guide. A message profile identifier or collection of message profile identifiers can be declared in a conformance clause for an application’s or product’s claim of conformance (e.g., a claim of conformance to a message profile). This claim is indicated in the message instance via the MSH-21 (Message Profile Identifier) element.
Figure 3.2 illustrates a representative implementation guide for a set of related immunization use cases. This diagram illustrates a use case (e.g., Send Immunization), the actors involved (i.e., EHR-S and IIS-Immunization Information System), and a set of relevant transactions (e.g., Z22/Z23) and interactions (e.g., Z22-VXU).
As stated in the Conformance Clause (Section 3.1.8), the implementation guide is informative within the context of this specification but highly recommended for documenting an interoperability solution. In addition, certain aspects in an instance of an implementation guide can be made normative by the implementation guide author. For example, an implementation guide can contain functional requirements and declare those as normative requirements; however, the implementation need not contain functional requirements at all.
The remainder of this section provides a sample outline of an HL7 v2 implementation guide. The manner in which the sample implementation guide is organized and a list of what parts it may contain are provided for guidance.
An implementation guide may contain various sections that provide background information to inform the reader of the overall purpose, scope, conventions, conformance clause, and any other facts the author thinks are pertinent for the use and application of the implementation guide. The following sub-sections provide a list and descriptions of common background sections.
This section is the beginning of the technical content. The Introduction provides basic background information about the implementation guide, including the problem statement, anticipated stakeholders, sponsors, and scope. Additional sub-sections (listed below) may include the purpose, intended audience, organization of the guide, reference profiles, scope, and key technical decisions or conventions.
The purpose can describe the intended use of the implementation guide.
This section provides information about the stakeholders who may have an interest in the implementation guide. This audience can include implementers, providers, hospitals, and records offices, such as public health registries. The section may indicate prerequisite knowledge requirements. Additionally, it may indicate any relationship to a regulation or certification program.
The scope provides, from a high-level perspective, the use cases the implementation guide is covering and the boundaries within the use cases. This section could include an “extended” workflow and indicate the portions of the workflow covered in the implementation guide (“in-scope”). The section also can include aspects that are not covered in the implementation guide (“out-of-scope”). The scope is intended to give the reader the appropriate context for interpreting the requirements.
This section informs the reader about the layout and design of the implementation guide. It is intended to help the reader navigate the document. Implementation guides may present the profiles in different ways. One way may be to define the building block components, such as the data type and value set definitions, separately and then describe the message definitions that reference these components. Alternatively, a message profile section contains all of the components relevant for its definition. Using this method, components typically are duplicated in the implementation guide. Other formats may exist, e.g., specifying a differential profile while referencing the base profile.
This section refers to and/or describes implementation guides or other specifications or artifacts related to this implementation guide, including previous versions or publication history of this implementation guide where applicable. This section may also point to regulations that influence the implementation guide.
An implementation guide should identify the mechanisms used to specify the included requirements. This document serves as the template for creation of the requirements, as most of the requirements must be specified via the conformance constructs; however, additional narrative-type requirements regarding the implementation guide, profiles, or functional requirements may need to be defined. In such instances, a set of standardized conformance keywords (also referred to as conformance verbs) must be used. The conformance keywords help define the requirements and testable criteria more precisely.
It is recommended that specifications adopt, in principle, the Key words for use in RFCs to Indicate Requirement Levels (commonly known as RFC 2119). Depending on the type of specification and its purpose, a subset of the keywords may be appropriate. Below is an example of a subset of the keyword definitions extracted from RFC 2119:
KEYWORDS:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. The following definitions are excerpted from the RFC:
MUST or the terms "REQUIRED" or "SHALL" means that the definition is an absolute requirement of the specification.
MUST NOT or the phrase "SHALL NOT" means that the definition is an absolute prohibition of the specification.
SHOULD or the adjective "RECOMMENDED" means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
SHOULD NOT or the phrase "NOT RECOMMENDED" means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood, and the case carefully weighed, before implementing any behavior described with this label.
MAY or the adjective "OPTIONAL" means that an item is truly optional. One software supplier may choose to include the item to enable certain capabilities while another software supplier may omit the same item. In either case, the communication partner cannot be expected to either provide it (sender) or process it (receiver) without clear and voluntary agreement between the partners.
An implementation guide should contain a conformance clause that defines the requirements, criteria, or conditions that must be satisfied by an implementation to claim conformance to the specification. The conformance clause identifies what must conform and how conformance can be met. This information typically is provided via a list of profiles or use cases that contain the profiles.
The conformance clause also can describe options and levels. The conformance clause will state which profiles must be implemented and which profiles may be implemented. The option to implement the same requirements but at different difficulty levels also may be allowed, which is useful when the specifiers want to ease the community into adoption of a difficult requirement by providing a preview of the sought-after implementation without mandating its immediate adoption. Implementers can use the conformance clause to make a claim related to the options and levels they selected.
The conformance clause will indicate the normative and informative parts of the specification. Normative parts of the implementation guide contain requirements that must be implemented (and, therefore, be verifiable). Informative parts of an implementation guide provide guidance that aids in implementation or provide supplementary information. No provisions in the informative part of a specification need to be implemented.
An Actor is an information system or a component of an information system that produces, manages, or acts on information associated with operational activities in an organization. An actor has a specific role, performs specific functions, and is defined in an abstract manner. Actors exchange information through standard HL7 v2 messages and can be an initiator or a responder. An Initiator is an entity that starts an action and is also referred to as a Sender, Producer, or Client. A Responder is an entity that is reacting to the action of the Initiator. A responder is also referred to as a Receiver, Consumer, or Server.
A Use Case describes a system capability and the associated sequences of actions that a system performs to achieve an intended outcome. The use case can include the actors involved (including the sending and receiving systems); the interactions (including the message exchanges) between the actors, system functional requirements, acknowledgement requirements, pre and post conditions; and any other pertinent information that aids in the understanding of an implementer, such as example messages or message excerpts.
The use case describes messaging requirements at a high-level and references detailed requirements specified in the Messaging Infrastructure. An implementation guide will typically contain more than one use case. A use case can be considered a container that collates the pieces needed to specify a system capability. The following sub-subsections provide a list of candidate content of a use case definition.
The Interaction Specification describes the dynamic aspects of a system. In HL7 v2, an interaction specification typically will include the sequence of trigger events and resulting message flows between two or more actors (Interaction Model) and any acknowledgement responsibilities. The Interaction Specification can be represented in literal or graphical form. Graphical form can include standard UML interaction diagrams (i.e., sequence and collaboration diagrams) and/or activity diagrams. An interaction specification must be defined in an implementation guide for relevant uses cases and must include an interaction model and acknowledgement responsibilities; however, this specification does not prescribe a specific method or format for doing so.
For each interaction, the specific HL7 v2 acknowledgements required and/or allowed for use with a message profile must be defined. Specifically, the acknowledgement responsibilites must identify whether an accept and/or application level acknowledgement is allowed or required.
The acknowledgement responsibilites must define the conditions under which an accept and/or application level acknowledgement is expected.
Allowed conditions include:
For a given interaction, multiple acknowledgement outcomes may be defined. Figure 3.4 shows an activity diagram for the acknowledgement responsibilities of the receiver in reaction to the processing of the Send Immunization Event.
Functional requirements are a set of requirements that describes the functions and operations of an application (or actor). They provide a defined set of capabilities of the application and are also referred to as business rules. Functional requirements may be included in HL7 v2 implementation guides and may be defined for each element or a collection of elements necessary to conduct a given operation. The extent to which functional requirements are included in implementation guides varies; typically, their inclusion is, and should be, minimal. A separate functional requirements specification allows for a protocol-independent specification that can change irrespective of the interface specification.
Example messages, or excerpts of them, may be included in implementation guides to provide insight and expected outcomes of the message profile for a specific use case interaction. Implementers can refer to the example messages to gain understanding but should not infer that the examples are comprehensive and use them as the sole basis for implementation.
The messaging infrastructure part of an implementation guide provides the specification of the messaging requirements. Messaging requirements are defined in the message profiles that include the message, segment, data type, and vocabulary definitions. An HL7 v2 implementation guide must include the messaging infrastructure.
An implementation guide can contain any other relevant information to aid developers in implementations. This information may include: