This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "Use of HL7 templates in CP"

From HL7Wiki
Jump to navigation Jump to search
Line 716: Line 716:
 
|1..1
 
|1..1
 
|M
 
|M
|Contains ''ImmunizationRefusalReason''template id 2.16.840.1.113883.2.4.6.10.90.1054
+
|Contains ''ImmunizationRefusalReason'' template id 2.16.840.1.113883.2.4.6.10.90.1054
 
|-
 
|-
 
|}
 
|}

Revision as of 18:16, 24 February 2012

Patient Care | Patient Care Normative Ballot Content

Contents

Use of Templates in Care Provision

HL7 Templates

An HL7 template is a constraint on models based on the HL7 Reference Information Model (RIM). It expresses the data content needed in a specific clinical or administrative context.

In healthcare there are prescribed patterns by which, for example, multiple observations may be combined to describe selected, gross observations. Some observations may be simple, such as the single lab result (e.g. potassium in blood is 4.4 mEq/L) or the blood pressure concept, which involves a set of expected observations (i.e., systolic, diastolic, patient position, method, etc.). Other more elaborate diagnostic procedures may involve hundreds of related pieces of information, including anatomy, orientation, sequences of measurements, etc.

In HL7, more or less generic models exist; the Patient Care model, especially the Care Statements = Clinical Statement Pattern (CSP) is one of it. Templates provide a method of describing rules for combining and constraining HL7 v3 XML instances like a Patient Care message. Templates can be used for three purposes:

  • To have a guideline to create (a fragment of) a Patient Care message instance
  • To validate an instance whether it conforms to the specified template rules
  • To have a guidance while processing a Patient Care message instance.

The last point should be considered carefully, because an instance must convey fully semantics even without knowing the underlying template.

Based on user need and preference, the template ideally is a structure that can be used as a building block and, once defined, can be re-used whenever appropriate.

Kinds of Patient Care templates

The Patient Care standard describes conformance requirements in terms of two general levels:

  • Message root level templates: they define / refine the overall structure of a message starting from the Care Provision class, which templates are contained in the message and whether they are optional or required.
  • Substructure level templates (patient, provider etc.)
  • Clinical Statement level templates: impose the Clinical Statement Pattern of a Patient Care message; they define the constraints on the classes, class attributes, data types and class relationships.

Template Identifiers in instances

Template identifiers (templateId) are assigned at the Message root level and Clinical Statement level. When valued in an instance, the template identifier signals the imposition of a set of template-defined constraints. The value of this attribute, e.g.

<templateId root="2.16.840.1.113883.10.1.2.3" />

provides a unique identifier for the template in question.

If a template is a specialization of another template, its first constraint indicates the more general template. The general template is not always required. In all cases where a more specific template conforms to a more general template, asserting the more specific template also implies conformance to the more general template.

Open and Closed Templates

In open templates, all of the features of the Patient Care based specification are allowed except as constrained by the templates. By contrast, a closed template specifies everything that is allowed and nothing further may be included.

Open templates allow HL7 implementers to develop additional content not constrained within the template. HL7 encourages implementers to bring their use cases forward as candidate requirements to be formalized in a subsequent version of the standard to maximize the use of shared semantics.

In general, Patient Care defines open templates only.

Template Metadata

Template metadata is mainly defined in the “Business Requirements for Template Registries”. In order to support template registries and to allow the appropriate use of templates, the following metadata is associated with each template.

@id

A mandatory globally unique, non-semantic, identifier for the template as the primary identifier.

@name

A required name for the template as a secondary identifier. Please note that there is no guarantee that the name is globally unique.

@effectiveDate

The mandatory date after which the template can be considered for use. Use of the template prior to this date would be considered an invalid use of the template.

@expirationDate

The optional date at which the concept represented by this template becomes stale, and should be reviewed for (clinical) relevance and accuracy. Use of the template after this date would be considered venturesome.

@statusCode

The mandatory status of the template. According to the Business Requirements for Template Registries the following status codes of a template shall be supported.

