Skip to main content

Creating Custom Schema Categories

It may be necessary to create custom schema categories in Ensemble. This chapter describes the details. It includes the following topics:

Important:

Never edit the built-in schema category definitions. When you need a custom schema (or, for HL7, when you need custom message types that contain Z-segments), create a custom schema category definition that uses a built-in schema category definition as its schema base.

Be sure to perform these tasks in the same namespace that contains your production.

When Custom Schema Categories Are Needed

The ASTM, EDIFACT, HL7, and X12 standards are extensible.

For example, a common practice in customizing ASTM is to add custom segments to an otherwise standard ASTM document structure.

Similarly, the common practice in customizing HL7 is to add custom segments to an otherwise standard HL7 message structure. By convention, the custom segments have names that begin with the letter Z (ZEK, ZPM, etc.), so custom segments are called Z-segments. A custom message structure often consists of a standard message with a few Z-segments added to it.

If you are working with documents that do not follow a standard schema that you have loaded, it is necessary to create the corresponding custom schema category if you want to do either of the following:

  • Perform structural document validation

  • Use segment and field path names in BPL, DTL, and routing rule syntax

Ways to Create Custom Schema Categories

There are four general ways to create custom schema categories:

The Studio Workspace window displays a list of the schema categories in the given namespace. See the Other folder. These definitions have file extensions such as .AST, .HL7, and .X12.

Syntax for Schema Categories in Ensemble

Ensemble uses the same XML-based syntax to represent schema category definitions for ASTM, EDIFACT, HL7, and X12. The following shows an example. Note that the actual text is longer and wider than the example, which contains ellipses (...) for omitted items and is truncated at right.

generated description: portal schema xml

Inside the <Category> element, the example begins with two sets of XML elements that you do not need to work with: <MessageGroup> and <MessageEvent>. These elements group HL7 messages into functional categories. The example ends with two other XML elements that you do not need to work with: <DataStructure> and <CodeTable>. These elements define the range of possible values for certain fields in certain messages.

When you create a custom schema category, you supplement an existing schema by defining custom segments (Z-segments) and then stating which message types and message structures may contain those segments. To accomplish this, you only need to work with the XML elements <MessageType>, <MessageStructure>, and <SegmentStructure>.

A custom schema category definition is simpler than a built-in definition and contains fewer statements. Everything in the base category is included in the custom schema category definition. There is no need to repeat the definitions of standard message types. You only need to define custom message types. The conventions for doing this are as follows:

What to Define How to Define It
Custom schema category definition <Category>
Custom segments (called Z-segments for HL7 messages) <SegmentStructure>
Any message structures that include custom segments <MessageStructure>
Any message types that include message structures with custom segments. A message type identifies:
  • The message structure to send

  • The message structure to expect in response

<MessageType>

When viewed in Studio, a custom schema category definition resembles the following figure. The actual text is wider than the example, which is truncated at right. You can view the complete example by opening the schema definition file Demo.HL7.MsgRouter.Schema.HL7 in the ENSDEMO namespace.

generated description: portal schema xml custom

<Category>

The <Category> element is the top-level container for the XML document that describes the custom schema category. The following is an example of <Category> syntax for a custom schema category definition:

<Category name="Demo.HL7.MsgRouter.Schema" base="2.3.1">
  <!-- All the statements in the custom schema category definition -->
</Category>

The following table describes the <Category> attributes.

Attribute Description Value
name Name displayed in the Schema Structures page in the list of available schema categories. String. For convenience, use the name of the .HL7 file or other schema file
std When 1 (true), this <Category> block describes a standard HL7 schema category. The default is 0 (false). For standard schema category definitions only. Do not use std in a custom schema.
base Identifies the schema category that is the base for this custom schema category. Every definition in the schema base is automatically included in the custom category; statements in the custom schema category simply add to the base. The name of a standard or custom schema category defined using a <Category> block in another .HL7 file or other schema file.

<SegmentStructure>

A <Category> element may contain one or more <SegmentStructure> elements. Each <SegmentStructure> element defines the structure of a custom segment (Z-segment). The following is an example of <SegmentStructure> element syntax:

<SegmentStructure name='ZNB' description='Newborn Abstract'>
  <SegmentSubStructure piece='1' description='SetID' symbol='!'
                       length='4' required='R' ifrepeating='0'/>
  <SegmentSubStructure piece='2' description='Birth Status Code'
                       length='60' required='O' ifrepeating='0'/>
  <SegmentSubStructure piece='3' description='Birth Type Code'
                       length='60' required='O' ifrepeating='0'/>
  <SegmentSubStructure piece='4' description='C-Section Indicator'
                       length='2' required='O' ifrepeating='0'/>
  <SegmentSubStructure piece='5' description='Gestation Period - Weeks'
                       length='3' required='O' ifrepeating='0'/>
  <SegmentSubStructure piece='6' description='Encounter Number' symbol='!'
                       length='12' required='R' ifrepeating='0'/>
  <SegmentSubStructure piece='7' description='Newborn Code' symbol='!'
                       length='60' required='R' ifrepeating='0'/>
  <SegmentSubStructure piece='8' description='Newborn Weight'
                       length='10' required='O' ifrepeating='0'/>
  <SegmentSubStructure piece='9' description='Stillborn Indicator'
                       length='8' required='O' ifrepeating='0'/>
</SegmentStructure>

The following table describes the <SegmentStructure> attributes.

Attribute Description Value
name Name displayed in the Schema Structures page in the list of available segment structures. 3–character string. By convention, custom segment names begin with the letter Z.
description Text description of the segment contents, displayed in the Schema Structures page and as a tooltip for the Document Viewer page. String

<SegmentSubStructure>

