X12 Schemas and Available Tools
This chapter provides an overview of the InterSystems IRIS® tools that you can use to work with X12 schemas and documents. It contains the following sections:
Using the X12 Schema Structures Page
Using the X12 Document Viewer Page
Creating Custom X12 Schemas
Defining X12 Search Tables
Using the X12 Schema Structures Page
The Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures page enables you to import and view X12 schema specifications.
For general information on using this page, see “Using the Schema Structures Page” in Using Virtual Documents in Productions.
To determine the schema structures, InterSystems IRIS extracts details from the .SETS, .SEGS, .COMS, .ELMS, and .CODES sections of the SEF file that was imported to define the structure of this X12 document. The description of a document is extracted from the .INI section of the SEF file that defines this X12 schema; an example is “Healthcare Claim Status Request.”
To load an X12 schema into InterSystems IRIS from the Schema Structures page, click Import and select your file. You can load either SEF or XSD files.
For suggestions on where to find SEF files (X12 schemas) to import, see “Standard Exchange Format (SEF) Files,” in the first chapter.
To load X12 schema files programmatically:
Start a Terminal session.
Change to an interoperability-enabled namespace and issue the following command:
Do ##class(EnsLib.EDI.SEF.Compiler).Import(filename)
Where filename is the full pathname of the schema file.
This command imports the data from the schema file and make it available as a schema definition within InterSystems IRIS.
InterSystems IRIS creates a name for the new schema category from the first piece of the first line in the .INI section of the SEF file. For example, in 837_X097.SEF you might see this line:
.INI 837_X098,,004 010 X098,X,X12-4010,Healthcare Claim: Professional
The extracted schema category would have this name:
837_X098
Due to the schema naming convention, if you want to edit a schema file to customize it, InterSystems suggests you first change the text in the schema file that provides its category name, so that you can distinguish your version from any other schema file that you also import into InterSystems IRIS.
A schema file may contain syntax errors. If so, InterSystems IRIS issues an error message and identifies the location of the error in the schema file.
Viewing a Document Structure
To view the internal organization of a document structure, select its name from the DocType Structures tab on the Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures page. InterSystems IRIS displays the segment structure of the document using the system of visual cues explained below. The following example shows the HIPAA_4010:820 document structure on this page. On the Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures page, select HIPAA_4010 in the left part of the page and select 820 in the right part. This displays the X12 Document Structure page.
Layout
Segments are listed in blue text and link to the relevant segment structure page.
Loops are listed in black text.
The segments that comprise the document structure are listed in sequential order, from left to right and top to bottom.
The name of each document segment is displayed: BPR, NM1, DTM, etc. This name indicates the type of segment that exists at this location in the X12 document structure.
Green dotted lines enclose segments that are optional.
Brown solid lines enclose segments that, if present, may repeat several times.
Yellow solid lines enclose segments that are part of a group.
A segment may be both repeating and optional (see segment NM1 above).
When you are viewing a segment diagram, if you hover the cursor over a three-letter segment name, a tooltip displays the syntax for referring to this segment in a virtual property path.
Raw Definition
To see the document structure in a raw text format, click Show Raw Definition Text. The raw definition of the HIPAA_4010:820 document structure is as follows:
Loops in X12 can have custom names. Note in the above raw definition sample for HIPAA_4010:820 that loop titles directly follow open bracket characters “[,{,(” unlike segment names, which are separated from bracket characters by a tilde “~”. To use a custom loop name, type in your custom name in the place of the default loop name within the schema file prior to importing the schema into InterSystems IRIS.
Legacy Document Structure
You can view the old document structure viewer for schemas by clicking Go to Validation Structure. The legacy document structure also provides some information that is not available in the default document structure viewer. For example, the legacy document structure can provide code tables, the number of loop repetitions allowed, and syntax notes.
Implementation Guide
This code identifies the relevant ASC X12 Implementation Guide which can be found at. The identifier is unique across all document structures and schemas.
Viewing a Segment Structure
To view the structure of a document segment, click on its name in any page similar to the example shown in the previous section. InterSystems IRIS displays a table that lists all the fields in that segment. This is the Schema Segment Structure page.
For example, if you click on the PER segment in the HIPAA_4010:276 document structure, InterSystems IRIS displays the following page.
The columns are as follows:
Elem — the number to use to access the element within the segment (if you prefer numbers).
Description — a short description of the element.
Property Name — the name to use to access the element within the segment (if you prefer names).
Data Type — a one to two letter symbol representing the element data type. See the table below for details.
Required — displays R for required, O for optional.
Length — displays the number of characters that can be in the element. If only one number is present, it represents the maximum number of characters. If two numbers are separated by a hyphen, it is the range of characters that can be in the associated element (minimum-maximum).
Max Repeats — the maximum number of times the element can repeat.
Alternate Description — a second, longer description of the element.
You can use this information, particularly the Property Name column, to build virtual property paths for InterSystems IRIS in the format segment:elem. The following are examples of virtual property paths involving simple elem values from the PER segment in the HIPAA_4010:276 document structure. The () shortcut syntax indicates all available instances of a repeating field, whereas (1) indicates the first instance:
loop2000A().loop2100A().PER:ContactFunctionCode loop2000A().loop2100A(1).PER:ContactFunctionCode loop2000A().loop2100A(2).PER:ContactFunctionCode loop2000A().loop2100A(x).PER:ContactFunctionCode loop2000A().loop2100A().PER:Name
Viewing a Composite Structure
When you select a name in the Composite Structure column, InterSystems IRIS displays all the elements in that data structure. This is the Composite Structure page. The column values are identical to those of the previous section.
Choosing a Different Category
It is a feature of the X12 standard that a document structure can differ by X12 version, even when the structure has the same name and number. For example, both X12 HIPAA_4010 and X12 HIPAA_5010 define a document structure called 277, but these definitions contain some differences in segments and segment repetitions. InterSystems IRIS provides the document structure definitions HIPAA_4010:277 and HIPAA_5010:277. The X12 Document Structure page makes it easy to see the differences between the two definitions, as the following two figures show.
Using the X12 Document Viewer Page
InterSystems IRIS provides a Document Viewer page for X12. You can use this page to display, transform, and export X12 documents (either external files or documents from the production message archives).
To access this page, select Interoperability > Interoperate > ASC X12 > ASC X12 Document Viewer. documents loaded from a file.)
None — Do not use any DocType to parse the document. Instead, display the raw segment without showing any of them as Document
To parse the document, set the options described above and click OK. The Document Viewer displays the following on the right side of the screen:
A summary of the document which contains following basic information:
The Data Transformation applied, if applicable
The Document ID
The DocType
The DocType description, if available
The number of segments
The Document ID of parent documents, if applicable
The document data, which has one row for each segment in the document structure. Each row contains:
Segment number
Segment name, such as ISA or DN1
Element contents and separators, as contained in the document
If the document matches the schema you have selected, segments and elements appear as links to the relevant structure page.
Due to the multiplicity of X12 DocType structures that use the same transaction set identifier code (ST:1), InterSystems IRIS checks the additional reference identification numbers ST:3, GS:8, or REF:2 and uses the first implementation guide version number found to uniquely identify document types. For example, examine HIPAA_4010:837P and HIPAA_4010:837D. Both documents have a transaction set identifier of 837, however each has a distinct reference identification number. See Implementation Guide.
Displaying the Segment Address
To display the segment address, hover the cursor over a segment name in the shaded column. The tooltip displays the following:
Segment address to use in a virtual property path
Descriptive name of this segment
Displaying the Element Address
To display the Element address, hover the cursor over a field within the document structure. The tooltip displays the following:
The element address to use in a virtual property path (as a number)
The element address to use in a virtual property path (as a name)
Viewing X12 Interchanges
When viewing Transaction Sets nested in Groups and Interchanges the Interoperability > Interoperate > ASC X12 > ASC X12 Document Viewer page allows you to walk through the document structure one level at a time.
The following display is the result of using the X12 document viewer to view a 4010:Interchange document.
The Document Viewer assigns the group document the identifier <38>.
When you click on a group document link in an X12 Interchange document display, a new browser window opens to display the group document. The document Viewer window, with the top-level parent, remains open in the original browser window.
The next display is the result of clicking the link to Group document <38>.
If there are more than 10 Groups in an Interchange or more than 10 Transaction Sets in a Group, the Document Viewer displays links to the first five and last five documents. Between the lists is a text field, into which you can enter any identifier number between the first and last numbers. After you enter a number, click Other. A new browser window opens to display the document.
The next display is the result of clicking the Transaction Set <39>. You can return to either the Group or the Interchange by clicking their respective Document ID number links.
When you are done viewing documents in the batch document hierarchy, you can close all the pop-up browser windows until the top-level parent document remains in the original document Viewer window. From here, you may return to other Management Portal activities.
Testing a Transformation
To test a transformation:
Check.
X12 Classes
For reference, this section lists the classes that InterSystems IRIS provides to enable you to work with X12 documents.
*When you configure a production to work with X12 documents, the Management Portal automatically selects the appropriate business host class.
You can also create and use subclasses of these classes.
The business host classes include configurable targets. The following diagram shows some of them:
For information on other configurable targets, see “Reference for Settings.”
Creating Custom X12 Schemas
You can create custom X12 schemas in any of the following ways:
Create a .x12 file using the Eclipse XML editor.
Import an existing schema using the X12 Schemas Management Portal page. Select Interoperability > Interoperate > ASC X12 > ASC X12 Schema Structures to get to the X12 Schemas page.
Create an XML file in Studio and give it an .x12 extension.
You are now ready to edit your file to add and remove XML statements from the <Category> block. The basic editing steps are as follows:
Define custom segments using <SegmentStructure> elements.
Define custom <MessageStructure> elements that contain the custom segments.
Define custom <MessageType> elements that contain the custom message structures.
Try viewing the new category definition from the Management Portal. See Portal Tools.
For information on creating custom schema categories, see “Creating Custom Schema Categories” in Using Virtual Documents in Productions.
Defining X12 Search Tables
The X12 search table class, EnsLib.EDI.X12.SearchTable, automatically indexes the X12 document ID, which it gives the name Identifier.
If you need more items to search, you can create a subclass. The subclass inherits the Identifier property, plus the infrastructure that makes search tables work. For details, see “Defining a Search Table Class” in Using Virtual Documents in Productions.
Be sure to perform all tasks in the same namespace that contains your production. Do not use reserved package names; see “Reserved Package Names” in Developing Productions. Also see “Overriding the Validation Logic” in Using Virtual Documents in Productions.