statusCode Description
draft Template under development (nascent). Metadata and template may be incomplete. Entered primarily to encourage other users to be aware of ongoing process.
active Template has been published by the custodian organization and deemed fit for use. May have associated adoption and annotation metadata
retired Template retired: No longer fit for use. Information available for historical reference.
inactive Template never recommended for use. For example, rejected, withdrawn or found another template fit for use of the one under development. Will not have associated adoption metadata.
rejected Template is rejected
cancelled Template is withdrawn
update Template under Update (adoption metadata): adopter adds adoption metadata and/or grouping metadata: these are the only actions an adopter organization can perform. The template(s) in the “under update (adoption metadata)” status are unavailable for any other status or metadata changes until the “under update/adoption metadata” action has been completed.
pending Template is in pre-publication review: the template is complete, pending appropriate review. Entered primarily to encourage other users to be aware of and/or participate in the review process. The custodian organization has not given it an “Active” status (i.e. it has not been published); and it may still be rejected (transitioned to an inactive status). E.g. the template may be under ballot by an SDO.
review Template is in Review: a post-publication state; may result in a new version or a retirement or no change at all. A new version is one that adds clarity but not new intent; the version number is incremented by one, but the identifier is unchanged. A retirement is a template that is no longer fit for purpose, and which may be replaced by a different a template with a different identifier, which is linked to the retired template.

@displayName

The optional human readable display name for the template for orientation purposes. This is not intended for machine processing.

@versionLabel

The optional human readable version label for the template to be able to determine the correct version of a template. This is not intended for machine processing.

desc

An optional free text natural language description of the intent and scope of the template. The purpose is to provide the author’s initial intent for the template. A description may be present in different languages.

context

An optional context of the template, i.e. where in an XML instance the template rules are considered to applied to. From a practical viewpoint templates may have no context. In this case the template is not “exposed” for external use, but rather used for internal inclusion in other templates. If the template is intended to be published for external purposes, it shall have a context. Typically there are three types of context specifications.

sibling node context

The template rules apply to all sibling elements and descendent nodes in the instance.

Example

CDA section level templates are often defined in sibling node context. 
parent node context

The template rules apply to the siblings of the parent node and all descendent nodes in the instance. Example

CDA entry level templates are often defined in parent node context. 
pathname specified context

A pathname (making use of XPath expressions) is specified, which allows to activate templates in an instance without the need to have template id elements in an instance. Example

Assume a recordTarget in an instance is considered to be unique for the payload. Then a template containing rules for the record target can be defined in the context of pathname “hl7:recordTarget”.

item

The item is used as an identification mechanism when it comes to error messages by derived validation scripts. For example if each constraint has a (unique) number, it may be used to precede every error message. Example

A CDA “encounter” section level template defines the section code to be 46240-8 drawn from LOINC. Each constraint is uniquely identified by an identifier at or near the end of the constraint (e.g., CONF:7941).
Every error, warning or information that is raised during validation carries this constraint identifier.
The default is the template id.

example

Templates may have zero to many example fragments to illustrate valid instances. In addition, each class attribute definition may have also an example fragment.

Versioning aspects

Changes to the Template that do not change the semantics or intention of the template will constitute a new version of the Template being created. This means that the id of the former template remains the same and the @effectiveDate is changed to the date when the new version of the template was created. Any change to the semantic meaning of the template will constitute the creation of a new template. This means that a new template will get a new @id.

Expressing Constraints in Templates

Constraints expressed in templates may determine

  • The data type or a data type flavor
  • The cardinality
  • The conformance, e.g. if data may be absent (nullFlavor)
  • Vocabulary bindings and coding strengths
  • Possible fixed values
  • Additional properties such as units (measurements), ranges, fraction digits

of a class attribute. In general this means to determine the properties of an XML element or an XML attribute. Examples of class attributes in table format, with different attribute names, data types (DT), cardinalitiy (Card), conformance (Conf) and description.

Table: Class Attributes with data type, cardinality, conformance and a description
Attribute DT Card Conf Description
repeatNumber INT 0..1 O Number of repetitions
value PQ 1..1 R The measurement as a physical quantity
code CE CNE 1..1 M The code of the observation

Data Type Constraints

The data type of a class attribute is simply determined by specifying a data type name or a data type flavor name. Note that the constraint shall be equal to or a valid demotion of the corresponding data type of the underlying model (if present).

Examples

Attribute Description Data type (flavor)
classCode Class code of the act CS
id Instance identifier II
effectiveTime A time stamp TS
value A measurement of a physical quantity PQ
lotNumber The lot number ST
repeatNumber a non-negative integer INT.NONNEG
date A timestamp that may be valued up to a day TS.DATE

