Creating Custom Schema Categories for Virtual Documents
It may be necessary to create custom schema categories in InterSystems IRIS® data platform. This page describes the details.
Never edit the built-in schema category definitions. When you need a custom schema, 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 EDIFACT and X12 standards are extensible.
For example, a common practice is to add custom segments to an otherwise standard document structure.
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 two general ways to create custom schema categories:
-
Create a copy of the schema file that most closely meets your needs. Edit that file. Then import it, as described in Portal Tools.
-
In an IDE, open the schema category definition that most closely meets your needs. Save that as a new definition. Then edit the copy. Syntax for Schema Categories in InterSystems IRIS provides details for the syntax of the definition.
Syntax for Schema Categories in InterSystems IRIS
InterSystems IRIS uses the same XML-based syntax to represent schema category definitions for EDIFACT and X12.
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 | <SegmentStructure> |
Any message structures that include custom segments | <MessageStructure> |
Any message types that include message structures with custom segments. A message type identifies:
|
<MessageType> |
<Category>
The <Category> element is the top-level container for the XML document that describes the custom schema 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 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 schema file. |
<SegmentStructure>
A <Category> element may contain one or more <SegmentStructure> elements. Each <SegmentStructure> element defines the structure of a custom segment.
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. . |
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. |
datatype | 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 <DataType> 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:
|
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:
|
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 InterSystems IRIS assumes the value refers to a custom <MessageStructure> block within the same file. Alternatively, a name may refer to a standard message structure from the schema base. This means it is defined in the file identified by the base attribute in the containing <Category> element. To indicate this, the name must use the prefix:
base:
So that InterSystems IRIS can find the appropriate <SegmentStructure> in the other file. No other external file can be referenced; only 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 file.
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: