EDI in Dictionary Builder
This section provides practical instructions for modifying
a dictionary in the EDI data format using the Dictionary Builder
interface. For more information on EDI and how to process EDI documents
using iWay Service Manager, see the iWay Integration Solution
for EDI User's Guide.
x
The metadata components required for any iWay project
in which EDI is the input or output data format are dictionary structure
and header.
Because these metadata components provide XML representation
of a specific EDI transaction, you must create the dictionary to
exactly match the structure of the specific transaction.
To open the standard EDI X12 Ebix Entry project that is presented
as an example in this section, download the X12_4010 package from
the following Web site, which is hosted and maintained by iWay Software:
http://iwse.ibi.com/iway60/ebiz/ism60/
When you open the X12_4010 package using iWay Transformer, ensure
that you select the Ebix Entry for 850 (Purchase Order) message.
The instructions in this section assume that you are familiar
with EDI, XML, and the specific EDI transaction with which you are
working. The Dictionary Builder facility enables you to design the
EDI metadata without having to manually write or edit XML syntax.
This section demonstrates how your metadata is being generated from
the graphical structure in Dictionary Builder.
Be careful when making modifications to documents in Dictionary
Builder. Published document standards allow documents to be traded
easily between trading partners by establishing and agreeing to
document footprints. If you add an element or segment, your partner
may not be able to read your document. If you decide to allow a
qualifier that is not in the published standard, your partner may
reject your document for non-compliance. There are several commercial
products available that can read and validate EDI documents. You should
validate all data after transformation to be sure that it is still
standards-compliant.
Dictionary Builder uses a combination of the following components
to represent the structure of a dictionary:
Component | Description |
|---|
Transaction
Set | Message type described in the dictionary,
which contains a combination of loops and segments. Transaction
sets cannot repeat. Note: The Transaction Set cannot
be empty. It must include at least one segment or loop. |
Loop | Logical group of segments or loops. A loop
can repeat within the document. |
Segment | Token of the document, which can contain
data elements and composite elements. A segment can repeat within
the loop. |
Composite
Element | Logical data element contained in the segment.
It can contain the component elements and can repeat within the segment. |
Element | Component value contained in the segment. |
Component Element | Component value contained in the composite
element. |
Note: EDI dictionary headers are written using the same
guidelines that are provided here for dictionary components, but
without the Transaction Set node.
The hierarchy of a Transaction Set is outlined in the following
diagram.
Note: The arrows on the diagram indicate an aggregation
(also called "has-a") type of relationship between a Transaction
Set and its subordinate components, Segments, and Loops. The numbers
indicate the minimum and maximum number of components allowed for
the EDI message.
The hierarchy of a Segment is outlined in the following diagram.
Note: The arrows on the diagram indicate an aggregation
(also called "has-a") type of relationship between a Segment and
its subordinate components, Elements, Composite Elements, and Component
Elements. The numbers indicate the minimum and maximum number of
components allowed for the EDI message.
The hierarchy of a Loop is outlined in the following diagram.
Note: The arrows on the diagram indicate an aggregation
(also called "has-a") type of relationship between a Loop and its
subordinate components, Loop and Segment. The numbers indicate the
minimum and maximum number of components allowed for the EDI message.
The following image shows the layout of standard dictionary EDI
X12 4010 850 (Purchase Order) as displayed on the Layout pane of
the Dictionary Builder interface. You can customize the layout according
to your requirements.
Note: To view the properties of a dictionary component
node in the Layout pane, right-click the node and select Properties from
the context menu, as shown in the following image.
Alternatively, you can double-click the node to view the properties.
The Component Node Properties window opens.
After you finish viewing the dictionary component node properties,
click OK to return to the Layout pane.
x
The necessary set of comments for your metadata are
included automatically by Transformer when you build your dictionary
using the Dictionary Builder interface, for example:
<!-- Title = EDI Transaction Dictionary by Transaction Set -->
<!-- Transaction = 276 Health Care Claim Status Request -->
Comments do not affect your overall EDI structure. As with any
XML document, a comment must begin with <!-- and end with -->.
A comment can contain any sequence of characters except the double
hyphen (--), which is only permitted to close the comment.
x
The EDI node is located at the Root of your structure's
hierarchy. The following table lists attribute properties for the
EDI node, and indicates which properties are necessary to be defined
in compliance with the iWay EDI specification.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
|
|
|
Type
|
|
|
Version
|
|
|
Standard
|
|
|
Note
|
|
Note: The Type attribute specifies the encoding type of
your EDI transaction document. The default encoding type is ASCII.
In the following image, the EDI node is displayed in the Layout
pane of Dictionary Builder. The Item Properties pane on the bottom
provides a list of attribute properties for the EDI node.
To modify an attribute's value, double-click the corresponding
row in the Value column.
x
The Transaction Set node is always positioned as a child
object of the EDI node. The following table lists the corresponding
attribute properties for the Transaction Set.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
|
|
|
Note
| |
Optionally, you can insert the information for your own reference
into the value for the Note attribute.
For example, for a standard dictionary of the EDI X12 4010 850
(Purchase Order) transaction, the Transaction Set opening tag (node)
would be defined in the syntax with values for the Name (850) and
Description (Purchase Order) attribute properties.
In the following image, the Transaction Set node is shown in
the Layout pane of Dictionary Builder. The Item Properties pane
on the bottom provides a list of attribute properties for the highlighted
850 Transaction Set node.
To modify an attribute's value, double-click the corresponding
row in the Value column.
x
A Segment node is always a child element of either a
Transaction Set or Loop node. The following table lists the corresponding
attributes for the Segment node.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
|
|
|
Type
| |
|
Req
|
|
|
MaxUse
|
|
|
Note
| |
The Name attribute provides a two or three character length
value that identifies the Segment in the dictionary document tree
node, for example, DTM.
The Description attribute provides a description of the
Segment node, for example, Date/Time Reference.
The Req attribute defines the requirement for the occurence
of the segment, which can be either 'M' (mandatory), 'O' (optional),
or 'N' (not used).
The MaxUse attribute sets the maximum allowed number of
occurrences of the Segment, which is set to null if the Segment
is allowed to exist an indefinite number of times.
Two optional attributes, Note and Type exist for
the Segment node. A value supplied to Note contains information
you can supply for your own reference. When multiple loops with
the same name exist in your transaction, the type attribute is used
to differentiate between the loops. For more information, see Segment Type Attribute.
For example, if you wish to add an ST segment, (Transaction Set
Header), which is mandatory and can only occur once, the Segment
opening tag (node) would be defined in the syntax with values for
the Name, Description, Req, and MaxUse attributes.
In the following image, the highlighted ST Segment node is shown
in the Layout pane of Dictionary Builder. The Item Properties pane
on the bottom provides a list of attribute properties for the ST
Segment.
To modify an attribute's value, double-click the corresponding
row in the Value column and type the new value.
x
The Type attribute is used to define a rule on a segment
that has the same first segment. For example, your dictionary may
have sibling loops 2000A and 2000B that both have a segment with
ID="HL" as their first child segment. In this case, the Type attribute
has to be added to these HL segments in order to determine which
loop of the input data they belong to.
The Type attribute specifies a condition that is always true
for the segment to which it belongs and is unique to the loop the
segment is contained in. The condition could contain information
about one of the segment elements, such as its value or whether
this element exists in the segment. If the condition is based on
the existence of a child element value, it can be entered in either
of the two following ways:
- Type is equal
to ElementID indicates that child element
with specified ID has a value.
- Type is equal
to !ElementID indicates that child element with
specified ID has a null value.
If the condition is based on the value of a child element, it
can be entered in either of the two following ways:
- Type is equal
to "ElementID=='value'"
indicates that child element with specified ID has given value.
- Type is equal
to "ElementID!='value'"
indicates that child element with specified ID does not have given
value.
For example, you may know that the third element of segment HL
always has value '20' for loop 2000A and always has value '21' for
loop 2000B. In this case, you would add Type="03=='20'" to segment
HL in loop 2000A and Type="03=='21'" to segment HL in loop 2000B.
x
A Loop node is always positioned as a child object of
either a Transaction Set node or another Loop node. The following
table lists the corresponding attribute properties for the Loop.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
| |
|
Req
| |
|
MaxUse
|
|
|
Type
| |
|
Note
| |
The MaxUse attribute is set to null if the loop is allowed to
repeat an infinite number of times. Optionally, you can add a Req
attribute, which value would determine whether the particular loop
is required to be present in this position within the message. The
values for Req can be either 'M' (mandatory), 'O' (optional), or
'N' (not used). If you do not specify this attribute, the loop is
considered optional by default.
For example, if you create a loop with the Name SG0 that can
be repeated as many times as required, the Loop opening tag (node)
would be defined in the syntax with value “SG0” for the Name and
value “99999” for MaxUse attributes.
x
An Element node is always a child element of a Segment
node. The following table lists the corresponding attributes for
the Element node.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
|
|
|
Req
|
|
|
MinLength
|
|
|
MaxLength
|
|
|
Pad
| |
|
PadChar
| |
|
Align
| |
|
Type
|
|
|
Domain
|
|
The Name attribute supplies a numerical value based on
the Element position within its parent segment.
Elements and Composite Element Names are given as ID values sequentially
within their parent segment. For example, if a segment contains
the sequence of two Elements, one Composite Element, followed by
another Element, the respective ID values for these components would
be 01, 02, 03, and 04.
The Description attribute provides a description for the
Element node.
The Req attribute defines the requirement for the occurence
of this element within the parent segment.
It must have values of either 'M' (mandatory), 'O' (optional),
or 'N' (not used). For more information, see Req: Conditional Requirement.
The MinLength attribute sets the minimum length permitted
for the Element.
The MaxLength attribute sets the maximum length permitted
for the value of the Element.
The Pad attribute allows you to enable or disable padding
by selecting True or False from
the drop-down list.
The PadChar attribute allows you to specify the character
that will be used for padding, for example, an underscore character
“_”. This attribute is used only if padding is enabled.
The Align attribute allows you specify the alignment of
the padding by selecting Left or Right from
the drop-down list.
The Type attribute specifies the type of the value to
be contained within the Element node.
The attribute can take one of the following values:
-
AN - string
Means
that the element can contain a sequence of any characters from the
basic or extended character sets.
-
DT - date
Means
that the element value can be in format YYYYMMDD or YYMMDD, depending
upon the MinLength and MaxLength attributes.
-
ID - identifier
Means
that the element can contain a value from a pre-defined list of
codes that is maintained by the ASC X12 Committee.
-
Nn - numeric (when
implemented, takes on an integer value; for example, N0 or N2 both
work).
Means that the element can contain a numeric value
with an implied decimal point position from the right. For example,
a transmitted value of 789, when specified as numeric type N2, represents
a value of 7.89. A leading minus sign (-) is used to indicate a
negative value.
-
R - decimal
Means
that the element can contain an explicit decimal point (unlike Type
Nn) in its value, if the value is not an integer value. For example,
a transmitted value of 7.89 when specified as type, R, represents
a value of 7.89. A leading minus sign (-) is used to indicate a
negative value.
-
TM - time
Means
that the element can be in general format HHMMSSd..d (where d are
the decimal seconds), and the precise format is determined by the
MinLength and MaxLength attributes. For example, transmitted data
of four characters denotes HHMM, and for the six characters it would
denote HHMMSS. Transmitted data of nine characters denotes HHMMSSddd.
For
example, if you wish to add a mandatory element as the first element
in a segment, then your element and the description of the element
should be “Transaction Set Identifier Code”. The alphanumeric value
should contain with it a minimum and maximum length of three as
shown in the following image.
x
Req: Conditional Requirement
If the requirement for the occurence of an Element or
Composite Element depends upon the outcome of another condition,
then its Req attribute must be defined as a conditional requirement.
This requirement always evaluates to one of 'M' (mandatory), 'O' (optional),
or 'N' (not used). A conditional requirement must be supplied in
the following way:
condition, trueReq, falseReq
A condition is comprised of terms, relational operators, and
conditional operators. Terms can be either sibling element IDs (for
example, 04 or 12), or constant values (for example, 3 or foo).
Relational Operators
The following table describes the relational operators supported
for EDI conditional requirements, gives an example of each, and
indicates when an operator returns "true."
Operator | Meaning | Example | Returns true if |
== | Is equal to | 01=='A' | Sibling element 01 has a value equal to 'A'. |
!= | Is not equal to | 02!='9' | Sibling element 02 has a value not equal
to '9'. |
> | Is greater than | 03>'81' | Sibling element 03 has a value greater than '81'. |
< | Is less than | 04<'729' | Sibling element 04 has a value less than '729'. |
Conditional Operators: Listed From Highest to Lowest Precedence
The following table describes the conditional operators, gives
an example of each, and indicates when an operator returns "true."
Operator | Meaning | Example | Returns true if |
<elementID> | Sibling element with given ID exists | 01 | Value exists for sibling element 0.1. |
! | Not | !02 | Value does not exist for sibling element
02 (value is null). |
&& See note* | And | 03&&11 | Values exists for both sibling elements
03 and 11. |
|| | Or | 08||26 | Value exists for either sibling element
08 or 26, or both values exist. |
Note: && replaces
the standard logic operator “&&” due to the special character
status given to the “&” character in XML.
You apply the trueReq requirement if the given condition evaluates
to true. This can only take the value 'M', 'O', or 'N' and cannot
be the same as the value given to falseReq.
You apply the falseReq requirement if the given condition evaluates
to false. This can only take the value 'M', 'O', or 'N' and cannot
be the same as the value given to trueReq.
x
A Composite Element node is always a child element of
a Segment node. The following table lists the corresponding attributes
for the Composite Element node.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
|
|
|
Req
|
|
|
Note
| |
The Name attribute is a numerical value based on the Composite
Element position within its parent segment.
Elements and Composite Elements are given ID values sequentially
within their parent segment. For example, in a segment containing
two Elements, one Composite Element, and another Element, the respective
ID values would be 01, 02, 03, and 04.
The Description attribute provides a description for the
Composite Element node.
The Req attrribute defines the requirement, which can
be either 'M' (mandatory), 'O' (optional), or 'N' (not used).
For example, if you need to add a mandatory Composite Element
whose name is "Composite Medical Procedure Identifier" as the first
child in a segment, the Composite Element opening node would be
defined with particular attributes for the Name, Description, and
Req attributes, as displayed in the following image. The Item Properties
pane on the bottom provides a list of attribute properties for the
01 Composite Element node.
To modify an attribute's value, double-click the corresponding
row in the Value column and type the new value.
x
A Component Element node is always a child element of
a Composite Element node. The following table lists the corresponding
attributes for the Component Element node.
|
Attribute
|
Required
|
|---|
|
Name
|
|
|
Description
|
|
|
Req
|
|
|
Type
|
|
|
MinLength
|
|
|
MaxLength
|
|
|
Pad
| |
|
PadChar
| |
|
Align
| |
|
Note
| |
|
Domain
| |
Optionally, you can add an attribute, Note, whose value contains
information for your own reference.
The Name attribute is a numerical value based on the Component
Element position within its parent Composite Element.
For example, the first Component Element must have ID="01" and
the fourth must have ID="04".
The Description attribute provides a description for the
Component Element node.
The Req attribute defines the requirement.
It must be either 'M' (mandatory), 'O' (optional), 'N' (not used),
or a conditional requirement. For more information, see Req: Conditional Requirement.
The Type specifies the type of content that the Component
Element node can hold. The permitted values are:
-
AN - string
Means
that the element can contain a sequence of any characters from the
basic or extended character sets.
-
DT - date
Means
that the element value can be in format YYYYMMDD or YYMMDD, depending
upon the MinLength and MaxLength attributes.
-
ID - identifier
Means
that the element can contain a value from a predefined list of codes
that is maintained by the ASC X12 Committee.
-
Nn - numeric (when
implemented, takes on an integer value; for example, N0 or N2)
Means
that the element can contain a numeric value with an implied decimal
point n positions from the right. For example, a transmitted value
of 789 when specified as numeric type N2 represents a value of 7.89.
A leading minus sign (-) indicates a negative value.
-
R - decimal
Component
Element can contain real (numeric) numbers if the value is not an integer
value. For example, a transmitted value of 7.89 when specified as
type R represents a value of 7.89. A leading minus sign (-) indicates
a negative value.
-
TM - time
Component
Element value is in general format HHMMSSd..d (where d are decimal seconds),
and the precise format is determined by the MinLength and MaxLength attributes.
For example, transmitted data of four characters denotes HHMM, and
six characters denotes HHMMSS. Transmitted data of nine characters
denotes HHMMSSddd.
The MinLength attribute sets the minimum length permitted
for the Component Element content.
The MaxLength attribute sets the maximum length permitted
for the Component Element content.
The Pad attribute allows you to enable or disable padding
by selecting True or False from
the drop-down list.
The PadChar attribute allows you to specify the character
that will be used for padding, for example, an underscore character
“_”. This attribute is used only if padding is enabled.
The Align attribute allows you specify the alignment of
the padding by selecting Left or Right from
the drop-down list.
For example, if you want to add an optional Component Element
that has alphanumeric content with minimum and maximum lengths of
two, and whose name is "Procedure Modifier" as the first element
in a Composite Element, the Component Element tag (node) would be
defined in the syntax with values for the required attributes.
A Component Element tag (node) cannot contain any children.
In the following image, the 01 Component Element node is displayed
in the Layout pane of Dictionary Builder. The Item Properties pane
on the bottom provides a list of attribute properties for the 01
Component Element node.
To modify an attribute's value, double-click the corresponding
row in the Value column and type the new value.