A <SegmentStructure> element may contain one or more <SegmentSubStructure> elements. Each <SegmentSubStructure> element describes one field of the custom segment, in sequential order from top to bottom. The following is an example of <SegmentSubStructure> element syntax:

<SegmentSubStructure piece='6' description='Encounter Number' symbol='!'
                     length='12' required='R' ifrepeating='0'/>

The following table describes the <SegmentSubStructure> attributes.

Attribute Description Value
piece Number displayed in the Schema Structures page when the user asks to view details of the segment that contains this field. This number can be used to identify the field in a virtual property path. Integer. Each <SegmentSubStructure> within a <SegmentStructure> must use piece values in sequential order, beginning at 1 and incrementing by 1.
codetable Code table that enumerates a list of valid values for this field. This attribute is typically not used in a custom schema. The name of a code table defined using a <CodeTable> block.
datastruct Data structure that specifies how to interpret the values in this field. This attribute is typically not used in a custom schema. The name of a data structure defined using a <DataStructure> block.
description Text description of the field contents, displayed in the Schema Structures page and as a tooltip for the Document Viewer page. String
symbol

Symbol that indicates the requirements for presence, absence, or repetition of this field within the segment.

This field is optional. It serves as an indicator on the Schema Structures page. It does not actually control the requirement or repetition of fields. See required and ifrepeating.

A single character:

  • ! means 1 only. The field must appear, but only once.

  • ? means 0 or 1. The field may appear, but at most once.

  • + means 1 or more. The field may repeat one or more times.

  • * means 0 or more. The field may repeat zero or more times.

  • & means the field may be present, and may repeat, but only under certain conditions.

length Upper limit on the number of characters that can be present in this field. Integer
required Whether or not this field must be present in the segment.

A single character:

  • C means conditional

  • O means optional

  • R means required

ifrepeating Whether or not this field may repeat within the segment. Integer. 0 means no, 1 means yes.

<MessageStructure>

A <Category> element may contain one or more <MessageStructure> elements. Each <MessageStructure> element provides a specification for the number and arrangements of segments in a message structure. The following is an example of <MessageStructure> element syntax:

<MessageStructure
  name='MFN_M03'
  definition='base:MSH~base:MFI~{~base:MFE~[~ZSI~]~base:OM1~[~base:Hxx~]~}'
  description='HNB MFN message'
  />

The following table describes the <MessageStructure> attributes.

Attribute Description Value
name Name displayed in the Schema Structures page in the list of available message structures. 3–character string, plus an underscore (_), plus a 3–character string.
definition Specification for the number and arrangements of segments in the message structure. May include a mix of standard and custom message segments. See syntax rules below. String that includes the 3–character name values for standard or custom message segments defined using <SegmentStructure>
description Text description of the field contents, displayed in the Schema Structures page and as a tooltip for the Document Viewer page. String

Syntax for the definition string works as follows:

  • Keep the entire string all on one line

  • List each segment sequentially from left to right

  • When listing a segment, use its name value as defined by a <SegmentStructure>

  • Separate a segment from the next segment by a ~ (tilde) character

  • If a segment or block of segments repeats, enclose the repeating part in {~ and ~}

  • If a segment or block of segments is optional, enclose the optional part in [~ and ~]

Within a definition, a name may be simple, in which case Ensemble assumes the value refers to a custom <MessageStructure> block within the same .HL7 file. Alternatively, a name may refer to a standard message structure from the schema base. This means it is defined in the .HL7 file identified by the base attribute in the containing <Category> element. To indicate this, the name must use the prefix:

base:

So that Ensemble can find the appropriate <SegmentStructure> in the other file. No other external .HL7 file can be referenced; only the schema base.

In the <MessageStructure> example at the beginning of this topic, only the ZSI segment is defined in the same .HL7 file. The other segments (MSH, MFI, MFE, OM1, and Hxx) are all defined in the schema base.

<MessageType>

A <Category> element may contain one or more <MessageType> elements. <MessageType> entries define any message types that include message structures that have custom segments. A <MessageType> element is a simple list of two items:

  • A message structure to send

  • A message structure to expect in response

The following is an example of <MessageType> element syntax:

<MessageType name='ADT_A31' structure='ADT_A01' returntype='base:ACK_A31'/>

The following table describes the <MessageType> attributes.

Attribute Description Value
name Name displayed in the Schema Structures page in the list of available message types. 3–character string, plus an underscore (_), plus a 3–character string.
structure The message structure to send. The name of a standard or custom message structure defined using <MessageStructure>
returntype The message structure to expect in response. This must be a valid ACK message structure. Make sure the returntype has a value from the schema base. For example: returntype="base:ACK" The name of a standard or custom message structure defined using <MessageStructure>

structure values can be simple name values from the current .HL7 file. If a file contains syntax like the following, where the structure is MFN_M03:

<MessageType name='MFN_M03' structure='MFN_M03' returntype='base:MFK_M03'/>

Then the same file must also contain syntax like the following, to define MFN_M03:

<MessageStructure
  name='MFN_M03'
  definition='base:MSH~base:MFI~{~base:MFE~[~ZSI~]~base:OM1~[~base:Hxx~]~}'
  description='HNB MFN message'
  />

Alternatively, structure or returntype values can refer to a standard message structures from the schema base. To indicate this, the values must use the prefix:

base:

So that Ensemble can find the appropriate <MessageStructure> entries, in the .HL7 file identified by the base attribute in the containing <Category> element. No other external .HL7 file can be referenced; only the schema base.

The following example uses both styles of syntax. This example defines a custom message type MFN_M03 that sends a custom MFN_M03 and receives a standard MFK_M03 as a response.

<MessageType name='MFN_M03' structure='MFN_M03' returntype='base:MFK_M03'/>
FeedbackOpens in a new tab