Note: Although not present in HL7 Data Types Release 1 or 1.1, data type flavors may be used in templates to constraint data types of class attributes.

Allowed Data Absent Reasons (Null Flavors)

In cases where data may be absent, i.e. non-mandatory attributes, indicated with a nullFlavor in an instance, the list of possible codes for the reason of absent data may be restricted.

Example

The list of valid codes for a (required) coded observation (value) is drawn from ValueSet SomeValueSet. There is only one exceptional situation allowed to be expressed in an instance, i.e. that the value of the observation is not known.
In this case the list of valid nullFlavor codes is restricted to be “UNK” only, i.e. the coded observation (value) shall be a code drawn from SomeValueSet or nullFlavor = UNK.

Fixed Values

Default Values

In practice so far no use case is known for specifying default values in a template.

List of Allowed Values

Quantity Ranges

Units

Textual Restrictions

regularExpression

A Regular Expression pattern defining the range of possible values for a string. In practice so far no use case is known for specifying regular expressions as a textual restriction in a template.

codingScheme

The intended coding scheme to be used for conforming instances for the textual data. In practice so far no use case is known for specifying coding schemes as a textual restriction in a template.

Cardinality

The cardinality indicator specifies the allowable occurrences within a message instance. The cardinality indicators are interpreted with the following format “m…n” where m represents the least and n the most:

  • 0..1 zero or one
  • 1..1 exactly one
  • 1..* at least one
  • 0..* zero or more
  • 1..n at least one and not more than n

Conformance

In some implementation guides conformance verbs as SHALL, SHOULD, MAY etc. are used. This is not handled consistently across several organizations (e.g., HL7, IHE, see also [Consolidating CDA Templates]). Once, conformance indicators are unified the can be incorporated in this document as well.

In this guide conformance verbs are used for vocabulary constraints (see following section) but not for templates as a whole or for template elements.

HL7 conformance indications are used instead. The following table gives an overview of mandatory items, the cardinality, conformance and whether data may be absent (nullFlavor).

Mandatory Conformance Minimum Cardinality Null ok? Comment
M R 1 No Shall be present and valued in a message
(not mandatory) R 0 Yes If no information is available, just don't send it
(not mandatory) R 1 Yes
(not mandatory) NP n/a No
(not mandatory) (unspecified) 0 Yes
Table: Overview of Conformance and Cardinality

Mandatory

The attribute is mandatory, i.e. a valid value shall be provided and no null value is allowed. The minimum cardinality is at least 1. This also includes that if the sender has no valid value for such an attribute, the message cannot be sent. It is indicated as “M” in the conformance column of the attribute table, a shorthand for “mandatory” with required conformance.

Example:

attribute code is 1..1 mandatory
Attribute DT Card Conf Description/Fixed value
code CE CNE 1..1 M The description of the code
Table: Class Attribute with data type, cardinality, conformance and a description

Required

The attribute is required, i.e. a valid value should be provided or if missing a null value is allowed if its minimum cardinality is 1, or may be omitted if its minimum cardinality is zero.

In messages, the element must be communicated if its minimum cardinality is one. In the case where the element is not mandatory, it may be communicated with a null value. Note that any element declared to be "Mandatory" must also be "Required" and have a minimum cardinality of one. If the minimum cardinality is zero, and the element is "Required", conforming applications need not send the element if data does not exist. For required elements, conforming applications must demonstrate their ability to provide and communicate not null values. Receiving applications must demonstrate their ability to receive and process (eg. Store, display to users) not null values for required elements.

It is indicated as “R” in the conformance column of the class attribute table.

Optional

The attribute is truly optional, i.e. a valid value may be provided or if missing may be omitted.

It is indicated as “O” in the class attribute table, a shorthand for an unspecified conformance with a minimum cardinality of zero.

Conditional

This usage has an associated condition predicate. It is denoted in the following format:

Card Conf Predicate
a1..b1 conf1 If condition1
a2..b2 conf2 If condition2
... ... ...
an..bn confn otherwise
Table: Condition Predicate Table

where a..b is the cardinality, conf denotes the conformance and condition is the condition, in human language or formalized in some constraint language. Please note that all predicates shall be mutually exclusive.

Example:

The cardinality (of a class attribute) is 1..1 if number of gravidities is greater than zero or 0..1 otherwise
Card Conf Predicate
1..1 M If number of gravidities > 0
0..1 O otherwise
Table: Example Condition Predicate Table

If the predicate is satisfied then

  • a conformant sending application must always send the element
  • a conformant receiving application must process or ignore data in the element; it may raise an error if the element is not present.

If the predicate is not satisfied then

  • a conformant sending application must not send the element.
  • a conformant receiving application must not raise an error if the condition predicate is false and the element is not present, though it may raise an error if the element is present.

A conditional attribute is indicated as “C” in the class attribute table, followed immediately by the condition predicate table.

Fixed

This indicates that an attribute has a fixed value. It fixed value shall appear in an XML instance.

It is indicated as “F” in the class attribute table, a shorthand for a mandatory element with required conformance with a fixed value. The cardinality should be 1..1.

Not used

This indicates that an attribute is not used. In principle, it is not part of an XML instance but is not rejected by validation mechanisms if present and a receiver should not raise an error when he received the element.

It is indicated as “X” in the class attribute table.

Not present

The attribute is not permitted, not part of an XML instance, rejected by validation mechanisms if found and should be rejected by receiver (raising an error).

It is indicated as “NP” in the class attribute table. There is no cardinality specified.

Vocabulary Conformance

The templates in this document use terms from several code systems. These vocabularies are defined in various supporting specifications and may be maintained by other bodies, as is the case for the LOINC® and SNOMED CT® vocabularies.

Note that value-set identifiers, e.g., ValueSet 2.16.840.1.113883.1.11.78 HL7ObservationInterpretation DYNAMIC, do not appear in messages/documents; they tie the conformance requirements of an implementation guide to the appropriate code system for validation.

Dynamic vs static binding

Value-set bindings adhere to HL7 Vocabulary Working Group best practices, and include both a conformance indicator and an indication of DYNAMIC vs. STATIC binding.

  • Value-set constraints can be STATIC, meaning that they are bound to a specified version (date) of a value set,
  • or DYNAMIC, meaning that they are bound to the most current version of the value set.

Example: binding to a single code

A simplified constraint, used when the binding is to a single code, includes the meaning of the code, as follows.

Example table with explicit XML attribute (data type CE) and binding to fixed code, codeSystem, etc.:

Attribute DT Card Conf Description/Fixed value
code CE CNE 1..1 M
  @code st 1..1 F 11450-4
  @codeSystem oid 1..1 F 2.16.840.1.113883.6.1
  @displayName st 0..1 F Problem List
  @codeSystemName st 0..1 F LOINC
Table: Example Class Attribute Table for a code

Verbatim

… SHALL contain exactly one [1..1] code/@code="11450-4" Problem List (CodeSystem: LOINC 2.16.840.1.113883.6.1) 

etc.

The notation conveys the actual code (fixed 11450-4) in the required @code attribute, the optional code’s display name (“Problem List” if present), the required OID of the code system from which the code is drawn (fixed 2.16.840.1.113883.6.1), and the optional code system name (LOINC).

XML attributes are denoted by a preceding @ and have cardinalities 0..1 (optional) or 1..1 (required) only. If an attribute is prohibited (may not be present), its conformance is set to NP.

HL7 Data Types Release 1 requires the @codeSystem attribute unless the underlying data type is “Coded Simple” or “CS”, in which case it is prohibited. The @displayName and the @codeSystemName are optional, but recommended, in all cases.

The above example would be properly expressed as follows.

or

Examples: code with STATIC or DYNAMIC binding to a particular ValueSet

Table:

Attribute DT Card Conf Description/Fixed value
confidentialityCode CE CWE 1..1 M ValueSet HL7BasicConfidentialityKind 2.16.840.1.113883.1.11.16926 STATIC 2010-04-21
languageCode CE CWE 1..1 R ValueSet Language 2.16.840.1.113883.1.11.11526 DYNAMIC
Table: Example Attribute Table

Verbatim:

… SHALL contain exactly one [1..1] confidentialityCode which SHALL be selected from ValueSet HL7BasicConfidentialityKind 2.16.840.1.113883.1.11.16926 STATIC 2010-04-21.
… SHOULD contain exactly one [1..1] languageCode which SHALL be selected from ValueSet Language 2.16.840.1.113883.1.11.11526 DYNAMIC

The first notation binds mandatory confidentialityCode to value set HL7BasicConfidentialityKind (as of 2010-04-21), the second notation binds required languageCode to value set Language 2.16.840.1.113883.1.11.11526 (most recent version).

Containment Relationship

The containment relationship constraints between a specific structure (context) in an XML instance and sub-structures in that context (child elements).

They may be indirect, meaning that where a structure asserts containment of a substructure, that substructure can either be a direct child or a further descendent of that structure, or be direct, meaning that the contained substructure shall be a direct child of the structure.

Example

A report about the first prenatal visit of a pregnant woman with historical findings recorded by an obstetrician or a midwife should contain an observation about the number of pregnancies so far (including the actual pregnancy), also known as “gravidity”.

Assume that the underlying model allows for clinical statements like an observation via a component relationship. Table:

Attribute DT Card Conf Description/Fixed value
component 1..1 R Contains GravidityObservation template id 2.16.840.1.113883.2.4.6.10.90.1053
  @typeCode CS 1..1 F COMP
Table: Example Attribute Table

Verbatim:

… SHALL contain exactly one [1..1] component such that it
  a)	SHALL contain exactly one [1..1] @typeCode="COMP" (CodeSystem: HL7ActRelationshipType 2.16.840.1.113883.5.1002)
  b)	SHALL contain exactly one [1..1] GravidityObservation (template id 2.16.840.1.113883.2.4.6.10.90.1053)

Assume that the referenced template is an observation with a LOINC code 11996-6 (number of pregnancies, reported), then the above example could be properly expressed as follows.

<component typeCode="COMP">
   <observation classCode="OBS" moodCode="EVN">
       <templateId root="2.16.840.1.113883.2.4.6.10.90.1053"/>
       
       <value xsi:type="INT" value="2"/>
   </observation>

</component>

Co-Occurance

Example: Amnionicity and Chorionicity

If the number of fetuses is more than 1, than an Amnionicity observation – number of fluid filled / (amniotic) sacs – and a Chorionicity observation– type of placentation – need to be reported.
Attribute DT Card Conf Description/Fixed value
component 1..1 M
  @typeCode CS 1..1 F COMP
C Conditionally contains

AmnionicityObservation template id 2.16.840.1.113883.2.4.6.10.90.1054

Card Conf Predicate
1..1 M If number of fetuses > 1
NP otherwise
C Conditionally contains

ChorionicityObservation template id 2.16.840.1.113883.2.4.6.10.90.1055

Card Conf Predicate
1..1 M If number of fetuses > 1
NP otherwise

Example: Immunization activity

An Immunization Activity can also include that a certain vaccination was not given (expressed as a negationInd/actNegationInd of the associated substance administration is valued “true”).

Assume that a business rule says that in this case an Immunization Refusal Reason shall be stated.

Table:

Attribute DT Card Conf Description/Fixed value
substanceAdministration
  @classCode CS 1..1 F SBADM
  @moodCode CS 1..1 F EVN
  @negationInd BL 0..1 O Refusal yes/no
  ...
  entryRelationship C Immunization Refusal Reason
Card Conf Predicate
1..1 M If @negationInd = true
0..1 O otherwise
  @typeCode 1..1 M RSON
1..1 M Contains ImmunizationRefusalReason template id 2.16.840.1.113883.2.4.6.10.90.1054

Originator Responsibilities: General Case

An originator can apply a templateId if there is a desire to assert conformance with a particular template.

In the most general forms of CDA exchange, an originator need not apply a templateId for every template that an object in an instance document conforms to. The implementation guide (IG) shall assert whenever templateIds are required for conformance.

Recipient Responsibilities: General Case

A recipient may reject an instance that does not contain a particular templateId (e.g., a recipient looking to receive only Procedure Note documents can reject an instance without the appropriate templateId).

A recipient may process objects in an instance document that do not contain a templateId (e.g., a recipient can process entries that contain Observation acts within a Problems section, even if the entries do not have templateIds).

Examples

Model and template hierarchy example

Clinical Statement Pattern (unconstraint model)

Assessment Scale (constraint model on Clinical Statement)

APGAR score (constraint model on Assessment Scale)